mirror of https://github.com/MarekWo/mc-webui.git synced 2026-05-02 11:32:35 +02:00

Files

MarekWo b18c0145dd docs(ble): add pairing guide, remove unused MC_BLE_PIN config

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 <noreply@anthropic.com>

2026-03-29 13:56:45 +02:00

3.0 KiB

Raw Blame History

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.

Connect to your MeshCore device via the mobile app or web interface.
Go to the Bluetooth Settings.
Set the pairing mode to use a Fixed PIN (Passkey).
Enter a memorable 6-digit PIN (e.g., 123456).
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).

Edit the main Bluetooth configuration file:
```
sudo nano /etc/bluetooth/main.conf
```
Find the [General] section and add or modify the following lines to force LE mode and speed up connections:
```
ControllerMode = le
FastConnectable = true
```
Save the file and restart the Bluetooth service:
```
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 <VMID> -usb0 host=<VENDOR_ID>:<PRODUCT_ID>,usb3=0

Step 2: The Pairing Process

Use the built-in bluetoothctl tool to discover, pair, and trust your device.

Open the Bluetooth control utility:
```
bluetoothctl
```
Enable the keyboard display agent (this tells Linux to ask you for the PIN):
```
[bluetooth]# agent KeyboardDisplay
[bluetooth]# default-agent
```
Turn on the Bluetooth scan to find your device:
```
[bluetooth]# scan le
```
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).
Initiate the pairing process using the MAC address:
```
[bluetooth]# pair AC:A7:04:08:66:A1
```
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.
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.

In the bluetoothctl prompt, type:
```
[bluetooth]# trust AC:A7:04:08:66:A1
```
You should see trust succeeded.
You can now safely exit the utility:
```
[bluetooth]# exit
```

Your MeshCore device is now permanently paired, trusted, and ready to communicate with the mc-webui server!

3.0 KiB Raw Blame History