More readme/instructions; LED->backlight (w/untested non-PWM support)

Author: clockspot

INSTRUCTIONS.md

@@ -4,7 +4,7 @@ Your clock has four main functions: [time of day](#time-of-day), [calendar](#cal
 
 To set anything, simply hold **Select** until the display blinks; use **Up/Down** to set, and **Select** to save.
 
-Additional settings are available in the [settings menu](#settings-menu). If you have a Wi-Fi-enabled clock, you can configure these settings (and more) on the [settings webpage](#wi-fi-support), where you can also configure the clock to set itself.
+Additional settings are available in the [settings menu](#settings-menu). If you have a Wi-Fi-enabled clock, you can configure these settings (and more) on the [settings page](#wi-fi-support), where you can also configure the clock to set itself.
 
 ## Time of day
 
@@ -74,7 +74,7 @@ If your clock has _neither_ a switch signal nor [Wi-Fi support](#wi-fi-support),
 * To enter the settings menu, hold **Select** for 3 seconds until the hour displays `1`. This indicates option number 1.
 * Use **Up/Down** to go to the option number you want to set (see table below); press **Select** to open it for setting (display will blink); use **Up/Down** to set; and **Select** to save.
 * When all done, hold **Select** to exit the menu.
-* If you have a Wi-Fi-enabled clock, you can configure these settings (and more) on the [settings webpage](#wi-fi-support).
+* If you have a Wi-Fi-enabled clock, you can configure these settings (and more) on the [settings page](#wi-fi-support).
 
 |  | Option | Settings |
 | --- | --- | --- |
@@ -121,19 +121,21 @@ To reset the clock to “factory” settings, hold **Select** for 15 seconds whi
 
 ## Wi-Fi support
 
-If your clock is Wi-Fi-enabled, it provides a settings webpage that duplicates the settings menu above (and more), and it can set itself by synchronizing to an [NTP time server](https://en.wikipedia.org/wiki/Time_server). To use NTP sync, use the webpage to supply the credentials for your Wi-Fi network.
+If your clock is Wi-Fi-enabled, it offers a settings webpage that duplicates the menu above (and more), and can set itself by synchronizing to an [NTP time server](https://en.wikipedia.org/wiki/Time_server).
 
-To access the settings webpage, grab a device with a web browser, and briefly hold **Alt**.
+To access the settings page, grab a device with a web browser, and briefly hold **Alt**.
 
 * If the clock **is not** connected to Wi-Fi, it will display `7777`.
-	* This indicates the clock is broadcasting a Wi-Fi access point called “Clock”. Connect your device to “Clock” and browse to [7.7.7.7](http://7.7.7.7).
+	* This indicates it is broadcasting a Wi-Fi network called “Clock.” Connect your device to “Clock” and browse to [7.7.7.7](http://7.7.7.7).
 
 * If the clock **is** connected to Wi-Fi, it will flash its IP address (as a series of four numbers).
-	* Connect your device to the same Wi-Fi network, and browse to that IP address.
-	* If you don't know what Wi-Fi network the clock is connected to, hold **Alt** for 10 seconds. It will disconnect from that network and broadcast the “Clock” access point, as above.
+	* Connect your device to the same Wi-Fi network as the clock, and browse to that IP address.
+	* If you don’t know what Wi-Fi network the clock is connected to, hold **Alt** for 10 seconds. It will disconnect from that network and broadcast the “Clock” access point, as above.
 
-For security, the clock will stop serving the settings page (and “Clock” access point, if applicable) after two minutes of inactivity.
+If you change the Wi-Fi settings, the clock will immediately attempt to (re)connect, and will display its IP address if successful, or `7777` if not. To continue configuring the clock, reconnect to it as above.
 
-When NTP sync is enabled, the clock will attempt to synchronize itself every hour (at minute 59). The settings webpage will indicate how recently the clock was last synced.
+For security, the settings page (and “Clock” network if applicable) will stop after two minutes of inactivity.
 
-**If the clock displays the time without seconds,** this indicates it was unable to sync in the last 24 hours. Check to make sure the clock is connected to Wi-Fi and configured to use a valid NTP server, and try a manual sync. If no Wi-Fi is available or you're unable to sync for other reasons (such as network limitations), disable Wi-Fi or NTP sync to restore the seconds display.
+When NTP sync is enabled, the clock will attempt to synchronize every hour (at minute 59). The settings page will indicate how recently the clock was last synced.
+
+**If the clock displays the time without seconds,** this indicates it was unable to sync in the last 24 hours. Check to make sure the clock is connected to Wi-Fi and configured to use a valid NTP server, and try a manual sync. If no Wi-Fi is available or you’re unable to sync for other reasons (such as network limitations), disable Wi-Fi or NTP sync to restore the seconds display.

README.md

@@ -4,69 +4,55 @@
 
 ## Operating instructions
 
-[The latest operating instructions (v2.0+) can be found here.](https://github.com/clockspot/arduino-clock/releases)
+[The latest operating instructions (v2.0+) can be found here.](https://github.com/clockspot/arduino-clock/blob/master/INSTRUCTIONS.md)
 
-[Instructions for earlier versions are here.](https://github.com/clockspot/arduino-nixie/releases)
+[Instructions for earlier versions are here.](https://github.com/clockspot/arduino-clock/releases)
 
 To see your clock’s software version, hold **Select** briefly while powering up the clock.
 
 ## About
 
-**A universal digital clock codebase for Arduino.**
+**A universal digital clock codebase for Arduino,** maintained by [Luke](https://theclockspot.com).
 
-* Time of day with automatic DST change, display shutoff, and chimes.
+* Time of day with automatic DST change and chimes.
 * Perpetual calendar with day counter and local sunrise/sunset times.
-* Alarm with snooze and automatic weekday/weekend skipping.
-* Chronograph and timer with interval and reset options.
-* Signals via piezo beeper, switch (appliance timer), pulse (bell ringer), and switchable backlighting.
-* Supports Nixie displays of four/six digits, multiplexed in pairs via two SN74141 driver chips.
-* Supports LED displays of three or four MAX7219 chips (via SPI) driving 8x8 LED matrices (example).
+* Daily alarm with snooze and automatic weekday/weekend skipping.
+* Chronograph and timer with reset/interval options.
+* Simple control via three/four buttons, a rotary encoder, and/or an [IMU](https://en.wikipedia.org/wiki/Inertial_measurement_unit) (tilt control).
+* Signals via piezo beeper, switch (e.g. appliance timer), and/or pulse (e.g. bell ringer).
+* Supports Nixie displays of two SN74141 chips driving four/six tubes, with anti-cathode poisoning.
+* Supports LED displays of three/four MAX7219 chips (via SPI) driving 8x8 LED matrices ([example](https://www.amazon.com/HiLetgo-MAX7219-Arduino-Microcontroller-Display/dp/B07FFV537V/)).
+* Supports scheduled display dim/shutoff and switchable backlighting with optional PWM fade.
 * Timekeeping can be internal, or based on a DS3231 RTC (via I2C) for reliability/accuracy.
 * Supports both AVR and SAMD Arduinos (tested on Arduino Nano and Nano 33 IoT).
-* On Nano 33 IoT, supports Wi-Fi connectivity with web-based config and NTP sync.
+* On Nano 33 IoT, supports Wi-Fi connectivity with web-based config and automatic NTP sync. 
 
-Originally written for [RLB Designs’](http://rlb-designs.com/) Universal Nixie Driver Board (UNDB):
+Written to support [RLB Designs’](http://rlb-designs.com/) Universal Nixie Driver Board (UNDB):
 
 * Backlighting (PWM LED) supported on UNDB v8+
 * Switch and pulse signals supported on UNDB v9+
 * Nano 33 IoT support coming on future versions
 
-[The latest release can be downloaded here.](https://github.com/clockspot/arduino-nixie/releases/latest)
+[The latest release can be downloaded here.](https://github.com/clockspot/arduino-clock/releases/latest)
 
-# Hardware configuration
+# Configuration, compilation, and upload
 
-A number of hardware-related settings are specified in a config file, so you can easily maintain multiple hardware profiles in their own config files, and include the relevant config at the top of the sketch before compiling. 
+Various options, such as enabled functionality, RTC, display, I/O pins, timeouts, and control behaviors, are specified in a config file. This allows you to maintain multiple configs for various clock hardware profiles, and simply include the relevant config at the top of the `.ino` before compiling. Several [example configs](https://github.com/clockspot/arduino-clock/tree/master/arduino-clock/configs) are provided, and [`~sample.h`](https://github.com/clockspot/arduino-clock/blob/master/arduino-clock/configs/%7Esample.h) includes all possible options with detailed comments.
 
-These settings include:
+You may also wish to adjust the defaults for the clock’s user-configurable values, to best suit its intended use; these defaults are currently specified in the main code (`optsDef[]` for [settings](https://github.com/clockspot/arduino-clock/blob/master/INSTRUCTIONS.md#settings-menu) and `initEEPROM()` for other values).
 
-* **Number of digits** in the display module. Default is 6; small display adjustments are made for 4-tube clocks.
-* **Which functions** are enabled (calendar, alarm, etc).
-* **Which pins** are associated with the inputs (controls) and outputs (displays and signals).
-  * If your clock includes LED backlighting (e.g. UNDB v8+), specifying an LED pin will enable the LED-related options in the options menu. LEDs should be connected to a PWM pin.
-* **What type of Up/Down controls** are equipped: pushbuttons (default) or rotary encoder (TBD).
-* **What type of signal outputs** are equipped: a piezo beeper (default) and/or a relay.
-  * **Signal duration** (default 3min) and **piezo pulse duration** (default 500ms)
-  * If your clock includes a relay (e.g. UNDB v9+), specifying a relay pin will enable the relay-related options in the options menu. You can also specify the **relay mode**:
-    * In switched mode (default), the relay will be switched to control an appliance like a radio or lamp. If used with timer, it will switch on while timer is running (like the “sleep” function on a clock radio). If used with alarm, it will switch on when alarm trips and stay on for **relay switch duration** (default 2 hours). In this case, the **Alt** button (if equipped) will shut it off immediately, skipping snooze. This mode also enables the option for the LED backlighting, if equipped, to switch with the relay (great for a radio!).
-    * In pulse mode, the relay will be pulsed, like the beeper is, to control an intermittent signaling device like a solenoid or indicator lamp; specify **relay pulse duration** (default 200ms).
-* **Soft alarm switch** enabled: default is yes; it is switched with **Up** (on) and **Down** (off) while viewing the alarm time. Change to no if the signal output/appliance has its own switch on this relay circuit; the software alarm will be permanently on.
-* **Soft power switch** enabled (switched relay only): default is yes; appliance can be toggled on/off with **Alt**. Change to no if the appliance has its own power switch (independent of this relay circuit) or does not need to be manually switched. (If set to no, or not using a switched relay, **Alt** acts as a function preset, as above.)
-* **Various other durations** for things like scrolling speed, set function/display timeouts, short and long button holds, “hold to set faster” thresholds, etc.
+I use the Arduino IDE to compile and upload, due to the use of various Arduino and Arduino-oriented libraries. Make sure the relevant libraries are installed in the Library Manager, per the config in use.
 
-You can also set the **defaults for the options menu** (in main code, currently) to better suit the clock’s intended use.
+* EEPROM (Arduino) for AVR Arduinos (e.g. original Nano)
+* SPI (Arduino) and [LedControl](http://wayoda.github.io/LedControl) for MAX7219-based displays
+* [Encoder](https://github.com/PaulStoffregen/Encoder) if rotary encoder is used for Up/Down inputs
+* Arduino_LSM6DS3 (Arduino) if using Nano 33 IoT’s IMU for inputs
+* WiFiNINA and WiFiUdp (Arduino) for Wi-Fi and NTP sync support on Nano 33 IoT
+* Wire (Arduino) and [DS3231](https://github.com/NorthernWidget/DS3231) if using DS3231 RTC (via I2C)
+* [Dusk2Dawn](https://github.com/dmkishi/Dusk2Dawn) if sunrise/sunset display is enabled
+  * Note: At this writing, for Nano 33 IoT, it’s necessary to download this library as .ZIP and [add manually](https://www.arduino.cc/en/guide/libraries#toc4), as the version in the Library Manager [is old](https://forum.arduino.cc/index.php?topic=479550.msg3852574#msg3852574) and, in my experience, will not compile for SAMD.
 
-## Compiling the sketch
+Before compiling and uploading, you will need to select the correct board, port, and (for AVR) processor in the IDE’s Tools menu.
 
-The author uses the Arduino IDE to compile, due to the use of various Arduino and Arduino-oriented libraries. Install them via the Library Manager as applicable (except where indicated otherwise).
-
-* Wire (Arduino)
-* EEPROM (Arduino) - for AVR-based Arduinos
-* SPI (Arduino) and [LedControl](http://wayoda.github.io/LedControl) by Eberhard Farle - for MAX7219-based displays
-* Arduino_LSM6DS3 (Arduino) - if using Nano 33 IoT's IMU (Inertial Measurement Unit) for inputs
-* WiFiNINA and WiFiUdp (Arduino) - for Nano 33 IoT Wi-Fi and NTP sync support
-* [DS3231](https://github.com/NorthernWidget/DS3231) by NorthernWidget - if using DS3231 for timekeeping
-* [Dusk2Dawn](https://github.com/dmkishi/Dusk2Dawn) by DM Kishi - if sunrise/sunset display is enabled
-  * Note: For Nano 33 IoT, it seems necessary to download the library from source as .ZIP and [add manually](https://www.arduino.cc/en/guide/libraries#toc4), rather than add directly via the Library Manager.
-* [Encoder](https://github.com/PaulStoffregen/Encoder) by Paul Stoffregen - if rotary encoder is used for Up/Down inputs
-
-**To upload the sketch to your clock,** if it doesn’t appear in the IDE’s Ports menu (as a USB port), your UNDB may be equipped with an Arduino clone that requires [drivers for the CH340 chipset](https://sparks.gogo.co.nz/ch340.html).
+* If your Arduino does not appear as a port option, you may have a clone that requires [drivers for the CH340 chipset](https://sparks.gogo.co.nz/ch340.html).
+* If upload fails for an ATMega328P Arduino (e.g. original Nano), try selecting/unselecting “Old Bootloader” in the processor menu.