Bluetooth keyboard

This article describes how to set up a
Bluetooth
HID keyboard with Arch Linux,
bluez
version 5.
Pairing process
This article or section is a candidate for merging with
Bluetooth
.
Notes:
Pairing process, and some troubleshooting related to it, are redundant with general device setup on Bluetooth page, and should be merged there. Keyboard-specific info would stay on this page. (Discuss in
Talk:Bluetooth#Merging general setup from Keyboard, Mouse, Headset pages
)
Login to the affected computer by a wired keyboard or by ssh.
First, make sure the local Bluetooth controller (e.g. a Bluetooth dongle the built in Bluetooth radio) is recognized:
# lsusb
Bus 001 Device 004: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter
Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp. LAN9500 Ethernet 10/100 Adapter / SMSC9512/9514 Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
The above output is from a Raspberry-Pi revision 'B' with archlinux-arm and a Keysonic Bluetooth Dongle.
Three items worth remembering:
Bluetooth devices (keyboard) and controllers (dongle) need to be paired once.
The Bluetooth controller needs to be powered up after every boot.
The Bluetooth controller needs to be told to connect to the keyboard after every boot.
Pairing
is a one time process, required only once. There are Bluetooth keyboards sold with a Bluetooth dongle which come already paired, but that is not certain.  We will use the
bluetoothctl
command from
bluez-utils
to pair our dongle and the keyboard.
Power up
can be done with
bluetoothctl
, or automatically in
/etc/bluetooth/main.conf
, see below.
Same for
connecting
, either
bluetoothctl
or
hcitool
can be used, the latter is more useful for scripting.
We will use
bluetoothctl
for the pairing process. Run the command to get at the
[bluetooth]#
prompt.
# bluetoothctl
[bluetooth]#
Note
If you are on a color console: the word "bluetooth" is in the default color as long as no devices are available, and blue as soon as required devices and/or controllers have been found.
While in
bluetoothctl
power up the controller:
[bluetooth]# power on
Changing power on succeeded
[CHG] Controller 06:05:04:03:02:01 Powered: yes
Next, tell
bluetoothctl
to look only for keyboards, and make that the default agent:
[bluetooth]# agent KeyboardOnly
Agent registered
[bluetooth]# default-agent
Default agent request successful
Next, put your controller (the local dongle) in
pairable
mode:
[bluetooth]# pairable on
Changing pairable on succeeded
Next, put your keyboard in an active mode, where it is
discoverable
, i.e. pairable. Some keyboards have a special button for this on the underside, or require a special key combination to be pressed. See the documentation of your keyboard. Please note that this
discoverability
of a device is time limited; some devices are only visible for 30 seconds, other for 2 minutes. Your mileage may vary.
Next, let the controller scan the Bluetooth frequencies for a suitable device:
[bluetooth]# scan on
Discovery started
[CHG] Controller 06:05:04:03:02:01 Discovering: yes
After a few seconds the address of the keyboard should be listed as found. This line will repeat over and over, but will not stop you from entering new commands.
Next, actually do the pairing. The address used is the Bluetooth MAC address of the keyboard:
[bluetooth]# pair 01:02:03:04:05:06
Pairing successful
Note
Some keyboards, such as Microsoft Surface Ergonomic, will send a pass code (e.g.
[agent] Passkey: 501334
) which has to be typed in on the Bluetooth keyboard followed by the key
Enter
in order to pair successfully. Use
paired-devices
command to double check if the pairing succeeded.
Next, make this a trusted device (this allows the device to establish the connection on itself). Again, the Bluetooth MAC address is the address of the keyboard device:
[bluetooth]# trust 01:02:03:04:05:06
Trusted
Next and finally connect to the device (keyboard). Again, the Bluetooth MAC address is the address of the keyboard device:
[bluetooth]# connect 01:02:03:04:05:06
Connection successful
Done. Leave the
bluetoothctl
utility:
[bluetooth]# quit
Now the external device (i.e. keyboard) and the USB Bluetooth dongle are paired permanently, unless you break the pairing intentionally.
Troubleshooting
Bluetooth controller does not show up in lsusb
Manually load the generic Bluetooth driver:
# modprobe btusb
For integrated Bluetooth controller, some are not internally wired through USB, and only appear using
lspci
.
Bluetooth controller is not visible in bluetoothctl
Check the
unit status
of
bluetooth.service
.
If the
[bluetooth]#
prompt is blue and you get
No default controller available
message when powering on the controller with
power on
, run
bluetoothctl
as root
.
Bluetooth keyboard does not work
Start with basic troubleshooting steps : does the device have power; if so, did it connect to the Bluetooth controller? If not, try with another controller or your smartphone to confirm where the issue lies.
Error: hci0 ACL packet for unknown connection handle 4
Try a reset with
hciconfig hci0 reset
Alt and Super are swapped
Some keyboards have separate macOS and Windows mode. When the keyboard is connected or when modes change, the Apple mode may activate. Remove the
hid_apple
kernel module
and re-connect the keyboard:
# rmmod hid_apple
If this works,
blacklist
the module to have a permanent solution.
Xorg
Device should be added as
/dev/input/event*
and your Xorg should add it automatically if you did not disable such feature.