Last changed: 30.09.2017

Configure bluetooth via command line in Linux

Almost everyone of us has used bluetooth connections before but only very few have ever looked into configuring the devices via command line. Below you can find some of the most usefull commands.

At the bottom I document some steps needed to control pulseaudio via the command line to connect an audio input with a bluetooth headset as the output sink.

setup bluetooth device

list bluetooth devices

hcitool dev
hciconfig

change bluetooth name

hciconfig hci0 name
hciconfig hci0 name <NEWNAME>

change bluetooth address

The bdaddr of bluetooth controllers with a CSR chipset can be changed.

bccmd psset -s 0 bdaddr 0x44 0x00 0x66 0x55 0x33 0x00 0x22 0x11
bccmd warmreset

scan for bluetooth devices

inquiry scan

hcitool inq

name scan

This command does an inquiry scan and connects to all discovered devices for a remote name request afterwards.

hcitool scan

bluetooth LE scan

hcitool lescan

bluetooth ping

l2ping <bdaddr>

request available services

sdptool browse <bdaddr> | grep 'Service Name'

list known controllers and devices

The bluetooth daemon stores information about known controllers and devices in the path /var/lib/bluetooth. With ls, find and grep you can print out which controllers have been connected to your machine and which bluetooth devices have been seen.

ls -1 /var/lib/bluetooth
find /var/lib/bluetooth/ -name cache -exec grep -r Name {} \;

bluetoothctl

To connect a bluetooth device I use the tool bluetoothctl.

start bluetoothctl

systemctl start bluetooth
bluetoothctl

scan with bluetoothctl

Before you are allowed to pair with a new device this device has to be discovered by the bluetooth daemon using scanning.

list
show
scan on
scan off

pair and connect with bluetoothctl

Certain devices need a special agent to support pairing. E.g. if you want to pair a keyboard which does not have some kind of display you need to use the agent KeyboardOnly.

agent KeyboardOnly
pair <bdaddr>
agent off 
connect <bdaddr>

configure a bluetooth headset with pulseaudio

If you have pulseaudio-bluetooth installed a connected bluetooth headset should be automatically detected as an audio sink by pulseaudio. To configure the audio output I use pactl.

change card profile

pactl list cards
pactl set-card-profile <card_id> headset_head_unit
pactl set-card-profile <card_id> a2dp_sink

configure audio sink

pactl list sinks [short]
pactl set-default-sink <sink_id>
pactl list sink-inputs [short]
pactl move-sink-input <sink_input_id> <sink_id>
pactl set-sink-volume <sink_id> 40%

connect microphone to a2dp_sink

pactl load-module module-loopback latency_msec=1
pactl list sources
pactl list sinks
pactl list sink-inputs
pactl list source-outputs
pactl move-sink-input <loopback_sink_id> <sink_id>
pactl move-source-output <loopback_source_id> <source_id>
pactl set-source-mute <source_id> 0
pactl set-source-volume <source_id> 30%

change master/slave role

Under certain circumstances it may be required to switch the roles of your connected device.

show connections

hcitool con

switch role

sudo hcitool sr <device bdaddr> slave
sudo hcitool sr <device bdaddr> master

send file via obex object push

using bt-obex

rfcomm connect hci0 <bdaddr> <channel>
bt-obex -p <bdaddr> /path/to/file

using obexctl

systemctl --user start obex
obexctl
connect <bdaddr>
send /path/to/file