firmware/docs/sw-design.md

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.