Manage HID Bluetooth devices in Linux July 6, 2008

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:

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):

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:

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.

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:

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.

Like this:

Related

Wonderful Howto!
I had already discovered by accident that my BT Mighty Mouse had some basic functionality (but not the scrollball) in GNU/Linux without any configuration after pairing it once in Mac OS X… now I understand why that happened. Following your post to the letter, I now have a working scrollball as well.

quite good tutorial, worked for me on Gentoo.
BUT (:-P) in your patch, you should leave out the iso keyboard quirk (HID_QUIRK_APPLE_ISO_KEYBOARD) because my apple wireless keyboard is also device 0×022d but is a english ‘intl keyboard.

Hi,
this is a great howto for the last version of BlueZ.
I just upgraded to 4.42 on Debian and it uses input service and uses Bluez-hid2hci.rules to control switching from HID to HCI mode.
Everything seems to work for me but I’m still not clear on how hid2hci works. It has methods of dell, csr and logitech which seems to leave a lot of the world out!

[…] work immediately (or so it does according to around 5 tests). The commands were adopted from this blog marking. Suffice to say I still need an USB keyboard every time to start this script, but much less time […]

Woah this site is superb everyone loves reading your site content. Carry on the fantastic works of art! You recognize, lots of people tend to be hunting around due to this information, you could possibly assist them to drastically.

obviously like your web site but you have to test the spelling on several of your posts.
A number of them are rife with spelling problems and I in finding it very bothersome to tell the
reality on the other hand I’ll certainly come again again.

Appreciating the persistence you put into your website
and in depth information you offer. It’s nice to come across a
blog every once in a while that isn’t the same
old rehashed information. Wonderful read! I’ve bookmarked your site and I’m including your RSS
feeds to my Google account.

Good day! I could have sworn I’ve been to this site before but after going through
many of the posts I realized it’s new to me.
Regardless, I’m definitely pleased I stumbled upon it and I’ll be bookmarking it and checking back regularly!

Lessons dіscovered just like the a ѕingle іn thiѕ
pߋst are just inevitable. Im glɑd you chose to wrіte about this kind оf
topic it’s not truly that simple so fantastic job on challenging
yoսrself with this!

Hi, I do believe this is a great site. I stumbledupon it 😉 I’m
going to come back once again since I book-marked it. Money and freedom is the greatest way to
change, mayy you be rich and continue to help others.