document the sleep management state machine

TODO.md

@@ -1,10 +1,12 @@
+
+
+
 # High priority
 
 Items to complete before the first alpha release.
 
 * have gps implement canSleep(), print nmea for debugging and discard buffers on the way into sleep
 * implement CustomRF95::canSleep
-* document rules for sleep wrt lora/bluetooth/screen/gps.  also: if I have text messages (only) for the phone, then give a few seconds in the hopes BLE can get it across before we have to go back to sleep.
 * make gps prevent light sleep if we are waiting for data
 * wake from light sleep as needed for our next scheduled periodic task (needed for gps position broadcasts etc)
 * turn bluetooth off based on our sleep policy
@@ -225,4 +227,5 @@ Items after the first final candidate release.
 * add requestResponse optional bool - use for location broadcasts when sending tests
 * post sample video to signal forum
 * support non US frequencies
-* send pr https://github.com/ThingPulse/esp8266-oled-ssd1306 to tell them about this project
+* send pr https://github.com/ThingPulse/esp8266-oled-ssd1306 to tell them about this project
+* document rules for sleep wrt lora/bluetooth/screen/gps.  also: if I have text messages (only) for the phone, then give a few seconds in the hopes BLE can get it across before we have to go back to sleep.

docs/sw-design.md

@@ -0,0 +1,31 @@
+# Rules for sleep
+
+## Terms
+
+From lower to higher power consumption.
+
+* Super-deep-sleep (SDS) - everything is off, CPU, radio, bluetooth, GPS.  Only wakes due to timer or button press
+* deep-sleep (DS) - CPU is off, radio is on, bluetooth and GPS is off.  Note: This mode is never used currently, because it only saves 1.5mA vs light-sleep
+* light-sleep (LS) - CPU is suspended (RAM stays alive), radio is on, bluetooth is off, GPS is off.  Note: currently GPS is not turned 
+off during light sleep, but there is a TODO item to fix this.
+* No bluetooth (NB) - CPU is running, radio is on, GPS is on but bluetooth is off, screen is off.  Note: We might not need this mode
+* running dark (DARK) - Everything is on except screen
+* full on (ON) - Everything is on
+
+## Behavior
+
+### things that increase CPU activity
+
+* Once every position_broadcast_secs (default 15 mins) - the unit will wake into DARK mode and broadcast a "networkPing" (our position) and stay alive for wait_bluetooth_secs (default 30 seconds).  This allows other nodes to have a record of our last known position if we go away and allows a paired phone to hear from us and download messages.
+* Every send_owner_interval (defaults to 4, i.e. one hour), when we wake to send our position we _also_ broadcast our owner.  This lets new nodes on the network find out about us or correct duplicate node number assignments.
+* If the user presses a button we go to full ON mode for screen_on_secs (default 30 seconds).  Multiple presses keeps resetting this timeout
+* If we receive text messages, we go to full ON mode for screen_on_secs (same as if user pressed a button)
+* While in LS mode, if we receive packets on the radio we will wake and handle them and stay awake in NB mode for min_wake_secs (default 10 seconds) - if we don't have packets we need to deliver to our phone.  If we do have packets the phone would want we instead stay in DARK mode for wait_bluetooth secs.
+
+### Things that decrease cpu activity
+
+* If time since last contact by our phone exceeds phone_timeout_secs (15 minutes) and we are in DARK mode, we transition down into NB mode
+* If nothing above is forcing us to stay in a higher mode (wait_bluetooth_secs, screen_on_secs, or min_wake_secs) we will lower down
+into either LS or SDS levels.  If either phone_sds_timeout_secs (default 1 hr) or mesh_sds_timeout_secs (default 1 hr) are exceeded we will lower into SDS mode for sds_secs (or a button press).  Otherwise we will lower into LS mode for ls_secs (default 1 hr) (or until an interrupt, button press)
+
+TODO: Eventually these scheduled intervals should be synchronized to the GPS clock, so that we can consider leaving the lora receiver off to save even more power.