Bluetooth Operations Manual
On this page
Separate the controller, pairing, connection and application profile. Pairing does not establish every connection; a connected headset may still receive no audio. Commands use BlueZ bluetoothctl with placeholder addresses.
| Task | Start here |
|---|---|
| Device not discovered | Controller and discovery |
| Paired but unusable | Pair, trust, connect |
| Disconnects or no audio | Layered diagnosis |
Ready the controller and make the device discoverable
Check service, radio switch, and controller separately
# Inspect the BlueZ daemon state
# Inspect software and hardware Bluetooth blocks
Hardware blocks require switch/firmware handling; software unblock applies to soft blocks.
# List local controllers and addresses
Do not confuse controller and headset addresses. If none exist, inspect driver/USB/firmware logs.
# Inspect power and capabilities of the default controller
# List known or discovered remote devices
This is neither a live-online nor a paired-only list; use info for state.
# Inspect controller initialization and connection errors
# Remove a soft block only when Bluetooth should be enabled
This is conditional, not a mandatory check step. Re-query rfkill; hardware blocks need separate handling.
list shows controllers; devices includes known/discovered devices, not only paired ones. Distinguish Powered from rfkill soft/hard blocking; software unblock cannot release a hardware switch. Select the intended adapter when several exist. Put the target in pairing mode and check competing hosts.
Verify three distinct states
| State | Meaning | Does not prove |
|---|---|---|
| Paired | Pairing credentials established | Currently online or audio working |
| Trusted | Local trust policy for device services | Unconditional auto-reconnect |
| Connected | A current connection exists | Every profile and application route works |
Enter these in interactive bluetoothctl, not a shell script. The agent handles confirmation/PIN; compare displayed codes. Some versions pair and also attempt trust/connect; verify the actual info state.
Enter one session and select the controller
# Open the BlueZ interactive session from the shell
Enter the text blocks at the bluetoothctl prompt without a bluetoothctl prefix. With multiple controllers, select the address from list; skip for one controller. The selection belongs to this process, not separate shell invocations.
select 11:22:33:44:55:66
Power on, then confirm Powered: yes with show. Resolve failures through rfkill/controller logs first.
power on
show
Register the pairing agent and scan
Register an agent in this attended session and keep it open for pairing prompts.
agent on
default-agent
Put the device into pairing mode, scan, and wait for the matching name/address before proceeding.
scan on
Inspect pairing before deciding trust and connection
Use the scanned device address, not the controller address. After pair, verify both devices’ codes and wait for success or failure before continuing.
pair AA:BB:CC:DD:EE:FF
Read the actual state. Skip later trust/connect actions if those states are already satisfied.
info AA:BB:CC:DD:EE:FF
Use trust only when this host should trust the device for subsequent services; it does not establish the current connection.
trust AA:BB:CC:DD:EE:FF
Connect when the device is online and needed now. Diagnose errors/profile instead of repeatedly recreating pairing credentials.
connect AA:BB:CC:DD:EE:FF
Recheck Connected: yes with info, then test actual input/audio. To revoke trust, use untrust with the real address in this session; disconnection is separate.
info AA:BB:CC:DD:EE:FF
Stop discovery and exit
Stop scanning when no longer needed, whether successful or not, then return to the shell. quit does not unpair the device.
scan off
quit
Act on the failing layer
| Symptom | Check and action |
|---|---|
| Empty scan | Power, rfkill, discovery window, distance; firmware/USB errors in logs |
| AuthenticationFailed | Check confirmation and stale pairing/other hosts; forget both ends only when re-pairing is needed |
| Connected headset is silent | Inspect wpctl status, profile and stream routing in media |
| Repeated disconnects | Correlate time, reason codes, battery and 2.4 GHz interference; capture a controlled reproduction with btmon |
Inspect state or deliberately disconnect
# Inspect device state from the shell
Use the real address and inspect Paired/Trusted/Connected and service UUIDs. For multiple adapters select and inspect in one interactive session.
# Disconnect the device while preserving pairing when desired
This is optional, not mandatory repair preparation. Verify Connected: no while pairing remains.
Capture HCI evidence during a controlled reproduction
# Start live Bluetooth event monitoring in one terminal
Reproduce once in another terminal, record time, then stop here with Ctrl-C. Correlate reason codes with service logs and review before sharing.
Disconnect retains pairing; remove deletes local pairing information and requires re-pairing. Restarting the service affects other devices. Review btmon captures for device identifiers and communication data before sharing.