bluez-simple-agent

bluez-simple-agent [-i ADAPTER] [-c CAPABILITY] [-d] [OBJECT_PATH]

-i, --adapter=ADAPTER
    Specify Bluetooth adapter name (e.g., hci0)

-c, --capability=CAPABILITY
    Agent capability: DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay, KeyboardInteractive

-d, --debug
    Enable debug output for troubleshooting

OBJECT_PATH
    Optional DBus object path for agent registration (default: /test/agent)

The bluez-simple-agent is a lightweight utility from the BlueZ Bluetooth stack for Linux, designed to handle Bluetooth device pairing and authorization requests. It acts as a DBus agent registered with the BlueZ daemon (bluetoothd), responding to events like PIN requests, passkey confirmations, and authorization prompts.

It supports various agent capabilities matching device input/output types, such as keyboards, displays, or no I/O. Users invoke it to simplify pairing workflows, especially for scripts or minimal setups where full GUI agents are unnecessary.

Upon startup, it registers on a specified DBus object path (default: /test/agent) and listens for requests. For example, when pairing a device, it prompts the user via stdin for input or displays confirmations. Debug mode aids troubleshooting connection issues.

Common in embedded systems, IoT devices, or testing environments, it bridges simple command-line interaction with BlueZ's pairing protocols (SSP - Secure Simple Pairing). While bluetoothctl offers interactive pairing in modern BlueZ versions, bluez-simple-agent remains useful for automated or custom agent logic.

Deprecated in favor of bluetoothctl for interactive use; requires running BlueZ daemon; stdin prompts may not suit headless environments.
Capabilities must match device I/O to avoid pairing failures.

bluez-simple-agent -c KeyboardDisplay
Registers agent for keyboard/display capable devices.

NoInputNoOutput: Auto-pair numeric comparison.
DisplayOnly: Just show passkey.
KeyboardOnly: Enter passkey.
DisplayYesNo: Confirm pairing yes/no.
KeyboardDisplay: Enter/confirm passkey.
KeyboardInteractive: Full PIN/passkey handling.

Introduced in BlueZ 4.x as a Python-based example agent (~2008); evolved in BlueZ 5.x with SSP support; maintained for compatibility but overshadowed by bluetoothctl since BlueZ 5.40+ (2016).

bluetoothctl(1), bluetoothd(8), hciconfig(8), hcitool(8)