Add some comments and stuff

watchos/Module_Power.cpp

@@ -15,14 +15,14 @@ Module_Power::Module_Power()
 	{
 	case ESP_SLEEP_WAKEUP_EXT1: // Button press
 		// Button press
-		m_light_sleep_delay = 2000;
-		m_deep_sleep_delay = 5000;
+		m_light_sleep_delay = MODULE_POWER_INTERACTIVE_LIGHT_SLEEP_DELAY;
+		m_deep_sleep_delay = MODULE_POWER_INTERACTIVE_DEEP_SLEEP_DELAY;
 		break;
 	case ESP_SLEEP_WAKEUP_EXT0: // External RTC
 	case ESP_SLEEP_WAKEUP_TIMER: // Internal RTC
 	default:
-		m_light_sleep_delay = 100;
-		m_deep_sleep_delay = 1000;
+		m_light_sleep_delay = MODULE_POWER_NONINTERACTIVE_LIGHT_SLEEP_DELAY;
+		m_deep_sleep_delay = MODULE_POWER_NONINTERACTIVE_DEEP_SLEEP_DELAY;
 		break;
 	}
 }
@@ -65,8 +65,8 @@ void Module_Power::tick()
 	if (module_input->isAnyPressed())
 	{
 		// In case we woke up because of RTC/etc, but have since received a button press
-		m_light_sleep_delay = 2000;
-		m_deep_sleep_delay = 5000;
+		m_light_sleep_delay = MODULE_POWER_INTERACTIVE_LIGHT_SLEEP_DELAY;
+		m_deep_sleep_delay = MODULE_POWER_INTERACTIVE_DEEP_SLEEP_DELAY;
 		m_accumulator = 0;
 	}
 

watchos/Task_Battery.cpp

@@ -36,7 +36,10 @@ public:
 
 		while (this->hasEvent()) { this->popEvent(); }
 		int new_voltage = getBatteryVoltage();
-		if (voltage != new_voltage && (millis() - last_update > 1000))
+		// TODO: The voltage fluctuates enough in ADC readings that we're just kinda constantly
+		// drawing it. Rate limiting it a bit at least prevents it from stopping power management
+		// putting us to sleep (constantly drawing == constantly awake).
+		if (voltage != new_voltage && (millis() - last_update > 5000))
 		{
 			last_update = millis();
 			ui->setDirty(hwnd);

watchos/watchos_consts.h

@@ -1,47 +1,125 @@
 #ifndef CONSTS_H
 #define CONSTS_H
 
+// TODO: Actually do something useful with this.
 #define WATCHOS_DEBUG
 
+// We preallocate structs for holding our registered modules and
+// running tasks. This sets how many we support.
 #define KERNEL_MAX_MODULES									8
 #define KERNEL_MAX_TASKS									16
 
+// Each task has a ring buffer to hold pending events. This sets
+// how large that buffer is. i.e., how many events can be queued
+// between ticks for each task.
 #define EVENT_RING_SIZE										8
 
-#define MODULE_EAT											0x0001
-#define MODULE_UI											0x0002
-#define MODULE_RTC											0x0004
-#define MODULE_INPUT										0x0008
-#define MODULE_POWER										0x0010
+//////////
+// Modules
 
-#define MODULE_RTC_EVENT_MINUTE								0x0001
-#define MODULE_INPUT_EVENT_PRESS							0x0001
+// Define the IDs of modules. Use powers of two so you can mask these
+// out.
+#define MODULE_EAT											0x01
+#define MODULE_UI											0x02
+#define MODULE_RTC											0x04
+#define MODULE_INPUT										0x08
+#define MODULE_POWER										0x10
 
+//////////
+// Events
+
+// Event IDs--when an event is generated, the generating module is
+// passed as well as an ID for the type of event. The (module, event)
+// tuple specifies what happened and what the event params represent.
+#define MODULE_RTC_EVENT_MINUTE								0x01
+#define MODULE_INPUT_EVENT_PRESS							0x01
+
+//////////
+// Module - EAT (EEPROM allocation table)
+
+// Two magic bytes we expect to find at the beginning of a valid
+// and initialized eeprom
 #define MODULE_EAT_MAGIC									0x4150
+// Version constant to allow for updating the format and migrating
+// data.
 #define MODULE_EAT_VERSION									1
+// Maximum number of allocations that can be made. If this changes,
+// all data in EEPROM is invalidated.
 #define MODULE_EAT_MAX_ENTRIES								16
+// The length of the EEPROM header (magic bytes + version)
 #define MODULE_EAT_HEADER_LENGTH							4
+// The length of the allocation table (module + offset
+// for each allocation)
 #define MODULE_EAT_TABLE_LENGTH								(MODULE_EAT_MAX_ENTRIES * 2)
+// The total size of EEPROM
 #define EEPROM_SIZE											4096
 
+//////////
+// Module - UI
+
+// We pre-allocate structs to hold each rendered window. This defines
+// the maximum number of windows you can register (inclusive of root,
+// placeholder, and actual windows).
 #define MODULE_UI_MAX_WINDOWS								32
+
+// The different layout modes for windows.
+// None - Overlapping
 #define MODULE_UI_LAYOUT_MODE_NONE							0
+// Vertical Split - Laid out left to right
 #define MODULE_UI_LAYOUT_MODE_SPLIT_VERTICAL				1
+// Horizontal Split - Laid out top to bottom
 #define MODULE_UI_LAYOUT_MODE_SPLIT_HORIZONTAL				2
+
+// Whether the actual drawing and update tasks should be offloaded
+// onto the processor's other core. This improves UI responsiveness
+// as input and other events can still be processed during the loooong
+// delay waiting for the screen to update. This could cause issues if
+// data is updated during a render, however.
 #define MODULE_UI_MULTICORE_RENDERING						true
+// If we're using multicore rendering, how big should the stack be for
+// the rendering process (in bytes).
 #define MODULE_UI_MULTICORE_STACK_SIZE						10240
+
+// Value to use as the primary colour when drawing
 #define COLOUR_PRIMARY										0xFFFF
+// Value to use as the secondary colour when drawing
 #define COLOUR_SECONDARY									0x0000
+// The reason we define these is to make it easy to invert the
+// colour palette.
+
+//////////
+// Module - Input
 
+// How many buttons we allocate
 #define MODULE_INPUT_BUTTONS								4
+// Bitmask for input module events to signal which buttons are pressed
+// and provide semantic meaning.
 #define MODULE_INPUT_BUTTON_BACK							0x01
 #define MODULE_INPUT_BUTTON_MENU							0x04
 #define MODULE_INPUT_BUTTON_UP								0x08
 #define MODULE_INPUT_BUTTON_DOWN							0x10
 
-// 1000000us = 1000ms = 1 second
-// Times given from last activity
-#define MODULE_POWER_DEFAULT_LIGHT_SLEEP_DELAY_MS					2000
-#define MODULE_POWER_DEFAULT_HIBERNATE_DELAY_MS						6000
+// NOTE: The actual tie-in between hardware buttons and these semantic
+// buttons is specified in Module_Input.cpp.
+
+//////////
+// Module - Power
+
+// When a non-interactive event occurs (e.g., RTC firing) how long to
+// wait before going back to sleep.
+#define MODULE_POWER_NONINTERACTIVE_LIGHT_SLEEP_DELAY		100
+#define MODULE_POWER_NONINTERACTIVE_DEEP_SLEEP_DELAY		500
+
+// When an interactive event occurs (e.g., button press) how long to
+// wait before going back to sleep.
+#define MODULE_POWER_INTERACTIVE_LIGHT_SLEEP_DELAY		100
+#define MODULE_POWER_INTERACTIVE_DEEP_SLEEP_DELAY		500
+
+// The rationale behind this separation is that generally if someone's
+// pressed _a_ button, there's a good chance they may follow up with
+// several more button presses (e.g., scrolling through a menu). We try
+// and avoid re-running initialization 10 times to scroll through ten
+// menu items (and putting wear on flash suspending and resuming, and
+// adding delay to each press).
 
 #endif