BLE Setup & Framing
Relevant source files
The following files were used as context for generating this wiki page:
Bluetooth Low Energy (BLE) Setup and Framing provides a standardized interface for initial device configuration across ESP32 and Linux platforms. This system enables the Muse mobile application or a web-based setup tool to provision Wi-Fi credentials, server tokens, and hardware settings through GATT characteristics. The architecture ensures secure communication via encrypted links and implements chunked framing to handle payloads exceeding standard BLE MTU limits.
Sources: esp32/components/muse/muse_ble.h:25-35, linux/AGENTS.md:32-34
Service Architecture
The BLE setup system implements a primary GATT service with specific characteristics for commands and status monitoring. This service identifies as MuseGadget-XXXXXX (ESP32) or MuseGadgetXXXXXX (Linux) during advertisement.
GATT Characteristics
The service consists of two primary operational characteristics:
| Characteristic | UUID (Suffix) | Operations | Purpose |
|---|---|---|---|
| CMD | ...0002... | Write | Receives key=value text commands for configuration. |
| STATUS | ...0003... | Read/Notify | Provides a JSON snapshot of the device state and command results. |
Sources: esp32/components/muse/muse_ble.h:28-34, esp32/components/muse/muse_ble.c:42-45, esp32/tools/muse/ble_setup.html:105-107
UUID Structure
The system uses a 128-bit base UUID: 4d757365-000X-4000-8000-6a6f6c6c7900. The second segment (000X) differentiates the service (0001), command (0002), and status (0003) entities.
Sources: esp32/components/muse/muse_ble.c:41-45, esp32/tools/muse/ble_setup.html:105-107
Command Processing
Devices process plain-text strings formatted as key=value. Commands control Wi-Fi connectivity, Muse server settings, and hardware parameters like volume or brightness.
Supported Commands
- Wi-Fi:
wifi.ssid,wifi.pass,wifi.connect,wifi.forget - Server (Hatch):
hatch.host,hatch.vm,hatch.token,hatch.token+(for chunked appending),hatch.test - Hardware:
volume,mic_gain,brightness,sleep,speaker
Sources: esp32/components/muse/muse_ble.h:28-32, esp32/components/muse/muse_ble.c:132-167
Sequence Diagram: Command Execution
The following diagram illustrates the interaction between a client (Phone/Web) and the Muse device during a setup command.
Data Framing and MTU Management
BLE communication requires specific handling of data lengths to ensure compatibility with mobile OS constraints.
Chunked Framing (Linux)
The Linux implementation uses a chunked framing protocol for larger payloads. Each frame follows a specific header format:
- Prefix:
0xFE - Index: The sequence number of the current chunk.
- Total: Total number of chunks expected.
- Payload: The actual data segment.
Sources: linux/AGENTS.md:33, linux/src/musegadget/ble_framing.py
MTU Restrictions
Android devices typically reject writes exceeding 512 bytes. To maintain stability, the system caps the negotiated MTU at 256 bytes. This is enforced via BlueZ configuration (ExchangeMTU = 256) on Linux and similar constraints in the ESP32 NimBLE stack.
Sources: linux/AGENTS.md:95-97, linux/install.sh:267-285
Security and Pairing
Access to configuration characteristics requires an encrypted, MITM-protected link. The system employs P-256 ECDH, HKDF-SHA256, and AES-256-GCM for pairing and communication.
Pairing Flow
- The device advertises a specific name prefix (
MuseGadget-). - The client initiates a connection.
- The first protected read/write operation triggers the OS pairing request.
- For ESP32, the device displays a 6-digit passkey on its screen; the user enters this into the client.
- On Linux, the
musegadget pairCLI command must be active to allow pairing, which uses an app-based confirmation.
Sources: esp32/components/muse/muse_ble.h:35, esp32/components/muse/muse_ble.c:266-285, linux/AGENTS.md:32, 90-93
Implementation Comparison
| Feature | ESP32 Implementation | Linux Implementation |
|---|---|---|
| BLE Stack | NimBLE | BlueZ (via D-Bus) |
| Passkey | Displayed on LCD | CLI-based pairing flow |
| Configuration | muse_ble.c handlers | ble_setup.py / ble_server.py |
| Persistence | NVS (Flash) | /var/lib/musegadget/identity.json |
Sources: esp32/components/muse/muse_ble.c:266-300, linux/src/musegadget/ble_server.py, linux/AGENTS.md:34, 76-78
Summary
The BLE Setup & Framing system provides a consistent cross-platform mechanism for device initialization. By leveraging GATT characteristics and standardized key=value commands, it enables flexible configuration via mobile and web interfaces. Framing and MTU management ensure that these operations remain reliable across varying hardware and operating systems.