From b1db58ee4c87b7274400a23b2da7a550a1644070 Mon Sep 17 00:00:00 2001 From: PhosphorosVR Date: Sun, 7 Sep 2025 13:07:16 +0200 Subject: [PATCH] Enhance LED status documentation and patterns in LEDManager and StateManager --- README.md | 24 +++++++ .../LEDManager/LEDManager/LEDManager.cpp | 72 +++++-------------- .../StateManager/StateManager.hpp | 16 +++-- 3 files changed, 49 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index cf292e2..050a64e 100644 --- a/README.md +++ b/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. diff --git a/components/LEDManager/LEDManager/LEDManager.cpp b/components/LEDManager/LEDManager/LEDManager.cpp index e71ddfe..b3baa4e 100644 --- a/components/LEDManager/LEDManager/LEDManager.cpp +++ b/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, diff --git a/components/StateManager/StateManager/StateManager.hpp b/components/StateManager/StateManager/StateManager.hpp index fc882d8..4541e2f 100644 --- a/components/StateManager/StateManager/StateManager.hpp +++ b/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