Linux bluetooth setup with bluez and hcitool

Bluetooth devices are quite ubiquitous today, found almost everywhere, simple and cheap way to add wireless connectivity to a device.

A Linux system could use many protocol like OBEX, A2DP, DUN, HID etc. etc. to interact with different devices for different purpose. So how to connect, pair and manage those bluetooth devices from a Linux PC, let's start.

Part 2 of this tutorial is published, Setup bluetooth in Linux part 2

Initial Linux bluetooth setup

Most bluetoth adapters are USB based and could be configured with HCI utilities, some bluetooth devices like Atheros bluetooth adapters may require device firmware installed in the system.

To install required software packages on Debain or other Debian derivatives like Ubuntu, Linux Mint run the commands below.

sudo apt-get install bluetooth bluez bluez-tools rfkill rfcomm

The next may be necessary for proper functioning of the bluetooth adapter, you may want to replace firmware-atheros package with the firmware package that matches your device like firmware-realtek .

sudo apt-get install bluez-firmware firmware-atheros

Now start the bluetooth service and enable automatic startup, assuming you're using systemd as the init daemon.

sudo systemctl start bluetooth.service
sudo systemctl enable bluetooth.service

hcitool scan for bluetooth devices

Before start scanning make sure that your bluetooth device is turned on and not blocked, you can check that with the rfkill command.

sudo rfkill list

If the bluetooth device is blocked (soft or hard blocked), unblock it with the rfkill command again

sudo rfkill unblock bluetooth

Bring up the bluetooth device with hciconfig command and start scanning, make sure the target device's bluetooth is on and It's discoverable.

sudo hciconfig hci0 up

hcitool scan

Wait few moment to complete the hcitool scan, the results will be something like bellow.

Scanning ...
       83:23:26:15:54:46      sat_P

Here 83:23:26:15:54:46 is the bluetooth MAC address and sat_P is the name of the bluetooth device, i.e. an Android phone.

Bluetooth service discovery

Now we have the bluetooth MAC address of the target device, use the sdptool command to know which services (like DUN, Handsfree audio) are available on that target device.

sdptool browse 83:23:26:15:54:46

Check the output of the sdptool command, you may want to filter the result with the grep command.

sdptool browse 83:23:26:15:54:46 | grep 'Service Name:'

You can also use the interactive bluetoothctl tool for this purpose.

$ bluetoothctl

[bluetooth]# info 83:23:26:15:54:46

Device 83:23:26:15:54:46
Name: sat_P

Alias: Nokia
Class: 0x580204
Icon: phone
Paired: yes
Trusted: yes
Blocked: no
Connected: no
LegacyPairing: no
UUID: OBEX Object Push (00001105-0000-1000-8000-00805f9b34fb)
UUID: Audio Source (0000110a-0000-1000-8000-00805f9b34fb)
UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
UUID: Handsfree Audio Gateway (0000111f-0000-1000-8000-00805f9b34fb)

Ping bluetooth devices:  If the target device is present, you can ping it with l2ping command, requires root privilege

sudo l2ping <Target device MAC address>

sudo l2ping 83:23:26:15:54:46         # Example

So, bluetooth service discovery is useful to determine the type of the device, like if it's a bluetooth mp3 player or it's a keyboard.

hcitool connect and pair devices

Connecting to the bluetooth device with rfcomm, this command requires root privilege, so use sudo .

sudo rfcomm connect <bluetooth host device> <Target bluetooth device MAC> <channel>

An exaple of connecting bluetooth hot device hci0 to a client device on channel 2

sudo rfcomm connect hci0 83:23:26:15:54:46 2

The device/phone will prompt to accept this connection request. Now the bluetooth client device should be available as /dev/rfcomm0 .

Send file through OBEX/OPP to a remote bluetooth device, the first command is a generic example

sudo bt-obex -p <Bluetooth remote device mac address> /path/to/file

sudo bt-obex -p 83:23:26:15:54:46 ~/img/some_pic.png

Now receive some file from the remote device, an OBEX server example, first start bt-obex in server mode listening for bluetooth connection.

bt-obex -s /path/to/output/folder

Replace /path/to/output/folder with a folder of your choice, like /tmp . Now send some file from the bluetooth client device, i.e. a phone. The sent file should be in the bt-obex output folder.

Below how to start a FTP session with the bt-obex command.

sudo bt-obex -f <Remote device MAC address>

hcitool commands

So, you've got a basic idea of using the the hcitool command to configure bluetooth devices on Linux.

Here's a list of almost every parameter related with the command. Anyway you can run the hcitool -h command to get a short overview of same, and the man pages are always helpful.

How to use these arguments? Fist if you have multiple bluetooth adapters, and want to use a specific device, then use use the -i flag, like below.

To get the list of available bluetooth devices, just use hcitool dev command.

Then run your desired command like below,

hcitool -i hciX  <command> <command parameters>

An example below, you may need to use sudo to run few commands, such as scanning.

sudo hcitool -i hci0 scan

Scanning ...
    00:00:00:00:5A:AD    MI4

sudo hcitool -i hci1 lescan

LE Scan ...
    EA:29:15:15:E8:A1 Keyboard K375s
    EA:29:15:15:E8:A1 (unknown)
    ..................

