Configuration
bluetooth-bridge reads one TOML file, /etc/bluetooth-bridge/config.toml
unless --config FILE names another. Only the transport is required:
[adapter]transport = "hci0"Everything else has a default. Unknown keys and wrong types are errors
(except in [scan], see the reference), so a typo stops the bridge at
startup. The configuration reference lists every
key; it is generated from the code, so it is always current.
A JSON Schema generated from the same code lets an editor with TOML schema support (Taplo, or VS Code’s Even Better TOML) complete and check the file. Point it at the schema with a first line of:
#:schema https://pulzar-net.github.io/bluetooth-bridge/config.schema.jsonThe tables
Section titled “The tables”| Table | What it sets |
|---|---|
[adapter] |
the transport, the GAP name and appearance, pairing (IO capability, passkey, bonding, MITM, Secure Connections only), and whether to use a random address |
[mqtt] |
broker host and port, user name, password file, client id, base topic, keep-alive |
[scan] |
whether to scan, active or passive, interval and window, coded PHY, filter accept list, duplicate filtering, an address allow list, a minimum RSSI, whether to publish every report |
[homeassistant] |
discovery on or off, the discovery prefix, Home Assistant’s status topic |
[data] |
the data directory |
[[bthome_keys]] |
bind keys of encrypted BTHome devices |
[[kkm_passwords]] |
passwords of KKM beacons with encrypted frames |
[[irks]] |
IRKs of devices known without pairing, so their private addresses resolve |
[[gatt_services]] |
GATT services the bridge serves to centrals |
[[advertising]] |
advertising sets started with the bridge |
[mesh] |
(since 0.2.0) make the bridge a Bluetooth Mesh provisioner |
Transports
Section titled “Transports”transport |
For |
|---|---|
hci0 (or hci1, …) |
a controller with a Linux kernel driver: built-in chips, USB dongles. Uses the HCI user channel. |
serial:/dev/ttyACM0:1000000 |
a UART controller with no kernel driver, H4 at that baud rate with RTS/CTS; append :noflow for none |
tcp:127.0.0.1:9000 |
H4 over TCP: Bumble’s virtual controller, or a network HCI bridge |
A complete example
Section titled “A complete example”config.example.toml
in the repository sets every key to its default, with comments, and shows
each list table commented out. CI checks that it parses.
# bluetooth-bridge configuration. Only [adapter] is required.
[adapter]# hci0 (Linux HCI user channel; stop bluetoothd first), serial:/dev/ttyACM0:1000000# for a UART controller, or tcp:127.0.0.1:9000 for a virtual controller.transport = "hci0"name = "bluetooth-bridge"# display_only, display_yes_no, keyboard_only, no_input_no_output, keyboard_displayio_capability = "no_input_no_output"# A fixed six-digit passkey, shown or typed when a pairing needs one.# passkey = 123456bonding = truemitm = falsesecure_connections_only = false# Use a static random address even when the controller has a public one.random_address = false
[mqtt]host = "localhost"port = 1883# username = "bluetooth"# password_file = "/etc/bluetooth-bridge/mqtt-password"client_id = "bluetooth-bridge"base_topic = "bluetooth"keepalive = 30
[scan]enabled = true# Active scanning sends scan requests (more data, more airtime).active = falseinterval_ms = 100window_ms = 100# Also scan the coded PHY (long range) when the controller has it.coded = truefilter_accept_list = false# off, changes, or { interval_ms = 10000 }: report a device when its data# changes and at least this often while it is heard.dedup = { interval_ms = 10000 }# Only these address prefixes (empty: everything).allow = []min_rssi = -127publish_reports = true
[homeassistant]enabled = truediscovery_prefix = "homeassistant"status_topic = "homeassistant/status"
[data]# Bonds and the bridge's own identity (IRK, static address), mode 0600.dir = "/var/lib/bluetooth-bridge"
# Encrypted BTHome devices.# [[bthome_keys]]# address = "A4:C1:38:00:00:01"# key = "231d39c1d7cc1ab1aee224cd096db932"
# Encrypted KKM sensor frames.# [[kkm_passwords]]# address = "BC:57:29:00:00:01"# password = "0000000000000000"
# Devices whose IRK is known without pairing: their private addresses# resolve to this identity.# [[irks]]# address = "C0:11:22:33:44:55/random"# irk = "ec0234a357c8ad05341010a60a397d9b"# label = "tag 1"
# A GATT service the bridge serves.# [[gatt_services]]# uuid = "12345678-1234-5678-1234-56789abcdef0"# [[gatt_services.characteristics]]# uuid = "12345678-1234-5678-1234-56789abcdef1"# properties = ["read", "write", "notify"]# read = "open"# write = "encrypted"# value = "00"
# An advertising set started with the bridge (AD structures, hex).# [[advertising]]# data = "0201060908627269646765"# params = { connectable = true, interval_min_ms = 200, interval_max_ms = 300 }Duplicate filtering and traffic
Section titled “Duplicate filtering and traffic”A busy site has thousands of advertisers, each repeating several times a
second. scan.dedup decides how much of that reaches MQTT:
dedup |
Publishes a device |
|---|---|
"off" |
on every advertisement received |
"changes" |
when its data changes |
{ interval_ms = 10000 } (default) |
when its data changes, and at least every 10 s while it is heard |
scan.allow (address prefixes such as "BC:57:29") and scan.min_rssi
narrow it further, and scan.publish_reports = false stops the per-report
scan/ topic while keeping decoded device/ readings.
The data directory
Section titled “The data directory”[data] dir (default /var/lib/bluetooth-bridge) holds the bonds (long
term keys and IRKs of paired devices) and the bridge’s own identity (its IRK
and static random address), written atomically with mode 0600. Back it up;
without it, bonded devices must pair again.
Logging
Section titled “Logging”The bridge logs to standard error at info unless RUST_LOG says
otherwise. RUST_LOG takes a default level and per-target levels, such as
debug or bluetooth_host=debug,info. During pairing, a passkey the
bridge shows is logged at info, so the person pairing can read it there.