bluetoothctl - What is a bluetooth agent?

I am using the bluetoothctl utility to set up Bluetooth connections between computers and Raspberry Pis.

In bluetoothctl, I can see there is something called an "agent", and by looking at most of tutorials, this "agent" has to be set "on" to create connections. I am trying to understand what is a bluetooth agent.

1) What is a bluetooth agent ?

2) What is the "default-agent" command in bluetoothctl for ? Can it be the same for all connections ?

3) What is the impact of not using an agent when setting up a connection ?

4) By looking at man bluetoothctl, it is said that agents can be set a capability. What is an agent capability ? What values could be put there ?

5) Do agents only exist with bluetooth ? Are there let's say wifi agents too ?

I am fairly new to the world of Bluetooth, and the documentation for bluetoothctl is quite limited... Any information would be appreciated.


The Bluetooth agent is what manages the Bluetooth 'pairing code'. It can either respond to a 'pairing code' coming in, or can send one out.

The default-agent should work for you. You say you're new to Bluetooth, so I suggest you go with the default for now.

Not using an agent will mean the 2 devices cannot negotiate the 'pairing code'.

An example might help, so here's an example of what worked for me on my Raspberry Pi 3 called Shep:

pi@shep:~/bluetooth $ bluetoothctl
[NEW] Controller B8:27:EB:B0:BC:22 shep [default]
[NEW] Device 18:9E:FC:94:8C:33 iPhone4
[bluetooth]# agent on
Agent registered
[bluetooth]# default-agent
Default agent request successful
[CHG] Device 18:9E:FC:94:8C:33 Connected: yes
[CHG] Device 18:9E:FC:94:8C:33 Connected: no

Here I asked the iPhone to pair with Shep, and iPhone sent 680044.

[CHG] Device 18:9E:FC:94:8C:33 Connected: yes
Request confirmation
[agent] Confirm passkey 680044 (yes/no): yes

Or see the following if you want to set the pass key in advance:

http://www.heatxsink.com/entry/how-to-pair-a-bluetooth-device-from-command-line-on-linux

Setup bluetooth-agent to pass the expected pairing code

$ bluetooth-agent 0000 &

Obviously the '0000' could be any number.

These agents and 'pairing codes' are specific to Bluetooth rather than Wi-Fi.