Configuring a dumb, insecure Bluetooth connection

From One-Eyed Man Wiki
Jump to navigation Jump to search


A random combination of these commands will eventually get things working, maybe with a reboot and some adjustments to the sound system playback thrown in. Bluetooth behavior is maddeningly opaque.

Pairing manually

Note: Before using the Bluetooth device, make sure that it is not blocked by rfkill.

This section describes directly configuring bluez5 via the bluetoothctl CLI, which might not be necessary if you are using an alternative front-end tool (such as GNOME Bluetooth).

The exact procedure depends on the devices involved and their input functionality. What follows is a general outline of pairing a device using bluetoothctl.

Start the bluetoothctl interactive command. Input help to get a list of available commands.

  1. (optional) Select a default controller with select MAC_address.
  2. (optional) Enter power on to turn the power to the controller on if the device is set to off. It is on by default; see #Default adapter power state.
  3. Enter devices to get the MAC address of the device with which to pair.
  4. Enter device discovery mode with scan on command if device is not yet on the list.
  5. Turn the agent on with agent on or choose a specific agent: if you press tab twice after agent you should see a list of available agents. A 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 be appropriate in most cases.[1]
  6. Enter pair MAC_address to do the pairing (tab completion works).
  7. If using a device without a PIN, one may need to manually trust the device before it can reconnect successfully. Enter trust MAC_address to do so.
  8. Enter connect MAC_address to establish a connection.

An example session may look this way:

$ bluetoothctl
[NEW] Controller 00:10:20:30:40:50 hostname [default]
[bluetooth]# agent KeyboardOnly
Agent registered
[bluetooth]# default-agent
Default agent request successful
[bluetooth]# power on
Changing power on succeeded
[CHG] Controller 00:10:20:30:40:50 Powered: yes
[bluetooth]# scan on
Discovery started
[CHG] Controller 00:10:20:30:40:50 Discovering: yes
[NEW] Device 00:12:34:56:78:90 device name
[CHG] Device 00:12:34:56:78:90 LegacyPairing: yes
[bluetooth]# pair 00:12:34:56:78:90
Attempting to pair with 00:12:34:56:78:90
[CHG] Device 00:12:34:56:78:90 Connected: yes
[CHG] Device 00:12:34:56:78:90 Connected: no
[CHG] Device 00:12:34:56:78:90 Connected: yes
Request PIN code
[agent] Enter PIN code: 1234
[CHG] Device 00:12:34:56:78:90 Paired: yes
Pairing successful
[CHG] Device 00:12:34:56:78:90 Connected: no
[bluetooth]# connect 00:12:34:56:78:90
Attempting to connect to 00:12:34:56:78:90
[CHG] Device 00:12:34:56:78:90 Connected: yes
Connection successful

Or, when none of that is working ...

I have gotten things working by using the Enlightenment Settings/Bluetooth Devices GUI utility. Better yet, with bluetoothctl open on the target so I can see the logging. The GUI also pleasantly displays up-and-down network stats.


To automate bluetoothctl commands, use echo -e "command1\ncommand2\n" | bluetoothctl or bluetoothctl -- command.

To unpair a device: In bluetoothctl, issue paired-devices to see a list of device MACs, then remove [MAC].