Enhance LED status documentation and patterns in LEDManager and StateManager

README.md

@@ -122,6 +122,30 @@ If you want to dig deeper: commands are mapped via the `CommandManager` under `c
 ---
 
 ## Troubleshooting
+### LED Status / Error Patterns
+The firmware uses a small set of LED patterns to indicate status and blocking errors. When `LED_DEBUG_ENABLE` is disabled and `LED_EXTERNAL_AS_DEBUG` is enabled the external IR LED mirrors ONLY error patterns (0%/50% duty). Non‑error patterns are not mirrored.
+
+| State | Category | Repeat | Pattern (ON/OFF ms) | Meaning |
+|-------|----------|--------|---------------------|---------|
+| LedStateNone | idle | no | (off) | No activity / heartbeat window waiting |
+| LedStateStreaming | active | yes | steady on | Streaming running (UVC or Wi‑Fi) |
+| LedStateStoppedStreaming | inactive | yes | steady off | Streaming intentionally stopped |
+| CameraError | error | yes | 300/300 300/700 | Camera init/runtime failure (check sensor, ribbon, power) |
+| WiFiStateConnecting | transitional | yes | 400/400 | Wi‑Fi associating / DHCP pending |
+| WiFiStateConnected | notification | no | 150/150 x3 then off | Wi‑Fi connected successfully |
+| WiFiStateError | error | yes | 200/100 500/300 | Wi‑Fi failed (auth timeout or no AP) |
+
+Guidelines for adding new patterns:
+- Keep error patterns short, distinctive, and repeating.
+- Reserve long holds (>600ms ON) for critical failures.
+- Use non-repeating patterns to acknowledge one-shot events (e.g. successful connection).
+
+Potential future additions (not implemented yet):
+- StorageError: two long ON pulses (e.g. NVS/flash failure).
+- ConfigError: triple short pulses repeating (invalid configuration / preferences corrupt).
+- ThermalWarning: slow ramp or alternating duty (would require PWM pattern support).
+- FirmwareUpdate: progressive heartbeat (increasing ON time) while updating OTA.
+
 - UVC doesn’t appear on the host?
   - Switch mode to UVC via CLI tool, replug USB and wait 20s.
 

components/LEDManager/LEDManager/LEDManager.cpp

@@ -2,63 +2,23 @@
 
 const char *LED_MANAGER_TAG = "[LED_MANAGER]";
 
+// Pattern design rules:
+//  - Error states: isError=true, repeat indefinitely, easily distinguishable (avoid overlap).
+//  - Non-error repeating: show continuous activity (e.g. streaming ON steady, connecting blink).
+//  - Non-repeating notification (e.g. Connected) gives user a brief confirmation burst then turns off.
+// Durations in ms.
 ledStateMap_t LEDManager::ledStateMap = {
-    {
-        LEDStates_e::LedStateNone,
-        {
-            false,
-            false,
-            {{LED_OFF, 1000}},
-        },
-    },
-    {
-        LEDStates_e::LedStateStreaming,
-        {
-            false,
-            true,
-            {{LED_ON, 1000}},
-        },
-    },
-    {
-        LEDStates_e::LedStateStoppedStreaming,
-        {
-            false,
-            true,
-            {{LED_OFF, 1000}},
-        },
-    },
-    {
-        LEDStates_e::CameraError,
-        {
-            true,
-            true,
-            {{{LED_ON, 300}, {LED_OFF, 300}, {LED_ON, 300}, {LED_OFF, 300}}},
-        },
-    },
-    {
-        LEDStates_e::WiFiStateConnecting,
-        {
-            false,
-            true,
-            {{LED_ON, 400}, {LED_OFF, 400}},
-        },
-    },
-    {
-        LEDStates_e::WiFiStateConnected,
-        {
-            false,
-            false,
-            {{LED_ON, 200}, {LED_OFF, 200}, {LED_ON, 200}, {LED_OFF, 200}, {LED_ON, 200}, {LED_OFF, 200}, {LED_ON, 200}, {LED_OFF, 200}, {LED_ON, 200}, {LED_OFF, 200}},
-        },
-    },
-    {
-        LEDStates_e::WiFiStateError,
-        {
-            true,
-            true,
-            {{LED_ON, 200}, {LED_OFF, 100}, {LED_ON, 500}, {LED_OFF, 100}, {LED_ON, 200}},
-        },
-    },
+    { LEDStates_e::LedStateNone, { /*isError*/false, /*repeat*/false, {{LED_OFF, 1000}} } },
+    { LEDStates_e::LedStateStreaming, { false, /*repeat steady*/true, {{LED_ON, 1000}} } },
+    { LEDStates_e::LedStateStoppedStreaming, { false, true, {{LED_OFF, 1000}} } },
+    // CameraError: double blink pattern repeating
+    { LEDStates_e::CameraError, { true, true, {{ {LED_ON,300}, {LED_OFF,300}, {LED_ON,300}, {LED_OFF,700} }} } },
+    // WiFiStateConnecting: balanced slow blink 400/400
+    { LEDStates_e::WiFiStateConnecting, { false, true, {{ {LED_ON,400}, {LED_OFF,400} }} } },
+    // WiFiStateConnected: short 3 quick flashes then done (was long noisy burst before)
+    { LEDStates_e::WiFiStateConnected, { false, false, {{ {LED_ON,150}, {LED_OFF,150}, {LED_ON,150}, {LED_OFF,150}, {LED_ON,150}, {LED_OFF,600} }} } },
+    // WiFiStateError: asymmetric attention pattern (fast, pause, long, pause, fast)
+    { LEDStates_e::WiFiStateError, { true, true, {{ {LED_ON,200}, {LED_OFF,100}, {LED_ON,500}, {LED_OFF,300} }} } },
 };
 
 LEDManager::LEDManager(gpio_num_t pin, gpio_num_t illumninator_led_pin,

components/StateManager/StateManager/StateManager.hpp

@@ -6,15 +6,17 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/queue.h"
 
+// LED status categories
+// Naming kept stable for existing queues; documented meanings added.
 enum class LEDStates_e
 {
-  LedStateNone,
-  LedStateStreaming,
-  LedStateStoppedStreaming,
-  CameraError,
-  WiFiStateError,
-  WiFiStateConnecting,
-  WiFiStateConnected
+  LedStateNone,           // Idle / no indication (LED off)
+  LedStateStreaming,      // Active streaming (UVC or WiFi) – steady ON
+  LedStateStoppedStreaming, // Streaming stopped intentionally – steady OFF (could differentiate later)
+  CameraError,            // Camera init / runtime failure – double blink pattern
+  WiFiStateError,         // WiFi connection error – distinctive blink sequence
+  WiFiStateConnecting,    // WiFi association / DHCP pending – slow blink
+  WiFiStateConnected      // WiFi connected (momentary confirmation burst)
 };
 
 enum class WiFiState_e