aeondave/bluez

BlueZ

Linux Bluetooth stack and operator toolkit for Bluetooth Classic and BLE discovery, connection, and debugging.

Why BlueZ

Use BlueZ as the baseline Bluetooth skill when you need:

• adapter bring-up and health checks
• BLE or Classic discovery from Linux
• pairing / trust / connection workflows
• Bluetooth service and characteristic inspection
• low-level monitoring and debugging

Quick Start

# verify controller state
bluetoothctl list
bluetoothctl show

# interactive discovery
bluetoothctl
[bluetooth]# power on
[bluetooth]# agent on
[bluetooth]# default-agent
[bluetooth]# scan on

Core Workflows

Live device discovery

bluetoothctl scan on

Pair and trust a device

bluetoothctl
[bluetooth]# pair AA:BB:CC:DD:EE:FF
[bluetooth]# trust AA:BB:CC:DD:EE:FF
[bluetooth]# connect AA:BB:CC:DD:EE:FF

Low-level monitor / troubleshooting

btmon

Use btmon when pairing, advertising visibility, or GATT behavior is unclear.

Practical Scope

BlueZ is the foundation. Prefer it before niche scanners because:

• it is current and maintained upstream
• it ships the real Linux Bluetooth stack
• it exposes both high-level and low-level workflows

Notes on Older Utilities

Older tooling such as gatttool or some deprecated tools may still appear in guides, but modern workflows should prefer current BlueZ client tooling where possible.

Relationship to Other Wireless Skills

| Skill | Best use | |---|---| | bluez | Core Linux Bluetooth discovery, pairing, monitoring | | kismet | Passive multi-RF visibility including Bluetooth with supported hardware | | sparrow-wifi | GUI/agent Bluetooth awareness plus Wi‑Fi/HackRF/Ubertooth workflows |

Resources

| File | When to load | |---|---| | references/scan-read-debug-workflow.md | For bluetoothctl, BLE scanning, service inspection, and monitor-first debugging workflows |