RGB LED Animations
Relevant source files
The following files were used as context for generating this wiki page:
The RGB LED animation system provides visual feedback for the device's operational state, connectivity status, and voice interaction progress. It supports various hardware backends, including standard PWM-driven RGB LEDs, addressable WS2812 LED strips, LED rings, and LCD displays that mirror LED status colors through on-screen bars or dedicated onboard LEDs. Sources: led_status.c:38-160, README.md:14-25
This system operates as a dedicated FreeRTOS task that manages state transitions and executes visual patterns such as breathing, blinking, and steady color fills. It integrates with the noise_control module to reflect connection states and the voice processing module to visualize microphone activity and agent responses. Sources: led_status.c:980-1010, noise_control.cpp:88-105
Hardware Backend Architecture
The system abstracts hardware differences through a unified API, allowing the same logic to drive multiple device types.
Backend Types
- PWM RGB: Driven via the ESP32 LEDC peripheral using three channels (Red, Green, Blue). Sources: led_status.c:203-238
- Addressable Strip (WS2812): Uses the RMT peripheral to control single or multiple LEDs. Sources: led_status.c:251-285
- Voice Ring: A 12-LED WS2812 ring used for complex voice state visualizations like level meters and comets. Sources: led_status.c:287-336
- Display Mirroring: LCD panels (ST7789, ILI9341, ST7701S) render status colors as colored bars at the top and bottom of the screen. Sources: led_status.c:338-372, README.md:14-18
Component Diagram
The diagram shows how the central manager dispatches state changes to a background task, which then communicates through an abstraction layer to specific hardware drivers. Sources: led_status.c:1164-1188
Operational States and Visual Patterns
The system defines specific colors and animations for every stage of the device lifecycle.
State Mapping Table
| State | Color | Animation | Meaning |
|---|---|---|---|
LED_STATE_BOOT | Orange | Steady | Device is starting up |
LED_STATE_BLE_ADVERTISING | Orange | Breathe | Ready for mobile app setup |
LED_STATE_PAIRING_CONFIRM | Blue | Breathe | Waiting for physical button press |
LED_STATE_WIFI_CONNECTING | Blue | Steady | Authenticating with Network/VM |
LED_STATE_WS_CONNECTED | Green | Steady/Dot | Fully connected to Muse |
LED_STATE_WS_DISCONNECTED | Yellow | Blink | Connection lost; reconnecting |
LED_STATE_ERROR | Red | Blink | Critical system error |
Sources: led_status.c:1040-1088, board-port/esp32/README.md:118-128
Pattern Logic
- Breathe: Gradually adjusts the duty cycle or brightness using a sine-like progression over a defined period (e.g., 2000ms). Sources: led_status.c:847-859
- Blink: Toggles the LED between a target color and
COLOR_OFFat specified intervals. Sources: led_status.c:840-845 - Steady: Sets a constant color level across all active channels or pixels. Sources: led_status.c:204-211
Voice Interaction Animations
When voice features are enabled, the LED system provides high-fidelity feedback for audio processing. On LED rings, this utilizes "comet" and "level meter" effects. Sources: led_status.c:882-978
Voice Animation Flow
- Listening: A level meter grows from the top of the ring down both sides based on microphone input volume.
- Thinking: A purple comet (bright head with fading tail) rotates clockwise.
- Speaking: A green "breathing" animation synced to the agent's vocal output.
- Volume Adjustment: A white arc grows clockwise to represent the current speaker volume percentage.
Sources: led_status.c:915-965
The sequence diagram illustrates the real-time update loop during a voice interaction where audio levels and state changes trigger immediate visual updates. Sources: led_status.c:1196-1224
Implementation Details
Primary Functions
led_status_init(): Allocates mutexes, initializes hardware backends, and spawns theledFreeRTOS task. Sources: led_status.c:1134-1162led_status_set_state(led_state_t state): Updates the global state variable and triggers the task to change visual patterns. Sources: led_status.c:1164-1173led_hw_set_color(rgb_t c): The low-level hardware bridge that converts RGB values into backend-specific commands. Sources: led_status.c:203-211, led_status.c:750-766
Data Structures
typedef struct {
uint8_t r, g, b;
} rgb_t;
typedef enum {
LED_STATE_BOOT,
LED_STATE_SETUP_IDLE,
LED_STATE_BLE_ADVERTISING,
// ... other states
} led_state_t;
Sources: led_status.c:177-179, led_status.h
Summary
The RGB LED animation system serves as the primary diagnostic and interaction interface for the device. By decoupling high-level states from hardware-specific implementations, the system supports a wide range of ESP32-based hardware while maintaining consistent user feedback. It ensures that critical events—such as pairing confirmation or connection errors—are immediately visible to the user through standardized color coding and animation patterns. Sources: board-port/esp32/README.md:118-128, led_status.c:1037-1093