BLE Advertising & Setup
Relevant source files
The following files were used as context for generating this wiki page:
BLE Advertising & Setup handles the initial provisioning of the Muse Gadget. This process allows a mobile device to discover the gadget, configure its Wi-Fi credentials, and establish secure pairing for connection to the Muse VM infrastructure. The system ensures that only authorized users can pair with the hardware through physical confirmation requirements.
The setup process transitions the device from an "unpaired" state, where it actively advertises over Bluetooth Low Energy (BLE), to a "provisioned" state where it can operate over Wi-Fi. It utilizes the "community pairing v5" protocol, which requires a physical button press on the device to prevent unauthorized remote pairing.
Sources: board-port/esp32/README.md:120-130, board-port/esp32/AGENTS.md:364-375, board-port/esp32/main/app.c:1345-1355
Setup Lifecycle and States
The device follows a specific state machine during the BLE setup process. Each state is visually represented by the status light or on-screen UI to guide the user.
| LED Color | State | Technical Meaning |
|---|---|---|
| Orange, breathing | Advertising | The BLE server is active and waiting for a mobile app to connect. |
| Orange, solid | BLE Connected | A mobile device has established a GATT connection but not yet paired. |
| Blue, breathing | Confirm Required | The app has initiated pairing; waiting for physical button/touch confirmation. |
| Blue, solid | Connecting | Provisioning data received; joining Wi-Fi and establishing Noise session. |
| Green, solid | Connected | Setup complete; tunnel and control sessions are active. |
| Purple, solid | Unpaired | Setup data has been wiped; device is in a clean state. |
| Red, blinking | Error | A failure occurred during Wi-Fi connection, authentication, or storage. |
Sources: board-port/esp32/README.md:131-140, board-port/esp32/AGENTS.md:345-360, board-port/esp32/main/led_status.c:980-1020
State Transition Flow
This diagram illustrates the high-level transitions from first boot to a fully connected state.
The device checks NVS for existing credentials at boot; if absent, it enters the advertising loop.
Sources: board-port/esp32/main/app.c:1340-1430
BLE Provisioning Protocol
The provisioning phase involves exchanging configuration data between the mobile app and the gadget via GATT characteristics.
1. Discovery and Connection
The device advertises as MuseGadget-XXXXXX (or MuseGadget-Disp-XXXXXX for boards with displays). Once a mobile client connects, the gadget stops general advertising and waits for pairing commands.
Sources: board-port/esp32/AGENTS.md:364-368, board-port/esp32/main/app.c:963-968
2. Physical Confirmation
To prevent man-in-the-middle attacks, the gadget requires a physical action to authorize pairing:
- Physical Buttons: A short press on the BOOT button (or designated GPIO).
- Touch Screens: A tap on the screen for boards like the ESP32 CYD.
- Timeout: If no press occurs within the
PAIRING_CONFIRM_WINDOW_MS(60 seconds), the session is terminated.
Sources: board-port/esp32/main/app.c:64-65, board-port/esp32/main/app.c:978-990, board-port/esp32/main/led_status.c:542-555
3. Data Exchange
The mobile app sends a JSON payload containing the following essential fields:
ssid&password: Wi-Fi credentials.access_token&refresh_token: Credentials for the Muse VM.api_url_v2&noise_host: Endpoint configurations for the backend services.
Sources: board-port/esp32/main/app.c:560-580
The sequence ensures that sensitive data is only accepted after the physical "Confirm Required" phase is satisfied.
Sources: board-port/esp32/main/app.c:995-1035, board-port/esp32/main/app.c:556-610
Setup Persistence and Reset
Credentials and setup markers are stored in Non-Volatile Storage (NVS).
Persistence Logic
- Setup Marker: The gadget marks
setup_completeonly after Wi-Fi is successfully connected and tokens are verified. - Partial Setup: If the device boots with only Wi-Fi credentials but no tokens (or vice versa), it wipes the partial state to ensure a clean re-pair attempt.
- NVS Encryption: The project recommends
CONFIG_HOMEHUB_NVS_ENCRYPTIONto protect Wi-Fi passwords and device tokens from physical extraction.
Sources: board-port/esp32/README.md:195-202, board-port/esp32/main/app.c:1350-1375
Factory Reset
Users can force the device back into the BLE advertising state by holding the button for 5 seconds. This triggers reset_setup_from_control, which:
- Disconnects all active VM and Wi-Fi transports.
- Erases all setup-related keys in NVS.
- Reboots the device or enters the advertising state.
Sources: board-port/esp32/README.md:141-141, board-port/esp32/main/app.c:834-845, board-port/esp32/main/app.c:1085-1100
Technical Implementation Details
Relevant Functions
ble_server_start(): Initializes the BLE stack and sets callbacks for provisioning events.on_provision(): Handles the incoming JSON provisioning data, joins Wi-Fi, and persists tokens.join_saved_networks(): Logic for scanning and connecting to the strongest known Wi-Fi access point.noise_ctrl_connect(): Initiates the encrypted Noise session to the Muse VM using tokens received during setup.
Sources: board-port/esp32/main/app.c:556, board-port/esp32/main/app.c:265, board-port/esp32/main/app.c:1040, board-port/esp32/main/noise_control.cpp:1150
Configuration Key-Value Pairs (NVS)
| Key | Type | Description |
|---|---|---|
ssid | String | Wi-Fi Network Name. |
password | String | Wi-Fi Password. |
access_token | String | Token used for Noise session authentication. |
refresh_token | String | Token used to obtain new access tokens. |
setup_complete | Marker | Flag indicating a successful provisioning cycle. |
Sources: board-port/esp32/main/app.c:590-605, board-port/esp32/main/app.c:485-495
BLE Advertising & Setup serves as the gateway for hardware integration into the Muse platform. By combining standard BLE GATT communication with physical security checks and NVS persistence, the system provides a robust mechanism for onboarding community-built ESP32 gadgets while maintaining secure communication channels.