Telemetry & State Management
Relevant source files
The following files were used as context for generating this wiki page:
Telemetry and state management in the Muse Gadget SDK provide a unified system for tracking device performance, battery health, and operational modes. The system coordinates data between hardware sensors, the voice pipeline, and the user interface to ensure accurate status reporting and power efficiency.
The architecture relies on shared state structures and specialized monitors to capture high-resolution metrics. These metrics include battery discharge rates, power-management transitions, and application-level operational states like thinking or speaking.
Battery Telemetry System
The battery meter tracks power consumption by pairing fuel gauge data with chip activity logs. It measures the duration of various power states, including screen-off time and light-sleep cycles. Sources: muse_battery.h:20-27
Monitoring Architecture
The system captures snapshots of system counters to calculate deltas over time. Measurements start automatically when the device unplugs from USB and stop when USB power returns. Sources: muse_battery.c:166-180, muse_battery.h:27-29
The diagram above shows the logic flow for starting and stopping a battery measurement session based on USB power status. Sources: muse_battery.c:166-180
Data Persistence
Telemetric data persists in RTC memory across resets. This allows the device to report metrics even if a crash occurs while on battery power. The system saves JSON-formatted telemetry strings at regular intervals (every 30 minutes) and upon significant power events. Sources: muse_battery.c:70-85, muse_battery.c:459-465
| Field | Type | Description |
|---|---|---|
secs | int64_t | Total time spent on battery power. |
pct_start / pct_now | int | Battery percentage at start and current time. |
screen_off_pm | int | Per mille of time the screen was inactive. |
slept_pm | int | Per mille of time the chip was in light sleep. |
busy_pm | int | Per mille of time a CPU core was active. |
Sources: muse_battery.h:32-44
Shared System State
The state management module synchronizes the voice pipeline with the User Interface. It maintains the global operational mode and provides access to hardware status like audio levels and battery voltage. Sources: muse_state.h:22-25
Operational Modes
The muse_mode_t enumeration defines the primary states of the gadget. The system tracks the duration spent in each mode to assist in performance analysis. Sources: muse_state.h:27-36
| Mode | Identifier | Description |
|---|---|---|
| Booting | MUSE_MODE_BOOT | Initial system startup. |
| Idle | MUSE_MODE_IDLE | Waiting for user interaction. |
| Listening | MUSE_MODE_LISTENING | Recording voice input via mic. |
| Thinking | MUSE_MODE_THINKING | Processing voice or waiting for VM. |
| Speaking | MUSE_MODE_SPEAKING | Playing back audio response. |
| Error | MUSE_MODE_ERROR | System failure or connectivity issue. |
Sources: muse_state.h:27-35
UI Integration and Captions
State management handles the timing and display of text captions. It provides a versioned interface to the UI, allowing it to detect when a new caption is available for rendering. The system also supports CJK-specific layout adjustments for larger characters. Sources: muse_state.h:47-58
Power Management Profiling
When CONFIG_PM_PROFILING is enabled, the telemetry system tracks specific power-management locks that prevent the device from entering deep sleep. Sources: muse_battery.c:30-45
Power Lock Tracking
The system monitors different power modes based on the strongest active lock. Sources: muse_battery.c:35-37
The diagram represents the hierarchy of power management modes monitored by the telemetry system. Sources: muse_battery.c:35-37
Implementation Detail: Snapshots
The snap_t structure captures the system's power state at a specific point in time. It records total sleep time, number of sleep cycles, and detailed power management statistics. Sources: muse_battery.c:56-62
typedef struct {
int64_t at_us;
int64_t slept_us;
uint32_t sleeps;
#if CONFIG_PM_PROFILING
pm_stats_t pm;
#endif
} snap_t;
Sources: esp32/components/muse/muse_battery.c:56-62
Heartbeat and Logging
The application maintains a heartbeat loop that logs system telemetry every 5 seconds. This log includes heap memory status (internal, DMA, and PSRAM), network status, and tunnel throughput. Sources: app.c:1348-1375
Monitoring Metrics
The heartbeat logs the following data points:
- Uptime: Time since boot in seconds.
- Connection Status: WiFi, WebSocket (Control), and Raw Tunnel availability.
- Memory: Free and largest blocks for Internal, DMA, and PSRAM heaps.
- Throughput: Bytes received and transmitted over the Noise tunnel.
Sources: app.c:1360-1375
Conclusion
The Telemetry & State Management system provides a technical foundation for debugging power consumption and coordinating asynchronous gadget behaviors. By leveraging RTC-backed persistence and high-frequency heartbeats, it ensures that developers have visibility into the device's operational health even during battery-powered usage.