This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!
BlueZ is an implementation of the Bluetooth protocol stack for Linux. It is a Linux standard for the short-range wireless interconnection of cellular phones, computers, and other electronic devices.
Table of contents¶
$ cd /usr/src/linux # make nconfig # or `make menuconfig` # BLUEHOOTH ########### # Double check here: <https://wiki.gentoo.org/wiki/Bluetooth> # Double check the prerequisites: <https://wiki.gentoo.org/wiki/Bluetooth#Prerequisites> # > [*] Networking support ---> # Symbol: NET [=y] > <M> Bluetooth subsystem support ---> # Symbol: BT [=m] > [*] Bluetooth Classic (BR/EDR) features # Symbol: BT_BREDR [=y] > <*> RFCOMM protocol support # Symbol: BT_RFCOMM [=y] > [ ] RFCOMM TTY support # Symbol: BT_RFCOMM_TTY [=n] > < > BNEP protocol support # Symbol: BT_BNEP [=n] > [ ] Multicast filter support # Symbol: BT_BNEP_MC_FILTER [=n] > [ ] Protocol filter support # Symbol: BT_BNEP_PROTO_FILTER [=n] > <*> HIDP protocol support # Symbol: BT_HIDP [=y] > [*] Bluetooth High Speed (HS) features # Symbol: BT_HS [=y] > ... > [*] Bluetooth Low Energy (LE) features # Symbol: BT_LE [=y] > Bluetooth device drivers ---> > <M> HCI USB driver # Symbol: BT_HCIBTUSB [=m] > <M> HCI UART driver # Symbol: BT_HCIUART [=m] > <*> RF switch subsystem support ---> # Symbol: RFKILL [=y] > Device Drivers ---> > HID support ---> > <*> User-space I/O driver support for HID subsystem # Symbol: UHID [=y]
After configuring the kernel don't forget to do a kernel make and rebuild!
hciconfigand other utilities are only available if
net-wireless/bluezis installed with the deprecated USE flag enabled:
Permissions for Bluetooth devices is handled automatically by D-Bus, and access is granted to all users by default.
Depending on your
runitimplementation, either run:or run:or run:In any case, finally run:
Optionally start Bluetooth at boot:
Depending on your
runitimplementation, either run:
- (OPTIONAL) Select a default controller with
$ bluetoothctl select <MAC address>.
- (OPTIONAL) Enter
$ bluetoothctl power onto turn the power to the controller on if the device is set to off. It is on by default.
$ bluetoothctl devicesto get the MAC address of the device with which to pair.
- Enter device discovery mode with
$ bluetoothctl scan oncommand if device is not yet on the list.
- Turn the agent on with
$ bluetoothctl agent onor 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.
$ bluetoothctl pair <MAC address>to do the pairing (tab completion works).
- If using a device without a PIN, one may need to manually trust the device before it can
reconnect successfully. Enter
$ bluetoothctl trust <MAC address>to do so.
$ bluetoothctl connect <MAC address>to establish a connection.
First, power on your bluetooth device, and enable its pairing mode, then:
$ bluetoothctl power on $ bluetoothctl scan on Discovery started [CHG] Controller 05:EB:67:76:CD:64 Discovering: yes [NEW] Device 69:1B:AB:45:19:A5 69-1B-AB-45-29-A5 [NEW] Device 7F:D7:15:68:B3:CB 7F-D7-15-68-B3-CB [NEW] Device 8C:B2:C4:A6:3C:4B 8C-B2-C4-A6-3C-4B [NEW] Device 31:85:DA:BF:57:A8 Your Device Name Here ... $ bluetoothctl pair 31:85:DA:BF:57:A8 $ bluetoothctl devices ... Device 31:85:DA:BF:57:A8 Your Device Name Here $ bluetoothctl info 31:85:DA:BF:57:A8 $ bluetoothctl trust 31:85:DA:BF:57:A8 # OPTIONAL if not already trusted $ bluetoothctl unblock 31:85:DA:BF:57:A8 # OPTIONAL if blocked
First, pair your Bluetooth device (see previous section), then:
Failed to connect: org.bluez.Error.Failed br-connection-profile-unavailable¶
If you are facing the above error message on an Arch-based distros, then :
- if you just installed the
bluez related packages, then a simple reboot might enough.
- if you installed the
bluez related packages in a previous session and you are using
pulseaudio, then you might want to install
pulseaudio-bluetooth and reboot.
If this cheat sheet has been useful to you, then please consider leaving a star here.