Skip to content

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

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_display
io_capability = "no_input_no_output"
# A fixed six-digit passkey, shown or typed when a pairing needs one.
# passkey = 123456
bonding = true
mitm = false
secure_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 = false
interval_ms = 100
window_ms = 100
# Also scan the coded PHY (long range) when the controller has it.
coded = true
filter_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 = -127
publish_reports = true
[homeassistant]
enabled = true
discovery_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 }

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.

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

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.