From b18c0145dd2aa5b8cfa4e56583ad8ca0e48a1250 Mon Sep 17 00:00:00 2001 From: MarekWo Date: Sun, 29 Mar 2026 13:56:45 +0200 Subject: [PATCH] docs(ble): add pairing guide, remove unused MC_BLE_PIN config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MC_BLE_PIN was non-functional — bleak in Docker cannot perform interactive pairing (no BlueZ agent). Pairing must be done on the host before starting mc-webui. Added comprehensive pairing guide at docs/meshcore_bluetooth_pairing.md. Co-Authored-By: Claude Opus 4.6 --- .env.example | 9 ++-- app/config.py | 2 +- app/device_manager.py | 1 - docker-compose.yml | 1 - docs/meshcore_bluetooth_pairing.md | 83 ++++++++++++++++++++++++++++++ 5 files changed, 87 insertions(+), 9 deletions(-) create mode 100644 docs/meshcore_bluetooth_pairing.md diff --git a/.env.example b/.env.example index 9044989..9be15cf 100644 --- a/.env.example +++ b/.env.example @@ -20,14 +20,11 @@ MC_SERIAL_PORT=auto # MC_TCP_PORT=5555 # --- Option C: BLE (Bluetooth Low Energy companion devices) --- -# Requires: USB BLE dongle on host, BlueZ installed, device pre-paired. -# One-time setup on host: -# bluetoothctl scan le (find your MeshCore device) -# bluetoothctl pair (enter PIN shown on device) -# bluetoothctl trust +# Requires: USB BLE dongle on host, BlueZ installed. +# The device MUST be paired and trusted on the host BEFORE starting mc-webui. +# See docs/meshcore_bluetooth_pairing.md for detailed setup instructions. # When MC_BLE_ADDRESS is set, serial and TCP are ignored. # MC_BLE_ADDRESS=AA:BB:CC:DD:EE:FF -# MC_BLE_PIN=123456 # Your MeshCore device name (used for .msgs file) # Use "auto" for automatic detection from device (recommended) diff --git a/app/config.py b/app/config.py index f1eec94..0afb328 100644 --- a/app/config.py +++ b/app/config.py @@ -33,8 +33,8 @@ class Config: MC_TCP_PORT = int(os.getenv('MC_TCP_PORT', '5555')) # v2: BLE connection (alternative to serial/TCP, for BLE companion devices) + # Device must be paired and trusted on host before starting (see docs/meshcore_bluetooth_pairing.md) MC_BLE_ADDRESS = os.getenv('MC_BLE_ADDRESS', '') # BLE MAC address or device name filter - MC_BLE_PIN = os.getenv('MC_BLE_PIN', '') # PIN for BLE pairing # v2: Backup MC_BACKUP_ENABLED = os.getenv('MC_BACKUP_ENABLED', 'true').lower() == 'true' diff --git a/app/device_manager.py b/app/device_manager.py index bedb7f3..f2e192f 100644 --- a/app/device_manager.py +++ b/app/device_manager.py @@ -189,7 +189,6 @@ class DeviceManager: logger.info(f"Connecting via BLE: {self.config.MC_BLE_ADDRESS}") self.mc = await MeshCore.create_ble( address=self.config.MC_BLE_ADDRESS, - pin=self.config.MC_BLE_PIN or None, auto_reconnect=False, ) elif self.config.use_tcp: diff --git a/docker-compose.yml b/docker-compose.yml index d2e3f05..7411a7a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -26,7 +26,6 @@ services: - MC_TCP_HOST=${MC_TCP_HOST:-} - MC_TCP_PORT=${MC_TCP_PORT:-5555} - MC_BLE_ADDRESS=${MC_BLE_ADDRESS:-} - - MC_BLE_PIN=${MC_BLE_PIN:-} - MC_BACKUP_ENABLED=${MC_BACKUP_ENABLED:-true} - MC_BACKUP_HOUR=${MC_BACKUP_HOUR:-2} - MC_BACKUP_RETENTION_DAYS=${MC_BACKUP_RETENTION_DAYS:-7} diff --git a/docs/meshcore_bluetooth_pairing.md b/docs/meshcore_bluetooth_pairing.md new file mode 100644 index 0000000..2f2ff10 --- /dev/null +++ b/docs/meshcore_bluetooth_pairing.md @@ -0,0 +1,83 @@ +# How to Pair MeshCore/Heltec Devices via Bluetooth on Linux + +Pairing Bluetooth Low Energy (BLE) devices like Heltec (running MeshCore or Meshtastic) with a headless Linux server can sometimes be tricky due to security negotiations. Follow this guide to ensure a stable and successful connection for the `mc-webui` application. + +## Prerequisites: Device Preparation + +Before touching the Linux terminal, you must configure your MeshCore device to use a fixed PIN. This prevents authentication timeouts and makes headless pairing much easier. + +1. Connect to your MeshCore device via the mobile app or web interface. +2. Go to the **Bluetooth Settings**. +3. Set the pairing mode to use a **Fixed PIN** (Passkey). +4. Enter a memorable 6-digit PIN (e.g., `123456`). +5. Save the configuration and let the device reboot. + +--- + +## Step 1: Linux Server Preparation + +Linux's default Bluetooth stack (BlueZ) needs to be optimized for Bluetooth Low Energy (BLE). + +1. Edit the main Bluetooth configuration file: + ```bash + sudo nano /etc/bluetooth/main.conf + ``` +2. Find the `[General]` section and add or modify the following lines to force LE mode and speed up connections: + ```ini + ControllerMode = le + FastConnectable = true + ``` +3. Save the file and restart the Bluetooth service: + ```bash + sudo systemctl restart bluetooth + ``` + +*Note for Proxmox/VM Users:* If you are passing a physical USB Bluetooth dongle to a Virtual Machine, **do not use USB 3.0 passthrough**. It causes packet drops and timeouts (`Opcode failed` errors). Always force USB 2.0. Example Proxmox command: +`qm set -usb0 host=:,usb3=0` + +--- + +## Step 2: The Pairing Process + +Use the built-in `bluetoothctl` tool to discover, pair, and trust your device. + +1. Open the Bluetooth control utility: + ```bash + bluetoothctl + ``` +2. Enable the keyboard display agent (this tells Linux to ask you for the PIN): + ```text + [bluetooth]# agent KeyboardDisplay + [bluetooth]# default-agent + ``` +3. Turn on the Bluetooth scan to find your device: + ```text + [bluetooth]# scan le + ``` +4. Wait until your device appears in the list and note its MAC address (e.g., `AC:A7:04:08:66:A1 MeshCore-demo mc-webui`). +5. Initiate the pairing process using the MAC address: + ```text + [bluetooth]# pair AC:A7:04:08:66:A1 + ``` +6. The terminal will prompt you for the passkey: + `[agent] Enter passkey (number in 0-999999):` + Enter the **Fixed PIN** you configured earlier (e.g., `123456`) and press Enter. +7. You should see `Pairing successful`. + +--- + +## Step 3: Trusting the Device + +This is the most crucial step. You must "trust" the device so that `mc-webui` can automatically connect to it in the future without requiring the PIN again. + +1. In the `bluetoothctl` prompt, type: + ```text + [bluetooth]# trust AC:A7:04:08:66:A1 + ``` +2. You should see `trust succeeded`. +3. You can now safely exit the utility: + ```text + [bluetooth]# exit + ``` + +Your MeshCore device is now permanently paired, trusted, and ready to communicate with the `mc-webui` server!