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.
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
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
/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>
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.
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.