Bluetooth
This article describes the configuration and usage of Bluetooth controllers and devices.
Prerequisites
This article assumes that udev and USB have been previously configured.
Installation
Kernel
In most cases enabling RFCOMM (CONFIG_BT_RFCOMM), HIDP (CONFIG_BT_HIDP), HCI USB (CONFIG_BT_HCIBTUSB) and/or HCI UART (CONFIG_BT_HCIUART) should be sufficient. The User-space I/O driver for HID input devices (CONFIG_UHID) should be enabled for Bluetooth keyboards and mice.
[*] Networking support --->
<M> Bluetooth subsystem support --->
[*] Bluetooth Classic (BR/EDR) features
<*> RFCOMM protocol support
[ ] RFCOMM TTY support
< > BNEP protocol support
[ ] Multicast filter support
[ ] Protocol filter support
<*> HIDP protocol support
[*] Bluetooth High Speed (HS) features
[*] Bluetooth Low Energy (LE) features
Bluetooth device drivers --->
<M> HCI USB driver
<M> HCI UART driver
<*> RF switch subsystem support --->
Device Drivers --->
HID bus support --->
<*> User-space I/O driver support for HID subsystem
Kernel may fail to initialize RFCOMM/BNEP being compiled as built-in. System log for bluetooth service in this case will mention the lack of RFCOMM/BNEP support. And this in turn for example may break HSP/HFP headset profile initialization. So if dmesg says nothing about RFCOMM, better recompile as a module.
Firmware
Most Bluetooth controllers need firmware to function. If the controller is supported by Linux, dmesg will usually indicate if firmware is needed. The sys-kernel/linux-firmware package should provide the needed firmware, although some devices may need firmware that available in other package or provided only from the manufacturer.
root #
emerge --ask --noreplace sys-kernel/linux-firmware
USE flags
BlueZ is an implementation of the Bluetooth protocol stack for Linux, and it is provided by the net-wireless/bluez package.
USE flags for net-wireless/bluez Bluetooth Tools and System Daemons for Linux
+mesh
|
Add support for Bluetooth Mesh control application and advertising bearer. |
+obex
|
Enable OBEX transfer support |
+readline
|
Enable support for libreadline, a GNU line-editing library that almost everyone wants |
+udev
|
Enable virtual/udev integration (device discovery, power and storage device support, etc) |
btpclient
|
Enable BTP client |
cups
|
Add support for CUPS (Common Unix Printing System) |
debug
|
Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces |
deprecated
|
Build deprecated plugins |
doc
|
Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally |
experimental
|
Build experimental plugins |
extra-tools
|
Install tools that upstream doesn't install on purpose by default. All this tools shouldn't be used. Then, please notify upstream about you still need them to let them know the situation. |
man
|
Build and install man pages |
midi
|
Enable MIDI support |
selinux
|
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur |
systemd
|
Enable use of systemd-specific libraries and features like socket activation or session tracking |
test
|
Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently) |
test-programs
|
Install tools for testing of various Bluetooth functions |
Bluetooth support can be enabled system-wide by setting the USE variable to bluetooth
:
USE="bluetooth"
Emerge
The system needs to be updated if the USE variable was set to bluetooth
:
root #
emerge --ask --changed-use --deep @world
Install BlueZ:
root #
emerge --ask --noreplace net-wireless/bluez
Configuration
Permissions
Permissions for Bluetooth devices is handled automatically by D-Bus, and access is granted to all users by default.
Services
OpenRC
Start bluetooth:
root #
rc-service bluetooth start
Start bluetooth at boot:
root #
rc-update add bluetooth default
systemd
Start bluetooth:
root #
systemctl start bluetooth
Start bluetooth at boot:
root #
systemctl enable bluetooth
Enabling battery reporting
Using bluez's experimental mode may prevent some bluetooth microphones from connecting automatically.[1]
Bluez has a feature to report a devices battery level to upower. This feature is currently experimental and not stable. Enable experimental mode:
[General]
Experimental=true
Restart bluetooth to apply the configuration changes:
root #
rc-service bluetooth restart
Now upower should know the battery level of every device which supports sending its own battery level.
Usage
Controller setup
Display controller information:
hciconfig and other utilities are only available if net-wireless/bluez is installed with the
deprecated
USE flag enabled.root #
hciconfig -a
hci0: Type: BR/EDR Bus: USB BD Address: 00:02:72:2F:A9:33 ACL MTU: 1021:8 SCO MTU: 64:1 UP RUNNING PSCAN RX bytes:1166 acl:0 sco:0 events:43 errors:0 TX bytes:960 acl:0 sco:0 commands:43 errors:0 Features: 0xbf 0xfe 0xcf 0xfe 0xdb 0xff 0x7b 0x87 Packet type: DM1 DM3 DM5 DH1 DH3 DH5 HV1 HV2 HV3 Link policy: RSWITCH SNIFF Link mode: SLAVE ACCEPT Name: 'BlueZ 5.21' Class: 0x000104 Service Classes: Unspecified Device Class: Computer, Desktop workstation HCI Version: 4.0 (0x6) Revision: 0x1000 LMP Version: 4.0 (0x6) Subversion: 0x220e Manufacturer: Broadcom Corporation (15)
Where hci0
is the name of the controller, and UP
(3rd line) indicates that the controller is enabled.
Enable the controller if hciconfig indicates (with DOWN
) (3rd line) that the controller is disabled:
root #
hciconfig hci0 up
When attempting to enable the controller, the following message may be displayed: Can't init device hci0: Operation not possible due to RF-kill
In this case, query the state of the Bluetooth radio transmitter with rfkill:
root #
rfkill list bluetooth
0: hci0: Bluetooth Soft blocked: no Hard blocked: no
rfkill is provided by >=sys-apps/util-linux-2.31. It can also be installed by the unmaintained net-wireless/rfkill package.
If Bluetooth is blocked or disabled in the BIOS/UEFI, rfkill may incorrectly list the controller as
Hard blocked: no
.Unblock the controller if rfkill indicates (with Soft blocked: yes
) that the controller is blocked:
root #
rfkill unblock bluetooth
If rfkill indicates (with Hard blocked: yes
) that the controller is blocked, unblock the controller by physical switch or keyboard function key.
Bluetooth controllers can be enabled automatically by setting AutoEnable=true
in /etc/bluetooth/main.conf:
[Policy]
AutoEnable=true
In some instances Bluetooth controllers may have been soft-blocked by power management tools in udev. Make sure state is set to 1
in the corresponding rule file, or remove the following line entirely:
SUBSYSTEM=="rfkill", ATTR{type}=="bluetooth", ATTR{state}="1"
Device pairing
Bluetooth devices need to be paired with a Bluetooth controller before they can be used. This is done by entering a PIN (or other code) on both devices via an interaction agent. Certain devices such as headsets do not allow entering an arbitrary PIN. These devices use a static PIN, which is usually 0000, 1111, 1234 or 9999. There are also devices (e.g. Sony BD Remote Control) that do not require PIN entry, and attempting to enter a PIN when prompted will result in failure. Pairing can be skipped with such devices.
This article only covers device pairing with bluetoothctl, which is a command-line interaction agent provided by the net-wireless/bluez package. If a graphical desktop environment is being used, device paring can be done with a graphical interaction agent. For KDE use kde-plasma/bluedevil, for GNOME use net-wireless/gnome-bluetooth, and for GTK use net-wireless/blueman.
Previously paired devices will need to be paired again when upgrading from BlueZ 4.
Start bluetoothctl:
user $
bluetoothctl
List the available controllers:
[bluetooth]#
list
Display information about a controller:
[bluetooth]#
show controller_mac_address
Set the default controller:
[bluetooth]#
select controller_mac_address
Power on the controller:
[bluetooth]#
power on
Enable the agent and set it as default:
[bluetooth]#
agent on
[bluetooth]#
default-agent
Set the controller as discoverable (temporarily for 3 minutes) and pairable:
[bluetooth]#
discoverable on
[bluetooth]#
pairable on
Scan for devices:
[bluetooth]#
scan on
Put the device into pairing mode. This generally involves pressing a button or a combinations of buttons, usually for several seconds.
Discover the device MAC address:
[bluetooth]#
devices
Pair with the device:
[bluetooth]#
pair device_mac_address
Enter the PIN if prompted:
[agent]
PIN code: ####
In case the pin is not prompted but needed, this command may need to be added before pairing with the device (see this post):
[bluetooth]#
agent NoInputNoOutput
Allow the service authorization if requested:
[agent]
Authorize service service_uuid (yes/no): yes
Trust the device:
[bluetooth]#
trust device_mac_address
Connect to the device:
[bluetooth]#
connect device_mac_address
Display information about the device:
[bluetooth]#
info device_mac_address
The device is now paired:
[bluetooth]#
quit
hciconfig
- Open and initialize HCI device:
root #
hciconfig -a <hci0> up
- Close HCI device:
root #
hciconfig -a <hci0> down
- Reset HCI device:
root #
hciconfig -a <hci0> reset
- Reset statistic counters:
root #
hciconfig -a <hci0> rstat
- Enable Authentication:
root #
hciconfig -a <hci0> auth
- Disable Authentication:
root #
hciconfig -a <hci0> noauth
- Enable Encryption:
root #
hciconfig -a <hci0> encrypt
- Disable Encryption:
root #
hciconfig -a <hci0> noencrypt
- Enable Page and Inquiry scan:
root #
hciconfig -a <hci0> piscan
- Disable scan:
root #
hciconfig -a <hci0> noscan
- Enable Inquiry scan:
root #
hciconfig -a <hci0> iscan
- Enable Page scan:
root #
hciconfig -a <hci0> pscan
- Get/Set default packet type:
root #
hciconfig -a <hci0> ptype [type]
- Get/Set default link mode:
root #
hciconfig -a <hci0> lm [mode]
- Get/Set default link policy:
root #
hciconfig -a <hci0> lp [policy]
- Get/Set local name:
root #
hciconfig -a <hci0> name [name]
- Get/Set class of device:
root #
hciconfig -a <hci0> class [class]
- Get/Set voice setting:
root #
hciconfig -a <hci0> voice [voice]
- Get/Set inquiry access code:
root #
hciconfig -a <hci0> iac [iac]
- Get/Set inquiry transmit power level:
root #
hciconfig -a <hci0> nqtpl [level]
- Get/Set inquiry mode:
root #
hciconfig -a <hci0> inqmode [mode]
- Get/Set inquiry data:
root #
hciconfig -a <hci0> inqdata [data]
- Get/Set inquiry scan type:
root #
hciconfig -a <hci0> inqtype [type]
- Get/Set inquiry scan window and interval:
root #
hciconfig -a <hci0> inqparms [win:int]
- Get/Set page scan window and interval:
root #
hciconfig -a <hci0> pageparms [win:int]
- Get/Set page timeout:
root #
hciconfig -a <hci0> ageto [to]
- Get/Set AFH mode:
root #
hciconfig -a <hci0> afhmode [mode]
- Get/Set Simple Pairing Mode:
root #
hciconfig -a <hci0> sspmode [mode]
- Set ACL MTU and number of packets:
root #
hciconfig -a <hci0> clmtu <mtu:pkt>
- Set SCO MTU and number of packets:
root #
hciconfig -a <hci0> scomtu <mtu:pkt>
- Delete link key from the device:
root #
hciconfig -a <hci0> delkey <bdaddr>
- Get local OOB data:
root #
hciconfig -a <hci0> oobdata
- Display supported commands:
root #
hciconfig -a <hci0> commands
- Display device features:
root #
hciconfig -a <hci0> features
- Display version information:
root #
hciconfig -a <hci0> version
- Display revision information:
root #
hciconfig -a <hci0> revision
- Add a device to the blacklist:
root #
hciconfig -a <hci0> block <bdaddr>
- Remove a device from the blacklist:
root #
hciconfig -a <hci0> unblock <bdaddr>
- Set LE Random Address:
root #
hciconfig -a <hci0> lerandaddr <bdaddr>
- Enable LE advertising:
root #
hciconfig -a <hci0> leadv [type]
- Show all commands device has support for:
root #
hciconfig get commands
Disable Bluetooth
To disable Bluetooth at runtime, run the following command:
root #
rfkill block bluetooth
To disable Bluetooth automatically on every boot, choose one of the following options:
Using udev to disable Bluetooth
When using UDEV, just install the following rule which will disable Bluetooth:
SUBSYSTEM=="rfkill", ATTR{type}=="bluetooth", ATTR{state}="0"
Using OpenRC to disable Bluetooth
When using sys-apps/openrc, install the following script for local service and ensure it is executable:
#!/bin/sh
rfkill block bluetooth
root #
chmod o+x /etc/local.d/disable-bluetooth.start
Disable Bluetooth at kernel level
When the kernel has modular Bluetooth support, disable loading of Bluetooth modules:
blacklist bnep
blacklist bluetooth
blacklist btusb
Troubleshoot
TLP and laptop_mode
If laptop-mode-tools is installed or TLP make sure they're not disabling Bluetooth to save power.
XBOX ONE controller pairing
It's a known issue that XBOX ONE wireless controllers will refuse to pair out of the box on most linux systems. To solve this issue ERTM needs to be disabled.
To disable it manually:
root #
echo 'Y' > /sys/module/bluetooth/parameters/disable_ertm
This will disable ERTM only until the system is rebooted. To disable it permanently, install the xpadneo kernel module.
root #
emerge --ask games-util/xpadneo
In most cases, this will automatically solve the issue. If it doesn't, add this line into xpadneo config manually:
options bluetooth disable_ertm=Y
Notebook has a Synopsys DesignWare Controller
Bluetooth support for this controller needs also these options in kernel config[2]:
Device Drivers --->
Character devices --->
Serial drivers --->
[*] 8250/16550 and compatible serial support
[*] Support for Synopsys DesignWare 8250 quirks
Resolving firmware problems
It happens that the firmware of bluetooth adapters enters a state where it is unable to pair with a certain (or all) bluetooth devices. Resetting the adapter might solve such problems.
In the case of a laptop with a built-in bluetooth adapter this might be achieved by:
- Enter the laptop's firmware settings (BIOS) and disable the built-in adapter
- Save settings and restart the laptop
- Enter the firmware settings a second time and enable the bluetooth adapter again
- Save and restart
- Now try to pair the device again
See also
- Bluetooth headset — describes the configuration of Bluetooth headsets within Gentoo Linux.
- Bluetooth input devices — describes the setup of Bluetooth input devices, for example a bluetooth mouse, on a Linux system.
- Bluetooth Network Aggregation Point — covers the setup of a Bluetooth Network Aggregation Point (NAP) on Gentoo Linux.
- Broadcom Bluetooth — details setup for Broadcom Bluetooth 4.x devices mostly based on BCM20702, BCM4354, and BCM4356 chipsets.