Status Screen & UI Rendering
Relevant source files
The following files were used as context for generating this wiki page:
The Status Screen and UI Rendering system manages visual feedback for Muse gadgets. It coordinates hardware backends including RGB LEDs, LED rings, and various LCD panels to display device states, connection progress, and media content sent from Muse.
This system translates internal system states—such as BLE advertising, Wi-Fi connection progress, and active Noise sessions—into user-visible visual patterns. On display-capable boards, it renders pixel-art animations, status bars, and custom images received via the display.draw_url command.
Architecture and Backends
The system abstracts visual feedback through a unified API defined in led_status.h and implemented in led_status.c. It supports multiple hardware configurations selected via Kconfig options.
Supported Display Hardware
| Backend | Resolution | Controller | Description |
|---|---|---|---|
| Ideaspark | 170x320 | ST7789 | IPS panel on SPI |
| Waveshare C6 | 172x320 | ST7789 | LCD on SPI |
| SenseCAP Indicator | 480x480 | ST7701S | RGB bus with I2C expander |
| Cheap Yellow Display (CYD) | 320x240 | ILI9341 | SPI display with touch support |
Sources: led_status.c:75-146, README.md:16-25
State to Color Mapping
The system maps led_state_t values to specific colors and animations.
Sources: led_status.c:1016-1065, README.md:99-108
Display Rendering Logic
For boards with LCDs, the system employs a layered rendering approach. It draws status indicators (colored bars or a "connected dot") on top of other content like animations or downloaded images.
Layer Hierarchy
- Status Bars/Dot: Drawn at the top and bottom edges (10-24 rows) or as a green dot in the top-right corner when connected.
- Captions/Title: Renders printable ASCII text using a pixel font centered above the animation.
- Animation/Image: The central area displays a pixel-art animation (
happy_anim) or a full-screen image received from the Muse server.
Rendering Flow
The led_task manages the periodic update of the display. When a state change occurs, it updates the s_bar_color and triggers a redraw.
Sources: led_status.c:647-750, app.c:1584-1600
Command-Driven Content
The system handles specific Hatch commands that allow the remote server to control the UI. These are registered in noise_control.cpp and handled in app.c.
display.draw_url
This command triggers image_fetch.c to download a JPEG or raw RGB565 image from a provided URL. Once downloaded, led_status_draw_rect renders the image to the screen.
- Parameters:
url(required),row(optional offset). - Behavior: Replaces the current animation and title with the downloaded image. The status bars/dots remain overlaid on top.
display.text
Sets a short line of text to be displayed in the title area of the status screen.
- Parameters:
text(required string). - Behavior: Replaces the agent's name with the provided text and ensures the animation is visible (clearing any active image).
Sources: app.c:1270-1300, noise_control.cpp:735-800
Interaction and Feedback
On specific boards like the ESP32 CYD, the UI system integrates with input hardware to provide a cohesive experience.
Touch Input
The system uses the XPT2046 resistive touch controller on the CYD to simulate physical button presses. A separate cyd_touch_task monitors touch pressure (Z1). If the pressure exceeds a defined threshold (CYD_TOUCH_THRESHOLD), it triggers button_touch_tap(), which acts as a BOOT button press to confirm pairing or reopen setup.
Sources: led_status.c:486-535, README.md:19-22
Voice Visualization
For devices with LED rings (e.g., Home Assistant Voice PE), the system provides specific animations for voice interactions:
- Listening: A level meter grows from the top down both sides based on audio levels.
- Thinking: A purple "comet" animation rotates clockwise.
- Speaking: The ring breathes green in sync with the audio output.
- Volume: A white arc grows clockwise to show the current volume level when the dial is turned.
Sources: led_status.c:928-985
Summary
The Status Screen & UI Rendering system provides critical visibility into the gadget's operational state. By abstracting diverse hardware—from single LEDs to high-resolution LCDs—into a unified state-based API, it ensures consistent user feedback across the entire Muse hardware ecosystem. It serves as both a diagnostic tool for setup and a medium for rich interaction via server-controlled images and text.