Skip to content

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.

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

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.

  • 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.