documentation improvements:

- moved MODELS to BRANDS
- added MODELS file generated from "make models"
- added version check info to manual
- clarified how memory options work
- fixed docs for auto-lock feature
- small code comment clarifications

6 files changed, 122 insertions, 35 deletions

diff --git a/spaghetti-monster/anduril/BRANDS b/spaghetti-monster/anduril/BRANDS
new file mode 100644
index 0000000..b74ddab
--- /dev/null
+++ b/spaghetti-monster/anduril/BRANDS
@@ -0,0 +1,9 @@
+Vendor / Model IDs for version check function
+
+Undefined	0000
+Emisar		0100 - 0199
+Noctigon	0200 - 0199
+Lumintop	0300 - 0399
+Fireflies	0400 - 0499
+Mateminco	0500 - 0599
+Sofirn		0600 - 0699
diff --git a/spaghetti-monster/anduril/MODELS b/spaghetti-monster/anduril/MODELS
index b74ddab..6697e52 100644
--- a/spaghetti-monster/anduril/MODELS
+++ b/spaghetti-monster/anduril/MODELS
@@ -1,9 +1,39 @@
-Vendor / Model IDs for version check function
-
-Undefined	0000
-Emisar		0100 - 0199
-Noctigon	0200 - 0199
-Lumintop	0300 - 0399
-Fireflies	0400 - 0499
-Mateminco	0500 - 0599
-Sofirn		0600 - 0699
+Model numbers:
+0111	emisar-d4
+0112	emisar-d4-219c
+0113	emisar-d4v2
+0114	emisar-d4v2-219
+0115	emisar-d4v2-nofet
+0121	emisar-d1
+0122	emisar-d1s
+0123	emisar-d1v2
+0131	emisar-d4s
+0132	emisar-d4s-219c
+0133	emisar-d4sv2
+0134	emisar-d4sv2-219
+0141	emisar-d18
+0211	noctigon-kr4
+0212	noctigon-kr4-nofet
+0213	noctigon-kr4-219
+0251	noctigon-k1
+0252	noctigon-k1-sbt90
+0253	noctigon-k1-12v
+0311	fw3a
+0312	fw3a-219
+0313	fw3a-nofet
+0321	blf-gt
+0322	blf-gt-mini
+0411	ff-rot66
+0412	ff-rot66-219
+0413	ff-rot66g2
+0421	ff-pl47
+0422	ff-pl47-219
+0423	ff-pl47g2
+0441	ff-e01
+0511	mateminco-mf01s
+0521	mateminco-mf01-mini
+0611	blf-q8
+0612	sofirn-sp36
+0621	blf-lantern
+Duplicates:
+Missing:
diff --git a/spaghetti-monster/anduril/Makefile b/spaghetti-monster/anduril/Makefile
index 0e0cd7b..d1e6b46 100644
--- a/spaghetti-monster/anduril/Makefile
+++ b/spaghetti-monster/anduril/Makefile
@@ -8,11 +8,13 @@ todo:
 	@egrep 'TODO:|FIXME:' *.[ch]
 
 models:
-	@echo 'Model numbers:'
-	@grep '^#define MODEL_NUMBER' cfg-*.h | perl -ne '/cfg-(.*)\.h:#define MODEL_NUMBER "(.*)"/ && print "$$2\t$$1\n";' | sort -n
-	@echo 'Duplicates:'
-	@cat cfg-*.h | grep '^#define MODEL_NUMBER' | sort | uniq -c | grep -v ' 1 ' || true
-	@echo 'Missing:'
-	@for f in cfg-*.h ; do grep --silent '^#define MODEL_NUMBER' $$f ; if [ "$$?" = "1" ] ; then echo "  $$f" ; fi ; done
+	@echo -n > MODELS
+	@echo 'Model numbers:' >> MODELS
+	@grep '^#define MODEL_NUMBER' cfg-*.h | perl -ne '/cfg-(.*)\.h:#define MODEL_NUMBER "(.*)"/ && print "$$2\t$$1\n";' | sort -n >> MODELS
+	@echo 'Duplicates:' >> MODELS
+	@cat cfg-*.h | grep '^#define MODEL_NUMBER' | sort | uniq -c | grep -v ' 1 ' || true >> MODELS
+	@echo 'Missing:' >> MODELS
+	@for f in cfg-*.h ; do grep --silent '^#define MODEL_NUMBER' $$f ; if [ "$$?" = "1" ] ; then echo "  $$f" ; fi ; done >> MODELS
+	@cat MODELS
 
 .phony: clean todo
diff --git a/spaghetti-monster/anduril/anduril-manual.txt b/spaghetti-monster/anduril/anduril-manual.txt
index ad22153..ae7510a 100644
--- a/spaghetti-monster/anduril/anduril-manual.txt
+++ b/spaghetti-monster/anduril/anduril-manual.txt
@@ -114,13 +114,17 @@ Advanced UI's ramp.
 There are four ways to access ramping mode when the light is off:
 
   - 1C: Turn on at the memorized brightness.
+    (see below for details about what "memorized" means)
+
   - 1H: Turn on at the floor level.  Let go after the light turns on to 
     stay at the floor level, or keep holding to ramp up.
+
   - 2C: Turn on at the ceiling level.
+
   - 2H: Turn on at full power, turn off when released.  (momentary turbo)
         (in Simple UI, this uses the ceiling level instead of turbo)
 
-While the light is on, a few basic actions are available:
+While the light is on, a few actions are available:
 
   - 1C: Turn off.
   - 2C: Go to or from the ceiling level.
@@ -138,6 +142,9 @@ While the light is on, a few basic actions are available:
   - 5H: Start a sunset timer.  Details are below in the Sunset Timer section.
 
   - 7H: Go to ramp config mode.
