jump to navigation

Manage HID Bluetooth devices in Linux July 6, 2008

Posted by idebian in Debian, GNU/Linux, Hardware.
Tags: , , ,
trackback

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
Advertisements

Comments»

1. Henk Koster - September 3, 2008

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.

I added the connect option to /etc/default/bluetooth,

HIDD_ENABLED=1
HIDD_OPTIONS=”–connect 00:1F:F3:DC:E5:93 –master –server”

so now my mouse 00:1F:F3:DC:E5:93 starts automatically when rebooting (I just have to give the mouse a little squeeze) once the gdm login page appears).

Thanks a lot.

2. Henk Koster - September 4, 2008

Just a few small corrections, probably related to my Debian Lenny OS:

1. The reset=1 option must be given to the kernel module “hci_usb” (and not “hci” as stated in the text).

2. Restarting Bluetooth after the initial configuring is done with

sudo /etc/init.d/bluetooth restart

3. zimon - October 9, 2008

How to make sure the Bluetooth encryption is enabled on the link with a BT keyboard always when it is (auto) connected?

After the pairing I had to manually do:
# hcitool auth
and
# hcitool enc
…to get the link encrypted.
# hcitool con
Connections:
< ACL 00:19:XX:XX:XX:XX handle 42 state 1 lm MASTER AUTH ENCRYPT

4. Michael - November 2, 2008

Hi I’ve tried this a few times now.

My mouse will do everything bar actually click on anything (scroll bar works)

My keyboard connects and apart from the features like volume control, it all works.

For some reason I can’t seem to use them after I restart my computer.

Hopefully someone could help me figure out how to first of all get the mouse to work properly and also ensure they stay connected when I restart my computer.

5. Nss - December 10, 2008

Hi, can i traslate that page and put it in my LUG wiki http://www.tulug.it/ ?? i’ll mention your site in the traslation.

Thanks Luca

6. bienchen - February 27, 2009

Hi,

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.

greetings,

bienchen

7. mike - August 5, 2009

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!

8. sabee - January 15, 2010

hi
in my case this is the result for “lsusb -t”
Bus# 5
`-Dev# 1 Vendor 0x1d6b Product 0x0001
Bus# 4
`-Dev# 1 Vendor 0x1d6b Product 0x0001
Bus# 3
`-Dev# 1 Vendor 0x1d6b Product 0x0001
Bus# 2
`-Dev# 1 Vendor 0x1d6b Product 0x0001
Bus# 1
`-Dev# 1 Vendor 0x1d6b Product 0x0002

my hcitool scan gives output no devices found Please any one help past 2 days i tried with this … thanks in advance…

9. Getting Apple bluetooth keyboard to work in Power PC Linux « Diverse things - October 31, 2010

[…] 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 […]

10. Setup Apple Wireless Keyboard via Bluetooth on Fedora 17 - VirtuallyHyper - September 18, 2012

[…] If you want more information on how Bluetooth interacts with HID, I would recommend reading “Manage HID Bluetooth devices in Linux” […]

11. pairing bluetooth keyboard is becoming a problem - October 9, 2012

[…] it's Bluez you want,… look here; https://idebian.wordpress.com/2008/07…ices-in-linux/ It probably wasn't set up with HID support out of […]

12. Lorenzo - January 10, 2013

BCM92045B3 this is my dongle usb http://pastebin.com/8mHdWxt4
i try as root “hciconfig hci0 reset=1” to return on HID mode but didn’t switch.

i need help… 😦

13. Cane Corsos - April 22, 2013

My brother recommended I might like this web site.
He was totally right. This post truly made my day.
You can not imagine simply how much time I
had spent for this information! Thanks!

14. abrir cuenta facebook - May 9, 2013

Greetings! Very useful advice in this particular post! It is the little changes that make the greatest changes.

Thanks a lot for sharing!

15. bluetooth for car radio - October 30, 2013

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.

16. Lowest Price - August 9, 2014

My partner and I stumbled over here by a different page and thought I might as well check things out.

I like what I see so now i am following
you. Look forward to looking over your web page for a second time.

17. new games book pdf - August 10, 2014

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.

18. Click Here! - August 15, 2014

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.

19. télécahrger Minecraft gratuit - August 17, 2014

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!

20. Edythe - August 21, 2014

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!

21. saludos de cumpleaños originales - August 21, 2014

Hi, its pleasant paragraph regarding media print, we all bee famniliar with media is
a great source oof data.

22. http://Sns.zgjieya.com - August 22, 2014

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.

23. Arianne - August 22, 2014

Everything is very open with a precise clarification of the challenges.
It was really informative. Your website is very helpful.
Thanks for sharing!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: