NVS Storage & Credentials
Relevant source files
The following files were used as context for generating this wiki page:
NVS (Non-Volatile Storage) serves as the primary persistence layer for Muse Gadget devices. It stores critical operational data including Wi-Fi credentials, device tokens, pairing information, and hardware-specific configurations. The system ensures that pairing and Wi-Fi settings survive firmware reflashing unless the flash is explicitly erased.
Sources: board-port/esp32/README.md:143-145, board-port/esp32/AGENTS.md:275-277
NVS Security and Encryption
The SDK recommends enabling NVS encryption to protect sensitive data from physical access. When enabled via CONFIG_HOMEHUB_NVS_ENCRYPTION, the system derives an encryption key from an HMAC key stored in eFuse. This key generation occurs automatically during the first boot if the eFuse block is available.
Sources: board-port/esp32/README.md:188-193
Partition Layout
The NVS system operates within a specific partition structure. The partition table starts at offset 0x10000 to accommodate larger Secure Boot bootloaders. Key partitions include nvs for general storage and nvsfactory for factory-specific data.
| Partition | Offset | Purpose |
|---|---|---|
nvs | Varies | Stores Wi-Fi SSIDs, passwords, and Muse tokens. |
nvsfactory | Varies | Stores factory-calibrated data; backup is recommended before overwriting. |
otadata | Varies | Manages OTA update states and rollback information. |
Sources: board-port/esp32/AGENTS.md:253-255, board-port/esp32/AGENTS.md:329-332
Credential Management
The device manages several types of credentials to maintain a secure session with the Muse backend.
Token Types
The system handles three primary token types:
- SDK Token: A unique identifier (
mgst_...) assigned to every gadget. It is baked into the firmware at build time. - Access Token: A short-lived credential used for authenticating API requests and Noise sessions.
- Refresh Token: A long-lived credential used to obtain new Access Tokens.
Sources: board-port/esp32/AGENTS.md:104-108, board-port/esp32/main/app.c:489-502
Token Refresh Logic
The application implements a proactive and reactive refresh policy. A proactive refresh occurs after a set interval (default 30 days of uptime). A reactive refresh triggers if a Muse endpoint rejects the current Access Token with a 401 error.
The diagram shows the logic flow for token validation and automatic recovery.
Sources: board-port/esp32/main/app.c:560-580, board-port/esp32/main/app.c:600-630
Setup and Provisioning Data
During the pairing process, the device receives and stores provisioning data. This data is critical for moving the device from an unpaired state to connected.
Key NVS Keys
The following keys are commonly used within the NVS storage:
| Key | Type | Description |
|---|---|---|
ssid | String | The Wi-Fi Network Name. |
password | String | The Wi-Fi Network Password. |
access_token | String | The current Muse Access Token. |
refresh_token | String | The Muse Refresh Token for token rotation. |
vm_url | String | The URL of the preferred Virtual Machine. |
wifi_channel | String | A hint for the last successful Wi-Fi channel. |
Sources: board-port/esp32/main/app.c:70-75, board-port/esp32/main/app.c:432-445
Setup Reset and Wipe
The system provides mechanisms to "unpair" or "factory reset" the device. Holding the BOOT button for 5 seconds triggers a setup reset, which clears all pairing data and Wi-Fi credentials from NVS.
This sequence illustrates the process of clearing credentials to return the device to a clean state.
Sources: board-port/esp32/main/app.c:465-485, board-port/esp32/README.md:139-141
Implementation Details
Credential handling is primarily implemented in app.c using the config_store wrapper.
- Verification: After erasing credentials, the system performs a readback to verify the data is truly absent before reporting success.
- Gate Control: The
s_operation_gatesemaphore prevents multiple setup operations (like BLE provisioning and manual resets) from conflicting. - Migration: The system includes logic to migrate legacy
auth_tokenkeys to modern device token pairs upon first connection.
Sources: board-port/esp32/main/app.c:468-472, board-port/esp32/main/app.c:514-530, board-port/esp32/main/app.c:166-170
Summary
NVS Storage & Credentials management ensures Muse Gadgets maintain persistent, secure connections. By leveraging hardware-backed encryption and robust token rotation logic, the system protects user data while allowing for easy recovery and reconfiguration through physical or remote triggers.