Connectivity: Wi-Fi & Tunnels
Relevant source files
The following files were used as context for generating this wiki page:
The connectivity system manages the network lifecycle for Muse gadgets. It enables devices to join home Wi-Fi networks, pair with the Muse mobile application via Bluetooth Low Energy (BLE), and establish secure tunnels to the Muse Virtual Machine (VM).
Sources: esp32/README.md:12-20, esp32/components/muse/muse_link.c:132-155
Wi-Fi Management
The Wi-Fi module handles station-mode operations, including network discovery, connection persistence, and power management. It identifies and connects to saved networks while providing status updates to the system and UI.
Sources: esp32/components/muse/muse_wifi.h:23-28
Network States and Connectivity
The system tracks the Wi-Fi connection through a set of defined states. These states reflect the device's ability to reach a local access point.
| State | Description |
|---|---|
MUSE_WIFI_OFF | Wi-Fi radio is disabled. |
MUSE_WIFI_NO_NETWORK | Radio is on but no credentials are saved. |
MUSE_WIFI_CONNECTING | Currently attempting to join a network. |
MUSE_WIFI_CONNECTED | Successfully associated and IP assigned. |
MUSE_WIFI_FAILED | Connection failed (e.g., wrong password). |
MUSE_WIFI_NOT_NEARBY | None of the saved networks were found in a scan. |
Sources: esp32/components/muse/muse_wifi.h:30-37
Scan Result Deduping
The firmware collapses raw BSSID scan results into a single entry per SSID. This prevents dual-band or mesh networks from appearing multiple times in the network picker. The system keeps the strongest BSSID's RSSI for each SSID and marks the entry as secure if any associated BSSID requires authentication.
The diagram shows the logic used to deduplicate multiple Access Points (BSSIDs) sharing the same Network Name (SSID).
Sources: esp32/tests/test_link_wifi_scan_contract.py:34-52
Power Management
Devices support three Wi-Fi power levels to balance latency and battery life:
- FULL: Standard mode with no modem sleep; maintains BLE coexistence.
- DOZE: Enables modem sleep between DTIM beacons, adding a few hundred milliseconds of latency.
- REST: Extends sleep over several beacons, resulting in up to one second of latency.
Sources: esp32/components/muse/muse_wifi.h:58-62, esp32/components/muse/muse_link.c:168-185
Bluetooth Low Energy (BLE) Provisioning
The BLE interface provides a "Phone setup" service that allows the Muse mobile app to configure the device without a physical network connection.
Sources: esp32/components/muse/muse_ble.c:70-85
GATT Service and Characteristics
The device exposes a specific primary service and two main characteristics for configuration:
- Service UUID:
4d757365-0001-4000-8000-6a6f6c6c7900 - Command Characteristic (CMD):
...-0002-...(Write/Encrypted/Authenticated). - Status Characteristic (STATUS):
...-0003-...(Read/Notify/Encrypted/Authenticated).
Sources: esp32/components/muse/muse_ble.c:45-50, esp32/components/muse/muse_ble.c:201-215
Pairing Procedure
- Navigate to Settings > Bluetooth > Phone setup on the device.
- Open the setup tool (e.g.,
ble_setup.html) in a compatible browser. - Connect to the device prefixed with
MuseGadget-. - Enter the 6-digit passkey displayed on the device screen when prompted by the OS.
- Send Wi-Fi credentials via the Command characteristic.
Sources: esp32/components/muse/muse_settings_ui.c:595-605, esp32/components/muse/muse_ble.c:236-258
The diagram illustrates the secure pairing and provisioning sequence over Bluetooth Low Energy.
Sources: esp32/components/muse/muse_ble.c:236-270, esp32/components/muse/muse_settings_ui.c:607-610
Home-Network Tunnels
The "home-network tunnel" allows the Muse VM to reach local devices and HTTP APIs within your home network. Establishing this tunnel requires specific hardware capabilities and configuration.
Hardware Requirements
The tunnel requires significant memory. Boards without PSRAM (e.g., classic ESP32 or ESP32-C6) do not support the tunnel feature. On these devices, Muse can control the gadget but cannot use it as a gateway to other local devices.
Sources: esp32/README.md:120-125, esp32/devices/AGENTS.md:162-167
Connectivity Lifecycle Indicators
The device uses a status LED (or screen animation) to indicate the progress of the Wi-Fi and Tunnel connection.
| Light Color | Meaning |
|---|---|
| Orange (Breathing) | Ready for setup (unpaired). |
| Blue (Breathing) | Waiting for physical button press to confirm pairing. |
| Blue (Solid) | Joining Wi-Fi and establishing VM connection. |
| Green (Solid) | Connected to Muse VM. |
| Yellow (Blinking) | Reconnecting to network. |
| Red (Blinking) | Error state. |
Sources: esp32/README.md:86-96
Link Operations (muse_link)
The muse_link component acts as the bridge between the core gadget logic and the underlying network drivers. It registers a set of operations (muse_link_ops_t) that handle high-level requests such as VM token lookups and Noise session management.
Sources: esp32/components/muse/muse_link.h:37-65
Key Functions
muse_link_hatch_vm: Looks up credentials for a specific Muse Virtual Machine.muse_link_req_open: Opens a request to the VM over the existing Noise session.muse_link_wifi_nap: Disconnects from Wi-Fi to allow the radio to sleep when the screen is off for an extended period.
Sources: esp32/components/muse/muse_link.c:70-85, esp32/components/muse/muse_link.h:55-65
Connectivity in the Muse Gadget SDK ensures that devices remain reachable and secure while managing the power constraints of ESP32 hardware. The combination of BLE provisioning, SSID deduping, and PSRAM-backed tunneling provides a robust framework for home automation integration.