Howto: Bluetooth Keyboard (5.01)

Finally got my Apple Bluetooth Keyboard working under 5.01! Here are the steps, you have to install and pair it using SSH (Google “how to SSH into an apple tv 2” if you don’t know how) as the GUI hasn’t been updated to work with 5.x. This only has to be done once unless you unpair your keyboard.

  1. SSH into your AppleTV.

  2. Run these three commands one after another:

apt-get install ch.ringwald.keyboard-atv
apt-get install org.tomcool.btstack-ui
killall AppleTV

Your AppleTV will reset.

  1. SSH into your AppleTV, ensure your keyboard is discoverable (on an Apple keyboard you hold the button on the right end until the light starts to blink)

  2. Enter the command:


  1. It will list all devices it can find, you want the one labeled Keyboard.

  2. Enter the command:

keyboard-config address

  1. Type 0000 on your keyboard.

  2. Enjoy your keyboard goodness!

Here’s a screenshot to show what should happen. The first time I ran it I didn’t have my keyboard in discovery mode so it didn’t show up. The second time I ran keyboard config I did and it showed up as Keyboard.


If nothing happens when you type 0000 on your keyboard, press CTRL+C and try again. Make sure the keyboard is still in discovery mode when you type 0000.

Have fun!

Thanks - worked perfect on ATV2 with the latest JB

Thanks for this info. Do you think these instructions will work on any bluetooth keyboard? I’m thinking of getting a non-Apple keyboard that is bluetooth 3.0.


I’m attempting this via CyberDuck on the Mac.  The connection seems to be working fine as I can browse the file structure and upload XBMC Add-ons.  I tried the command in Cyberduck via: Go > Send Command.  The program just hung/crashed after submitting the first string.  How long should each command take to execute?  Should I be SSH’ed into the root folder or should I be in a specific sub folder?  


You should use “Terminal”. The Program is already on your Mac.

Open Terminal

Type: ssh root@192.168.1.x (or what ever IP your ATV has)

Password is alpine (default - you can change it later by typing “passwd” if you like)

You are now logged in and can use the above description.



will this work with any bluetooth keyboard?

It should, yes. I’ve only tried it with an Apple Keyboard, but it should work with most.

is it bluetooth 2.0 or 3.0? or both?

I have tested with 3 different BT keyboards all work correctly.

Thank you for your information. They worked perfect on me.

I believe the AppleTV is 2.0, for what it’s worth Wikipedia says 3.0 devices are backwards compatible with 2. Will 3.0 devices work? I can’t say for sure, but if you try it and it does please reply and let everyone know!

Got linked nicely to my Targus mini keyboard: [[wysiwyg_imageupload:226:]]



This is awesome but appears to have some issues with URLs entered into Couch Surfer.  Seems to be entered lots of unnecessary “%00” strings which means it can’t connect to intended sites.


Works great in ATV’s standard “search fields” though!


Thanks for the info, Jonez. I did all as described with a generic bluetooth keyboard. I got all of the prompts you show up to the pairing instructions. It found my keyboard address, but pressing 0000 did not produce the final confirmation response you showed. I did the control c and repeat with no success. I repowered the keyboard tried again–re-doing the discovery mode on the keyboard, but nothing. Any thoughts?



Never mind–got it. I guess I was not hitting enter after doing 0000. Finally took once it dawned on me to hit enter!


Whoo hoo!




it is possible to switch to german keyboard layout?




Hi again,

My generic BT keyboard is the only one I’ve ever used, so maybe it is an issue with it’s “generic” quality. My question is this–do BT keyboards go to sleep after a few minutes and then need to be paired again with the device? I’ve got my keyboard to work with the ATV, but the pairing drops after leaving either the TV or keyboard for a while, and then I have to SSH back in to do the pairing.

Any thoughts?


I’m stuck on the last command of the set up of my Apple bluetooth keyboard. Everything shows up as planned in Putty. It shows me the findings of the keyboard addresses.

Then on the how to it says enter the command

keyboard-config address

 which I pasted and hit enter. I get nothing, no set of numbers as in the screen capture shows. The keyboard is blinking

 I don’t get the pairing:

My Apple keyboard doesn’t do that, I leave my keyboard in a basket under my coffee table and only use it once or twice a week and I’ve never had to repair it. It could be an issue with the keyboard, or it could just be that the guy who wrote the Bluetooth Stack mainly tested with Apple keyboards, I can’t say for sure.

You can't paste that exact line, the "address" is what shows up in the list of devices next to keyboard. In my screenshot this is what I typed;

keyboard-config e8:06:88:4b:87:47

You need to do the same but with the address it displays to you (the middle block of text in the screenshot).

I think that it is an issue with generic, older (unfortunately, crappy) Bluetooth keyboards.  (I’ve seen similar happen before, with other iOS devices – iPhones and my own AppleTV.)  These crappy ones need to be re-paired often.  More expensive, newer, known-name-brand ones do not.  It’s annoying enough to be a dealbreaker for those crappy keyboards…

Thanks Jonez and Fofar! That info helps. I’m going to roll the dice on one more cheap BT keyboard for 10 bucks (a mini). Other than for XBMC searches I have no use for an expensive Apple keyboard (even though it would be a nice extravagance.) If this next mini BT keyboard doesn’t work, I’ll accept the annoying click-fest of searching with the remote and on-screen board.

Cheers all.