+    - Item 1: Floor level.
+    - Item 2: Ceiling level.
+    - Item 3: Number of steps (except for smooth ramp).
 
   - 10C: Activate manual memory and save the current brightness.
   - 10H: Manual memory config menu.
@@ -147,16 +154,25 @@ While the light is on, a few basic actions are available:
               Sets the timer to N minutes, where N is the number of 
               clicks.  A value of 0 (no clicks) turns the timer off.
 
-The "automatic" vs "manual" memory modes change the level the light goes 
-to with 1 click from off.  In automatic mode, it uses the last 
-brightness the user ramped to.  In manual mode, it uses the brightness 
-the user explicitly saved with 10 clicks.
+Memory determines which brightness level the light goes to with 1 click 
+from off.  There are three types of brightness memory to choose from:
+
+  - Automatic:  Always uses the last-ramped brightness.
+
+  - Manual:  Always uses the user's saved brightness.
+
+  - Hybrid:  Uses the automatic memory brightness if the light was only 
+    off for a short time, or resets to the manual memory level if it was 
+    off for a longer time.
+    The timer for this is configurable from 0 to 255 minutes.
+
+To choose a memory style, set the configuration accordingly:
 
-There is also an optional timer for manual memory, which puts it into a 
-hybrid memory mode.  This makes the light use automatic memory if it was 
-only off for a short time, or reset to the manual memory level if it was 
-off for a longer time.  The timeout value is configurable by the user, 
-from 0 to 254 minutes.
+  mem type	manual mem	manual mem timer
+  --------	----------	----------------
+  automatic	off		any
+  manual	on		zero
+  hybrid	on		non-zero
 
 
 Sunset Timer
@@ -219,12 +235,14 @@ lockout mode has two levels:
   - 2H: Light up at the highest floor level.
 
 It is also possible to make the light lock itself automatically after 
-being turned off.  To enable this, go to lockout mode and then click 10 
-times to activate the auto-lock config menu.  Then at the prompt, click 
-N times to set the auto-lock timeout to N minutes.
+being turned off.  To enable this, go to lockout mode and use a 10H 
+action to activate the auto-lock config menu.  Release the button after 
+the first blink.  Then at the prompt, click N times to set the auto-lock 
+timeout to N minutes.
 
-  - 10C: Auto-lock config menu.  Click N times to set timeout to N minutes.
-  - 10H: Turn off auto-lock.
+  - 10H: Auto-lock config menu.  Click N times to set timeout to N minutes.
+         A value of zero disables the auto-lock feature.
+         So, to turn off auto-lock, don't click at all.
 
 And on lights which have aux LEDs, there may be additional functions:
 
@@ -487,6 +505,29 @@ to 150.  A value of 1 is a special case.  It places the step halfway
 between the floor and ceiling levels.
 
 
+Version Check Mode
+------------------
+
+This allows people to see which version of the firmware is installed on 
+their light.  The format for this is (usually) 12 digits -- a date 
+followed by a model number.  YYYYMMDDBBPP
+
+  - YYYY: Year
+  - MM: Month
+  - DD: Day
+  - BB: Brand ID
+  - PP: Product ID
+
+The date is when the firmware was compiled.  If the vendor did not set 
+this value, it defaults to 1969-07-20, the date of first human contact 
+with the moon.  However, it might not be a date at all; some vendors may 
+specify a completely different type of value here.
+
+The brand/product values are also known as the model number.  These are 
+hard-coded in the source code for each light's build target, and can be 
+looked up in the "MODELS" file or by using the "make models" command.
+
+
 Protection Features
 -------------------
 
diff --git a/spaghetti-monster/anduril/config-mode.c b/spaghetti-monster/anduril/config-mode.c
index f62924a..f89a922 100644
--- a/spaghetti-monster/anduril/config-mode.c
+++ b/spaghetti-monster/anduril/config-mode.c
@@ -38,9 +38,12 @@ volatile uint8_t number_entry_value;
 //     at the prompt to set the new value to N.
 // after completing this process, config state calls the savefunc callback
 // and then returns to caller/parent state
-uint8_t config_state_base(Event event, uint16_t arg,
-                          uint8_t num_config_steps,
-                          void (*savefunc)(uint8_t step, uint8_t value)) {
+uint8_t config_state_base(
+        Event event,
+        uint16_t arg,
+        uint8_t num_config_steps,
+        void (*savefunc)(uint8_t step, uint8_t value)) {
+
     static uint8_t config_step;
     if (event == EV_enter_state) {
         config_step = 0;
diff --git a/spaghetti-monster/anduril/ramp-mode.c b/spaghetti-monster/anduril/ramp-mode.c
index b2c5102..34c2511 100644
--- a/spaghetti-monster/anduril/ramp-mode.c
+++ b/spaghetti-monster/anduril/ramp-mode.c
@@ -454,11 +454,13 @@ uint8_t manual_memory_timer_config_state(Event event, uint16_t arg) {
 // find the ramp level closest to the target,
 // using only the levels which are allowed in the current state
 uint8_t nearest_level(int16_t target) {
+    // using int16_t here saves us a bunch of logic elsewhere,
+    // by allowing us to correct for numbers < 0 or > 255 in one central place
+
+    // ensure all globals are correct
     ramp_update_config();
 
     // bounds check
-    // using int16_t here saves us a bunch of logic elsewhere,
-    // by allowing us to correct for numbers < 0 or > 255 in one central place
     uint8_t mode_min = ramp_floor;
     uint8_t mode_max = ramp_ceil;
     uint8_t num_steps = ramp_stepss[1 + simple_ui_active];