bluetooth-bridge
bluetooth-bridge is a Bluetooth host stack that runs directly on HCI, and a Bluetooth LE to MQTT bridge, written in Rust. It drives a Bluetooth controller with no BlueZ and no D-Bus, decodes beacons and sensors, and publishes them to MQTT with Home Assistant discovery; connections, GATT, pairing and advertising are MQTT requests. It is a single static binary with no runtime, small enough for routers and gateways, and a set of library crates for anyone building Bluetooth software in Rust.
This site is the user guide and the reference. The README is the two-minute overview; the API docs cover every type and function.
Where to start
Section titled “Where to start”| You want to | Read |
|---|---|
| try it without hardware | Getting started |
| run it with a controller | Installation, then Hardware |
| see sensors in Home Assistant | Sensors and beacons, Home Assistant |
| connect to a device, read and write GATT | Connections, GATT and pairing |
| script it or build on its topics | MQTT API |
| change a setting | Configuration and the reference |
| embed the stack in Rust | Library overview |
| understand how it works | Architecture |
| fix a problem | Troubleshooting and FAQ |
Status
Section titled “Status”bluetooth-bridge is at 0.x. Version 0.1.0 is Bluetooth LE; 0.2.0 adds the first part of Bluetooth Mesh, and the rest is in progress. Everything is tested in CI against Bumble’s virtual controller, but no release has been tested on real hardware yet. Pages that describe something only real hardware can confirm say so.
Bluetooth® is a registered trademark of the Bluetooth SIG, Inc. This project is not affiliated with or qualified by the Bluetooth SIG.
Terms used in these docs
Section titled “Terms used in these docs”- Controller: the Bluetooth chip, on a board, a USB dongle or a UART. It runs the radio and the link layer and speaks HCI (the Host Controller Interface) to the host.
- Host: the software above HCI. Usually that is the kernel and BlueZ; with bluetooth-bridge it is this stack, running as one process.
- HCI user channel: a Linux socket that gives one program exclusive, raw access to a controller the kernel’s driver has set up.
- H4: HCI over a byte stream (a UART, or TCP).
- Address: six bytes, written
C0:11:22:33:44:55, public or random. Devices with privacy use resolvable private addresses that change every few minutes; with the device’s IRK they resolve to its stable identity address. - Advertisement: a broadcast packet. Sensors and beacons put their readings in advertisements; nothing needs to connect to them.
- GATT: the attribute protocol used over a connection: services, characteristics, reads, writes and notifications.
- Bond: the keys two devices keep after pairing, so they can encrypt again without pairing.