You need to stop the BLE device scan manually with Ctrl +C key combination.

I used a USB bluetooth adapter, hci1 in this case to scan a Logitech keyboard. Which is a BLE device, can't be detected by my laptop's default bluetooth device.

Note: If the -i flag is not used, then the first available local bluetooth device will be used. Now the list of commands.

dev	Display local devices.
inq	Inquire remote devices. For each discovered device, Bluetooth device address, clock offset and class are printed.
scan	Inquire remote devices. For each discovered device, device name are printed.
name <bdaddr>	Print device name of remote device with Bluetooth addressbdaddr.
info <bdaddr>	Print device name, version and supported features of remote device with Bluetooth address bdaddr.
spinq	Start periodic inquiry process. No inquiry results are printed.
epinq	Exit periodic inquiry process.
cmd <ogf> <ocf> [parameters]	Submit an arbitrary HCI command to local device. ogf, ocf and parameters are hexadecimal bytes.
con	Display active baseband connections
cc [--role=m|s] [--pkt-type=<ptype>] <bdaddr>	Create baseband connection to remote device with Bluetooth address bdaddr. Option --pkt-type specifies a list of allowed packet types. <ptype> is a comma-separated list of packet types, where the possible packet types are DM1, DM3, DM5, DH1,DH3, DH5, HV1, HV2, HV3. Default is to allow all packet types. Option --role can have value m (do not allow role switch, stay master) or s (allow role switch, become slave if the peer asks to become master). Default is m.
dc <bdaddr> [reason]	Delete baseband connection from remote device with Bluetooth address bdaddr. The reason can be one of the Bluetooth HCI error codes. Default is 19 for user ended connections. The value must be given in decimal.
sr <bdaddr> <role>	Switch role for the baseband connection from the remote device to master or slave.
cpt <bdaddr> <packet types>	Change packet types for baseband connection to device with Bluetooth address bdaddr. packet types is a comma-separated list of packet types, where the possible packet types are DM1,DM3, DM5, DH1, DH3, DH5, HV1, HV2, HV3.
rssi <bdaddr>	Display received signal strength information for the connection to the device with Bluetooth address bdaddr.
lq <bdaddr>	Display link quality for the connection to the device with Bluetooth address bdaddr.
tpl <bdaddr> [type]	Display transmit power level for the connection to the device with Bluetooth address bdaddr. The type can be 0 for the current transmit power level (which is default) or 1 for the maximum transmit power level.
afh <bdaddr>	Display AFH channel map for the connection to the device with Bluetooth address bdaddr.
lp <bdaddr> [value]	With no value, displays link policy settings for the connection to the device with Bluetooth address bdaddr. Ifvalue is given, sets the link policy settings for that connection to value. Possible values are RSWITCH, HOLD, SNIFF and PARK.
lst <bdaddr> [value]	With no value, displays link supervision timeout for the connection to the device with Bluetooth address bdaddr. Ifvalue is given, sets the link supervision timeout for that connection to value slots, or to infinite if value is 0.
auth <bdaddr>	Request authentication for the device with Bluetooth address bdaddr.

---

enc <bdaddr> [encrypt enable]	Enable or disable the encryption for the device with Bluetooth address bdaddr.
key <bdaddr>	Change the connection link key for the device with Bluetooth address bdaddr.
clkoff <bdaddr>	Read the clock offset for the device with Bluetooth address bdaddr.
clock [bdaddr] [which clock]	Read the clock for the device with Bluetooth address bdaddr. The clock can be 0 for the local clock or 1 for the piconet clock (which is default).
lescan [--privacy] [--passive] [--whitelist] [--discovery=g|l] [--duplicates]	Start Bluetooth BLE scan
leinfo [--static] [--random] <bdaddr>	Get LE remote information
lewladd [--random] <bdaddr>	Add device to LE White List
lewlrm <bdaddr>	Remove device from LE White List
lewlsz	Read size of LE White List
lewlclr	Clear LE White List
lerladd [--local irk] [--peer irk] [--random] <bdaddr>	Add device to LE Resolving List
lerlrm <bdaddr>	Remove device from LE Resolving List
lerlclr	Clear LE Resolving List
lerlsz	Read size of LE Resolving List
lerlon	Enable LE Address Resolution
lerloff	Disable LE Address Resolution
lecc [--static] [--random] <bdaddr> | [--whitelist]	Create a LE Connection
ledc <handle> [reason]	Disconnect a LE Connection
lecup <handle> <min> <max> <latency> <timeout>	LE Connection Update

This list is a direct copy paste of the hcitool man page, but better organized.

Conclusion

I tested those above commands with three phones, Mi 4, which is Android, a SANSUNG Z3, which is Tizen and a symbian Nokia 5230, and all functions are working fine except Handsfree audio.

In the next tutorial about bluetoth I'll discuss about how to setup a dial-up internet connection via bluetooth in Linux.

Managing bluetooth devices could be even more easier with graphical tools like bluedevil for KDE desktop, Gnome-Bluetooth for Gnome desktop or general purpose Gtk2 application blueman.

So when these commands are useful ? For headless servers, single board computers like Raspberry Pi or machines accessed form a SSH server, or simply knowing what's going on behind the scene.

If you have any suggestion or question just leave a comment, also don't forget to share this with your friends.