Hardware Adapters and Troubleshooting

Hardware, Adapters & Troubleshooting

Adapters

Caeruleus uses whatever BlueZ exposes. The default adapter is hci0; target another with -i hciN. Both built-in (USB or UART-attached) controllers and USB dongles work. caeruleus adapter info shows the current state.

• USB dongles are the simplest: plug in, caeruleus doctor, go.
• UART-attached controllers (e.g. Raspberry Pi onboard BT) are supported, including for raw operations. Raw (HCI user-channel) commands auto-manage bluetoothd and the controller recovers via HCIDEVUP. The one hazard is re-running hciattach/btattach (hciuart) on an already-attached UART controller, which can wedge it and require a reboot — doctor will warn when the transport is UART.

doctor: first stop when something's off

caeruleus doctor walks BlueZ and kernel state and prints an OK/WARN/FAIL checklist, each non-OK item with a concrete fix command. It verifies bluetoothd is running, the adapter is powered, no stale discovery session is leaked, the BlueZ-cached address matches the MGMT chip-live address, LE scanning works (a 2-second probe), and ExchangeMTU is in a safe band. Exit code follows grep/diff convention: 0 all-clear, 2 when a check fails.

Common issues

Missing services, or handles that look wrong (older BlueZ). BlueZ around 5.55 omits the remote GAP (0x1800) / GATT services from its D-Bus GATT tree, so enumerate can miss characteristics (e.g. Device Name 0x2A00) and report handles offset from the device's true ATT handles. Run sudo caeruleus enumerate -b <mac> --raw to walk the database directly over ATT — a complete, host-independent view with the device's true value handles, then read --raw -a <handle> to read those handles.

Connect fails / "Input/output error".

• Pass --addr-type random (or public). scan shows each device's type; some peripherals only accept one.
• An MTU mismatch can block a connection, not just truncate reads. caeruleus mtu -b <mac> --set 247 is a reasonable first try (note: --set is global and restarts bluetoothd; root).

"Operation already in progress" / Connected=true that won't clear.

• caeruleus forget -b <mac> then retry, or caeruleus adapter power cycle. doctor suggests the fix.

Ghost connection after a crash. Caeruleus disconnects cleanly on SIGTERM/SIGHUP (it polls until Connected=false propagates), so the peripheral re-advertises immediately. If a different tool left a stuck link, forget / adapter power cycle clears it.

Single-connection peripherals. Many small devices accept one central at a time. Caeruleus disconnects on exit; for many back-to-back operations, hold one warm link with serve + send (see Output & Automation).

Stuck UART controller. If a UART controller wedges, a full reboot recovers it; do not systemctl restart hciuart while it's attached — that can make it worse. Leave hciuart alone.

Adapter MAC (bdaddr)

sudo caeruleus bdaddr --show reads the controller BD_ADDR; --set <mac> spoofs it via a vendor HCI write. This is per-controller and chip-dependent (works on some CSR/Intel/Broadcom parts, silently no-ops or reverts on others). With multiple adapters, use -i hciN to target the one that accepts it; the default hci0 may not be spoofable.

Notes & gotchas

• MTU changes are global and gated. mtu --set/--reset edit /etc/bluetooth/main.conf and restart bluetoothd, affecting every adapter on the host. They prompt on a TTY (pass -y for scripts).
• Assessments are non-destructive by default. assess wwr and assess dfu --probe-entry are the exceptions and can reset the target.
• Pairing rejection is a result, not a failure. pair and assess encryption exit 0 and record it.

FAQ

Why won't it connect even though scan sees the device? Almost always the address type — retry with --addr-type random/public — or an MTU mismatch (try mtu --set 247), or the device already has a central connected.

Do I need root? Only for conn-params, monitor, fuzz write --raw, cccd --raw, raw-write, mtu --set/--reset, and bdaddr --set. Everything else runs over BlueZ D-Bus unprivileged. See Installation & Setup for a scoped sudoers drop-in.

Does it run on macOS/Windows? No. Caeruleus is Linux/BlueZ only.

Can it sniff traffic or do MITM? No — central only. No traffic sniffing of other devices, no active MITM, no peripheral cloning.