esp-hci-bridge

A remote Bluetooth adapter for Linux. Flash a board here, install the PC tool, claim the board, pair your devices. Five minutes, no cables after the first step.

STEP 1 Flash the board

Pick your board, plug it into this computer over USB, and click Install. Firmware …, built ….

Needs Chrome, Chromium, or Edge. Firefox and Safari have no Web Serial. Open this page over HTTPS.

Pick the board's serial port in the dialog. The dialog also has a console for watching boot logs.

On Linux your user needs access to the serial device, usually by being in the dialout or uucp group. A Flatpak browser needs --device=all.

Download the files and flash them at these offsets:

file	offset

On the non-ISO Olimex ESP32-POE, unplug PoE before connecting USB. Olimex warns the missing isolation can damage the PC.

WiFi boards start a setup hotspot after flashing. Join esp-hci-bridge-setup from a phone or laptop, open http://192.168.4.1/, and enter your WiFi name and password. The board reboots onto your network.

STEP 2 Install on the PC

One package. It installs the hcibridge command and a background service that starts on boot and finds boards on its own.

sudo curl -fsSLo /etc/apt/keyrings/hcibridge.gpg https://heppu.github.io/esp-hci-bridge/hcibridge.gpg
echo "deb [signed-by=/etc/apt/keyrings/hcibridge.gpg] https://heppu.github.io/esp-hci-bridge/deb stable main" | sudo tee /etc/apt/sources.list.d/hcibridge.list
sudo apt update && sudo apt install hcibridge

A signed repository for amd64, arm64, and armhf. apt upgrade picks up new releases.

sudo curl -fsSLo /etc/yum.repos.d/hcibridge.repo https://heppu.github.io/esp-hci-bridge/rpm/hcibridge.repo
sudo dnf install hcibridge

A signed repository for x86_64, aarch64, and armhfp. dnf upgrade picks up new releases.

sudo wget -O /etc/apk/keys/heppu-esp-hci-bridge.rsa.pub https://heppu.github.io/esp-hci-bridge/alpine/heppu-esp-hci-bridge.rsa.pub
echo https://heppu.github.io/esp-hci-bridge/alpine | sudo tee -a /etc/apk/repositories
sudo apk add hcibridge

A signed repository for x86_64, aarch64, and armv7. apk upgrade picks up new releases. The service is hcibridged under OpenRC.

curl -LO https://github.com/heppu/esp-hci-bridge/releases/latest/download/PKGBUILD
makepkg -si

Builds from source, needs zig.

curl -LO https://github.com/heppu/esp-hci-bridge/releases/latest/download/void-template
# drop it into your void-packages checkout as srcpkgs/hcibridge/template, then
./xbps-src pkg hcibridge && sudo xbps-install --repository hostdir/binpkgs hcibridge

Static binaries for x86_64, aarch64, and armv7 are on the release page, along with the man page and shell completions. The install script in the repository sets up the service for systemd, OpenRC, runit, or s6:

git clone https://github.com/heppu/esp-hci-bridge
cd esp-hci-bridge && sudo scripts/install-host-service.sh

STEP 3 Claim the board

A fresh board talks to nobody until a PC claims it. Claiming exchanges a key once, over the network. The service picks the key up by itself.

hcibridge list               # find the board, KEY column says unclaimed
sudo hcibridge claim <ip>    # pair it with this PC

A few seconds later the board is a Bluetooth adapter on this PC. A claimed board refuses every other claim.

STEP 4 Pair your devices

The board is a normal adapter now. Pair with whatever you usually use, for example:

bluetoothctl
scan on                      # press the pairing button on the device
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX

Pairings are stored on the board, so devices reconnect on their own after a reboot of either side.

Xbox controllers need current controller firmware to pair. Update through an Xbox or the Xbox Accessories app on Windows.

That is it

The service handles boards coming and going. The few commands you might need later:

`hcibridge status <ip>`	everything a board reports, including traffic and drop counters
`sudo hcibridge update <ip>`	latest release over the network, checksum verified, the board rolls back by itself if it fails
`sudo hcibridge revoke <bdaddr>`	stop trusting a board
`sudo hcibridge unclaim <ip>`	release a board so another PC can claim it

Problems? The troubleshooting section covers the ones seen so far.