Bluetooth Connections


Pairing a Bluetooth Device

You need to "pair" your device with the host on which you wish to use it. You can pair a device with more than one host, but you can usually only use it with one host at a time.

On Linux

Pairing a Bluetooth device on Linux is relatively easy if you're comfortable working within the graphical (X) environment. All you need to do is to run bluetooth-applet and follow the steps it presents to you. It's a little trickier to pair a Bluetooth device via the command line, but it can be done. How to do it depends on the version of the Bluetooth software stack that you're using.

For Bluetooth Version 5

As of Bluetooth version 5, all required actions for pairing a device via the command-line can be performed with a single tool called bluetoothctl.

First, in case you have several Bluetooth controllers in use (uncommon, but possible), you need to make sure that the correct one is currently selected. Use the list command to show all available controllers, and the select <host-address> command to select one:

# bluetoothctl
[bluetooth]# list
Controller 01:23:45:67:89:AB fzidpc73
[bluetooth]# select 01:23:45:67:89:AB

It can happen that the selected controller is not powered on at the moment. Make sure it is, and, if it isn't, use the power on command to enable the controller:

[bluetooth]# show
Controller 01:23:45:67:89:AB
        Name: fzidpc73
        Alias: fzidpc73-0
        Class: 0x000000
        Powered: no
        Discoverable: no
        Pairable: yes
        UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
        UUID: Generic Access Profile    (00001800-0000-1000-8000-00805f9b34fb)
        UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
        Modalias: usb:v1D6Bp0246d0517
        Discovering: no
[bluetooth]# power on
[CHG] Controller 01:23:45:67:89:AB Class: 0x000104
Changing power on succeeded
[CHG] Controller 01:23:45:67:89:AB Powered: yes

To obtain the Bluetooth device address of the device you want to pair with, enable scan mode:

[bluetooth]# scan on
Discovery started
[CHG] Controller 01:23:45:67:89:AB Discovering: yes
[NEW] Device 12:34:56:78:9A:BC braillex live 0139
[bluetooth]# scan off
Discovery stopped
[CHG] Controller 01:23:45:67:89:AB Discovering: no

To be able to receive PIN code requests directly on the console, you need to enable the agent:

[bluetooth]# agent on
Agent registered

Now you are finally ready to initiate the pairing:

[bluetooth]# pair 12:34:56:78:9A:BC
Attempting to pair with 12:34:56:78:9A:BC
[CHG] Device 12:34:56:78:9A:BC Connected: yes
Request PIN code
[agent] Enter PIN code: 1234
[CHG] Device 12:34:56:78:9A:BC UUIDs:
[CHG] Device 12:34:56:78:9A:BC Paired: yes
Pairing successful
[CHG] Device 12:34:56:78:9A:BC Connected: no

For Bluetooth Version 4

You need to find out your host's Bluetooth Device Address (referred to later in this document as host-address). To do this, run the command:

hciconfig hci0

Look for the (indented) line which begins with BD Address:. The very next "word" on that line is your host's Bluetooth Device Address. It'll be six two-digit hexadecimal numbers separated by colons (:). Examples in this document use the value 01:23:45:67:89:AB.

You need to find out your device's Bluetooth Device Address (referred to later in this document as device-address). To do this, run the command:

hcitool scan

This command can take a while to complete as it gives devices a fair bit of time to respond. Each device which responds creates one two-column output line. The first column is its Bluetooth Device Address (examples in this document use the value 12:34:56:78:9A:BC), and the second column is its current name. Manufacturers usually set a device's initial name to its product name and model number so that it's easy to spot within the scan output. If your device allows you to change its name, it's okay to do so even after you've paired it.

A device needs to be "visible" in order for the scan to find it. Most devices are "invisible" by default, but have a way to be made temporarily visible. You should check your device's manual to find out how to do this. In many cases, there's either a button which needs to be pressed or a menu item which needs to be selected. Since both the device's temporary visibility and the host's scan time out, make your device visible just before you initiate the scan.

You need to know what PIN (password) your device is expecting. Your device's documentation should contain this information. Many devices allow you to set the PIN, in which case they'll have a menu which allows you to do this. Examples in this document use the value 1234.

Go into the directory /var/lib/bluetooth/<host-address>. In there (create if necessary) is the file pincodes. Each line in this file associates a device with its PIN. It has two fields separated by space. The first field is the device's Bluetooth Device Address and the second field is its PIN. The Bluetooth Device Address must be in uppercase. For example:

cat /var/lib/bluetooth/01:23:45:67:89:AB/pincodes
12:34:56:78:9A:BC 1234

Using a Bluetooth Device with BRLTTY

After your device has been paired with your host, it's ready to be used by BRLTTY.

Identifying the Device

You can tell BRLTTY to use your Bluetooth device either via the -d (or --braille-device=) command line option, or via the braille-device line in the file /etc/brltty.conf. The device should be specified as the word bluetooth, a colon (:), and the device's Bluetooth Device Address. For example:

brltty -d bluetooth:12:34:56:78:9A:BC


cat /etc/brltty.conf
braille-device bluetooth:12:34:56:78:9A:BC

On some platforms, BRLTTY supports the detection of a Bluetooth device based on its name. These platforms include:

  • Android
  • Linux (if the Bluetooth version is at least 5)
  • Windows

The address of the device needn't be specified on these platforms - specifying just bluetooth: is sufficient. BRLTTY will find the braille device based on its name. It'll only consider devices that have already been paired with the host.

If two (or more) braille devices are paired with your host, and if both of them are near by, turned on, and configured for Bluetooth access, then, of course, BRLTTY might choose the wrong one. As long as both of them don't have the same Bluetooth name, you can still specify the intended device without knowing its address. You can limit the devices that BRLTTY will consider by specifying the beginning of its Bluetooth name:


If you need to specify a space within the prefix, then:

  • On the command line, use quotes:

    -d "bluetooth:name=braille device"
  • In /etc/brltty.conf, use \s:

    braille-device bluetooth:name=braille\sdevice