Logging & Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
Logging and diagnostics provide developers with real-time and historical data to monitor device health, debug failures, and analyze power consumption. The system includes serial logging, persistent battery metrics in RTC memory, and a bug reporting mechanism that captures system snapshots.
Sources: esp32/main/main.c, esp32/components/muse/muse_battery.h:20-29
System Logging
The SDK uses the standard ESP-IDF ESP_LOG macros to output system status to the serial console. During the boot sequence, the application initializes diagnostic logs and reports the product name and version.
Initialization Flow
The application main entry point attempts to initialize diagnostic logs in internal RAM or PSRAM. If PSRAM is unavailable, the system disables support log capture and emits a warning.
Sources: esp32/main/main.c:22-35
Battery and Power Diagnostics
The battery meter monitors power consumption and device state transitions. Because hardware often lacks direct current measurement, the system correlates fuel gauge changes with chip activities like light sleep and CPU busy time.
Persistent RTC Storage
Diagnostic data for battery performance persists in RTC memory across software resets. The system saves snapshots when:
- The measurement starts (USB unplugged).
- USB power is restored.
- Periodically every 30 minutes on battery power.
Sources: esp32/components/muse/muse_battery.c:85-94, esp32/components/muse/muse_battery.h:20-29
Battery Diagnostic Data Fields
| Field | Description |
|---|---|
secs | Total time spent on battery power. |
screen_off_pm | Per mille of time the screen remained off. |
slept_pm | Per mille of time actually spent in light sleep. |
busy_pm | Per mille of time the CPU core was running a task. |
awake | List of power locks preventing sleep (e.g., "wifi 4%"). |
Sources: esp32/components/muse/muse_battery.h:32-44
Bug Reporting System
The bug report module generates JSON payloads containing environment data and log tails for remote debugging. This system extracts information from various sub-components to provide a holistic view of the device state at the time of a reported issue.
Data Collection Components
Bug Report Schema
The diagnostic system serializes specific fields into the bug report while explicitly excluding sensitive PII (Personally Identifiable Information).
- Included Data: Firmware version, RSSI (dBm), base64-encoded log tail, reset reason, and OTA partition states.
- Excluded Data: SSID, passwords, tokens, private keys, and local IP addresses.
Sources: esp32/tests/link_bug_report_harness.c:193-214
Diagnostic User Interface
On devices with a screen, the Settings UI provides a "Battery" page for real-time diagnostic viewing. This interface displays current levels, discharge rates, and sleep efficiency.
Procedure: Viewing Battery Diagnostics
- Open Settings on the device.
- Navigate to the Battery row.
- Review the following metrics:
- Battery Level: Current percentage and voltage.
- Used: Percentage drained and rate (percent per hour).
- Chip Asleep: Percentage of time the device maintained light sleep.
- Wakes: Number of wake events per second.
Sources: esp32/components/muse/muse_settings_ui.c:709-725, esp32/components/muse/muse_settings_ui.c:835-860
Diagnostic Tools and Verification
Developers verify diagnostic output through serial monitoring tools. The SDK provides specific commands to inspect the state of a connected board.
| Tool/Command | Function |
|---|---|
idf.py monitor | Views real-time serial logs and diagnostic initialization. |
tools/muse/monitor.py | Specialized monitor for boards running the full UI. |
>nap | CLI command used to trigger measurement between USB wake events. |
Sources: esp32/devices/AGENTS.md:288-295, esp32/components/muse/muse_battery.h:28-29
The diagnostic system ensures that even if a board crashes or resets upon opening a serial port, the last known-good battery state and diagnostic logs are recoverable from persistent storage.