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.

1 Answer 1


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:


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.

  • Thanks Geoff. Good clarification. Plus the link you provided me explains how to set up a serial connection through the Bluetooth, which was my next issue. Commented Apr 28, 2016 at 17:37
  • 1
    It seems bluetooth-agent isn't available on xenial. Some googling suggests that it used to be part of the bluez package. Any thoughts on how to set the pass key in advance on xenial? Commented Oct 2, 2017 at 15:09
  • 2
    @cheshirekow check out bt-agent in bluez-tools Commented Mar 30, 2018 at 17:58

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .