Manage HID Bluetooth devices in Linux

This is a post dedicated to all of you guys who’d like to use Bluetooth HID (Human Interface Device), i.e. keyboard, mouse, etc. in Linux.

In my case the dongle is integrated in iMac (based on a Broadcom BCM2045B2 chipset) and the HID devices are the Apple Aluminium Bluetooth Keyboard and the Apple Mighty mouse, but the concepts here are still valid for other devices.

It takes me a while to have a clear picture of the concepts here, so I wish this guide will make a smooth path for you 😉

Bluetooth

Bluetooth is a wireless protocol suited for low power consumption and data transmissions over short distances from fixed and/or mobile devices.

In Bluetooth a master device (the host) can communicate with up to seven active devices in an ad-hoc piconet. Up to 255 further devices can be inactive, or parked, which the master device can bring into active status at any time.

The Bluetooth technology offers a seamless integration of different peripheral and functionality overcoming issues arising from synchronization of these devices.
This is achieved by means of profiles: they provide standards which manufacturers follow to allow devices to use Bluetooth in the intended manner.

At a minimum, each profile specification contains information on the following topics:

• Dependencies on other profiles
• Suggested user interface formats
• Specific parts of the Bluetooth protocol stack used by the profile.

Bluetooth protocol stack

In Linux the Bluetooth support is provided by BlueZ.

The HID Profile

The HID (Human Interface Device) profile provides support for devices such as keyboards, mice, joysticks, as well as support for simple buttons and indicators on other types of devices. It is designed to provide a low latency link, with low power requirements.

Bluetooth HID is a lightweight wrapper of the HID protocol defined for USB which simplifies host implementation by enabling the re-use of some of the existing support for USB HID to also support Bluetooth HID.

Apple, but I have seen a similar approach also in other vendors (like Logitech with their diNovo product family), abstract the Bluetooth HID devices as USB HID (HID mode). This means that the Bluetooth device appear to the system as if it were directly connected to the USB port.

That’s the reason why we can use the Apple Bluetooth keyboard and mouse in Linux even we have not installed the Bluetooth stack at all.

That’s a cool approach (consider for example BT keyboard usage in BIOS) but it has some limits: in this mode

• the Bluetooth controller does not act as a standard BT host so other devices (mobiles, printers, etc) cannot be added;
• the HID device hardware is not accessed directly and as a such you are limited to the (basic) function that the manufacturer decided to export to this emulation layer.

In my case, for example, the mighty mouse act as a basic 3 button mouse with no awareness of the really useful wheel on top of it which would allows horizontal scrolling 😛

Blue or Red Pill?

For people who just want to use keyboard/mouse without any fancy feature and do not plan to use Bluetooth with other devices (like smartphone) just use the USB HID emulation and you are set.

You are not neither required to install the Bluetooth stack nor did anything else than pair the keyboard and mouse in MacOS. You device will appear to Linux as they were connected directly to a USB port.

[…] and the story ends.

Since we are f**ckin’ curious guys 😀 we would like to have all the possibilities enabled even if we are not ever making use of them.

The procedure here is to set HID emulation to use at boot time (BIOS, rEFIt, others) and then switch to native BT (HCI mode) when Linux loads up, managing HID peripherals with the Bluetooth modules.

Let’s Rock’n’Roll

Bluez installation

First of all let’s install the Linux’s Bluetooth stack. In Debian this is as easy as type 😉

$ sudo apt-get install bluetooth bluez-utils bluez-gnome

The bluez-gnome package contains a passkey agent (which in bluez 3.x replaced the legacy pin-assistant component) which is required to perform associations with the BT devices.

HID to HCI

We can now start scanning the Bluetooth spectrum to see available devices (if any). At a first glance, I received an error:

$ hcitool scan
Scanning ...
Inquiry failed: Connection timed out

This is because the device is still in HID mode: this can be easily verified with an lsusb (note the 820a and 820b entries):

$ sudo lsusb -t
[...]
Bus# 1
`-Dev# 1 Vendor 0x1d6b Product 0x0001
`-Dev# 4 Vendor 0x0a5c Product 0x4500
|-Dev# 5 Vendor 0x05ac Product 0x820f
|-Dev# 6 Vendor 0x05ac Product 0x820a
`-Dev# 7 Vendor 0x05ac Product 0x820b


where the 0x820f is the Bluetooth adapter, the 0x820a is the HID keyboard and the 0x820b is the HID mouse (simply execute sudo lsusb -v).

In the new iMac, host switch to HCI mode can be done with a dongle reset. In other cases (as in the old iMac which had CSR chipset) there is a utility hid2hci which accomplish this.

Note: after the reset you are going to loose you BT keyboard and mouse since we didn’t pair them yet. So you would better find a USB keyboard and mouse to use by that time 😉

$ sudo hciconfig hci0 reset

To make this behavior permanent you can either add an option to one of the /etc/modprobe.d file or patch the kernel by adding the Apple BT ID code in the hci_usb.c file.
Marcel Holtmann (the bluez designer which help me setting-up my device) is taking care of the patching process which is hopefully online soon. In the meantime I inserted an option in my /etc/modprobe.d/local file with a line:

options hci reset=1

If we repeat the commands above we noticed that there are no HID devices in the lsusb output and, if the devices are in discovery state, we now able to find them with an hci scan:

$ sudo lsusb -t
[...]
Bus# 1
`-Dev# 1 Vendor 0x1d6b Product 0x0001
`-Dev# 4 Vendor 0x0a5c Product 0x4500
`-Dev# 5 Vendor 0x05ac Product 0x820f
$ hcitool scan
Scanning ...
00:XX:XX:XX:XX:99 alessandro's keyboard
00:XX:XX:XX:XX:2D alessandro's mouse


