Linux SDK Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Linux SDK converts a Linux-based computer, such as a Raspberry Pi, into a Muse gadget. It operates as a Python package (musegadget) that establishes an encrypted Noise session with a Muse Virtual Machine (VM). The SDK allows the Muse app to execute shell commands, manage files, and monitor device health on the host machine.
Sources: linux/README.md:16-18, linux/AGENTS.md:20-22
System Architecture
The Linux SDK follows a modular design to handle communication, identity, and execution. The musegadget service maintains a reconnect loop and manages token rotation while running as a systemd unit.
Component Modules
| Module | Role |
|---|---|
cli.py | Handles command-line interface operations like pair, run, and info. |
pairing.py | Implements Community pairing v5 (P-256 ECDH, AES-256-GCM). |
ble_server.py | Manages BlueZ GATT peripheral and advertisements over D-Bus. |
link_client.py | Manages Noise XX handshakes and encrypted control streams. |
executor.py | Executes commands sent from Muse as the designated local user. |
identity.py | Maintains persistent device identity and BLE naming. |
Sources: linux/AGENTS.md:24-35
Data Flow Diagram
The following diagram illustrates the lifecycle of a Muse command from the cloud to the Linux host.
The SDK uses a persistent Noise session to receive link.invoke messages and return link.result payloads.
Sources: linux/AGENTS.md:100-105
Security and Authentication
Security is established through physical pairing and encrypted transport. The SDK utilizes the Noise XX handshake for session security and restricts command execution to a specific local user account.
- Pairing: Uses P-256 ECDH and HKDF-SHA256. Pairing only opens when manually triggered via
musegadget pair. - Execution Isolation: Commands run in child processes using the permissions of the account specified during installation. If the account lacks
sudoprivileges, Muse cannot perform administrative tasks. - Token Management: The SDK token is stored in
/var/lib/musegadget/sdk_token, which is readable only by the root user.
Sources: linux/README.md:46-48, linux/AGENTS.md:25-26, linux/install.sh:317-318
Installation and Deployment
The SDK is deployed using a shell script (install.sh) that configures the environment and system services.
Installation Steps
- System Check: Validates the distribution (Debian 11+, Ubuntu 22.04+, or Arch).
- Package Installation: Installs dependencies including
bluez,python3-dbus, andcryptography. - Environment Setup: Creates a Python virtual environment in
/opt/musegadget/venvusing the system interpreter. - Service Configuration: Installs a systemd service unit and configures BlueZ GATT MTU settings.
Sources: linux/install.sh:100-115, linux/install.sh:160-170
Connection Sequence
This diagram shows the sequence of events during a device connection attempt.
The SDK identifies itself as platform: "linux" and device_family: "homehub" during registration.
Sources: linux/AGENTS.md:95-103
Command Execution Framework
The Executor class in executor.py defines the interface for Muse to interact with the Linux system.
| Command | Functionality | Timeout |
|---|---|---|
system.run | Runs a shell command and returns output/exit code. | 30s (default) |
file.read | Reads a file in 64 KB chunks. | 30s (default) |
file.write | Atomically writes data to a file. | 30s (default) |
device.health | Reports uptime, memory, disk, and temperature. | 30s (default) |
Sources: linux/README.md:57-62, linux/AGENTS.md:112-115
Management and Diagnostics
Administrators manage the SDK through the musegadget CLI and standard systemd tools.
- Logs: Viewed via
sudo journalctl -u musegadget -f. Logs recordinvokeevents but never parameters or output. - Status:
sudo musegadget infoprovides the node ID and pairing state. - State Directory: Persistence data (identity and tokens) is located in
/var/lib/musegadget.
Sources: linux/README.md:86-92, linux/AGENTS.md:85-90
Summary
The Linux SDK provides a bridge between Linux hardware and the Muse ecosystem. It prioritizes secure, encrypted communication and granular permission control by leveraging Noise protocol handshakes and standard Linux user isolation. By implementing a subset of the protocols used by the ESP32 firmware, it ensures compatibility with the existing Muse mobile applications while offering the expanded capabilities of a full Linux environment.