Linux Deployment & Systemd
Relevant source files
The following files were used as context for generating this wiki page:
The Linux Deployment system automates the installation and lifecycle management of the Muse Gadget SDK on Linux-based devices, such as the Raspberry Pi. It installs necessary system dependencies, configures the BlueZ Bluetooth stack, and establishes a persistent Systemd service to maintain connectivity with the Muse platform. Sources: linux/README.md, linux/AGENTS.md
This module ensures that the musegadget Python package runs in a secure, isolated virtual environment while maintaining the ability to execute system commands as a designated user. Sources: linux/install.sh:159-170, linux/AGENTS.md:37-41
Deployment Architecture
The deployment process follows a specific sequence to prepare the host environment and launch the background service.
The installer identifies the distribution family (Debian/Ubuntu or Arch) and ensures the hardware architecture is supported (armhf, arm64, amd64, or x86_64). Sources: linux/install.sh:79-114
System Dependencies
The installation script requires specific system-level packages to handle Bluetooth communication via D-Bus and cryptographic operations.
| Package | Purpose |
|---|---|
bluez | Bluetooth stack for BLE pairing |
python3-dbus | D-Bus bindings for Python communication with BlueZ |
python3-gi | GObject Introspection for the GLib main loop |
python3-cryptography | Support for Noise protocol handshakes |
uv | High-performance Python package installer |
Sources: linux/install.sh:33-34, linux/AGENTS.md:37-41
Systemd Service Configuration
The musegadget service is managed by Systemd to ensure the gadget remains online across reboots. The service unit is generated by the installer and placed in /etc/systemd/system/musegadget.service. Sources: linux/install.sh:30, linux/README.md:65-70
Service Execution Logic
The service runs the musegadget run command, which maintains a reconnection loop to the Muse VM. Sources: linux/AGENTS.md:32. The installer uses a template to set the execution user.
Sources: linux/AGENTS.md:32, 98-105
User Permissions
The service runs as a non-root account specified during installation via the --run-as flag. If the chosen account has sudo privileges, the Muse VM can execute administrative commands on the host. Sources: linux/install.sh:124-135, linux/README.md:74-76
Bluetooth & BlueZ Optimization
For reliable pairing with the Muse mobile application, the installer modifies the host Bluetooth configuration.
- GATT MTU: The installer sets
ExchangeMTU = 256in/etc/bluetooth/main.conf. This matches the ESP32 firmware behavior and prevents pairing failures on Android devices that reject writes over 512 bytes. Sources: linux/install.sh:176-206, linux/AGENTS.md:121-125 - Battery Plugin: The installer creates a Systemd drop-in for
bluetooth.serviceto disable thebatteryplugin. This prevents BlueZ from asking phones to bond, as gadgets use unbonded community pairing. Sources: linux/install.sh:211-251, linux/AGENTS.md:112-115
File System Layout
The deployment follows a standardized path structure for application files and state.
| Path | Description | Permissions |
|---|---|---|
/opt/musegadget | Application prefix containing bin/uv and the venv | Root-owned |
/var/lib/musegadget | Persistent state including identity.json and pairing.json | 0700 (Root-only) |
/etc/systemd/system/musegadget.service | The Systemd service unit | Root-owned |
/run/musegadget/musegadget.sock | Local socket for CLI communication | Root & Run-as group |
Sources: linux/install.sh:29-32, linux/AGENTS.md:88-91
Deployment Lifecycle Management
Users manage the deployment using the musegadget CLI and standard Systemd commands.
- Pairing: Run
sudo musegadget pairto open Bluetooth advertising for 10 minutes. Sources: linux/README.md:70-71 - Logs: Use
sudo journalctl -u musegadget -fto monitor service activity and command invocations. Sources: linux/AGENTS.md:85, 93-96 - Uninstallation: The
install.sh --uninstallcommand removes the service, binaries, and virtual environment. Adding the--purgeflag removes the device identity and pairing credentials in/var/lib/musegadget. Sources: linux/install.sh:314-332
The Linux Deployment system provides a robust framework for turning standard Linux hardware into Muse-connected gadgets, ensuring security through isolated environments and encrypted communication sessions. Sources: linux/README.md:17-20, linux/AGENTS.md:21-23