HID daemon

Since we are now in native BT mode, we need some software to manage HID devices: the HID daemon (hidd).

To start hidd in Debian we simply modify the /etc/default/bluetooth file changing:

• HIDD_ENABLED=0 to HIDD_ENABLED=1
• HID2HCI_ENABLED=1 to HID2HCI_ENABLED=0, since I don’t use hid2hci

Restart Bluetooth:

$ sudo invoke-rc.d bluetooth restart

Adding the Keyboard and Mouse

You now need to pair the devices with the computer; remember to unpair them first in MacOS before proceed with the following pairing process.

Let’s start from the keyboard: put it in discovery mode (hold down the power key until the small led start to flash) and then type:

$ sudo hidd --connect 00:XX:XX:XX:XX:99

This is the tricky part: as soon you start the hidd command above, on the BT keyboard, enter a pass-code (from 4 to 8 numbers) and finally press Enter to confirm.

You should be notified by GNOME that you need to enter the same pass-phrase in a pop-up window (now with the USB keyboard). If you did it right you should have your keyboard paired and connected now (I need some trials before get everything works).

Let’s repeat those steps for the mouse: close and open the led shutter to put it in discovery mode and when prompted enter the pin 0000:

$ sudo hidd --connect 00:XX:XX:XX:XX:2D

The devices can be trusted in the GNOME Bluetooth Manager: right-click on the Bluetooth icon in the GNOME systray and select ‘Preferences’: in the ‘Bonded Devices’ area select the two devices and click on ‘Set Trusted’.

GNOME Bluetooth Preferences

You should be set!
The devices will automatically reconnect when they go to sleep and when your computer boots up.

Apple devices support

We can now see the two devices connected with hidd managing them:

$ hcitool con
Connections:
< ACL 00:XX:XX:XX:XX:2D handle 13 state 1 lm MASTER
< ACL 00:XX:XX:XX:XX:99 handle 12 state 1 lm MASTER
$ sudo hidd --show
00:XX:XX:XX:XX:2D Apple Computer, Inc. Mighty Mouse [05ac:030c] connected
00:XX:XX:XX:XX:99 Apple Inc. Keyboard [05ac:022d] connected

Those devices are exposed to higher (software) layers as HID devices, both produced by Apple (0x05ac), where one is identified by product ID 0x030c (Apple mighty mouse) and the other one by 0x022d (Apple Wireless keyboard).

In order to correctly handle these devices, the hidp kernel module, which is in charge hid protocol, needs to be aware of some “quirks” the devices use.

The might mouse is supported since 2.6.25 and I wish the BT Aluminium keyboard support will be introduced soon (hopefully in 2.6.26 with the ongoing rework for the Apple devices in hid_apple.c).
In the meantime this is the patch for the BT Aluminium keyboard support:

--- linux-2.6.25/net/bluetooth/hidp/core.c 2008-04-17 03:49:44.000000000 +0100
+++ /usr/local/src/linux-2.6.25/net/bluetooth/hidp/core.c 2008-05-25 13:26:32.000000000 +0100
@@ -678,6 +678,8 @@
} hidp_blacklist[] = {
/* Apple wireless Mighty Mouse */
{ 0x05ac, 0x030c, HID_QUIRK_MIGHTYMOUSE | HID_QUIRK_INVERT_HWHEEL },
+ /* Apple Bluetooth alu ISO keyboard */
+ { 0x05ac, 0x022d, HID_QUIRK_APPLE_HAS_FN | HID_QUIRK_APPLE_ISO_KEYBOARD },

{ } /* Terminating entry */
};

Hi-level device management

I will address the “high-level” device management (console keymap and Xorg) in the near future with a dedicated post.

Open issues

Contrary to what happen in Mac OS, Linux is not able to switch back my device to HID mode and the only way I found to have HID mode at the next system restart is to explicitly shut-down the system (not using a restart): not a big deal …

TODO

The use of the hidd is now deprecated in favour of the new Input Service. As soon as Debian will switch to this I will have to reconfigure my devices.

References

1. Using the Apple Aluminium Bluetooth Keyboard with Linux
2. Using the Logitech diNovo Media Desktop in Linux
3. Fun with Logitech MX900 Bluetooth receivers