Evinyatar edited this page Sep 13, 2010 · 7 revisions
Clone this wiki locally

What is atvclient?

atvclient is a background application for Linux that reads input from the AppleTV’s internal infra-red receiver and submits it to XBMC in a way very similar to how XBMCHelper does this under the native AppleTV OS. It implements most of the functionality the ATV OS HID driver supports, including pairing and control of the status LED.

Supported operations

Aside of the regular buttons (up, left, down, right, play/pause and menu), you can hold down menu or play/pause for about half a second to trigger their alternate function in XBMC (context menu, etc…). atvclient is compatible with the default AppleRemote keymap.xml so you do not need any additional configuration in XBMC. For more information about the default mapping, read this.
The following button ID’s are available:

  • 1 Up
  • 2 Down
  • 3 Left
  • 4 Right
  • 5 Play
  • 6 Menu
  • 7 Hold Play
  • 8 Hold Menu


atvclient supports pairing. When an AppleTV is paired to a remote that means the AppleTV will only respond to that particular remote control. To pair your AppleTV to your remote hold down the menu and right/fast forward buttons at the same time for about 6 seconds. You should receive a notification in XBMC confirming the pairing.
To unpair your AppleTV, hold down the menu and left buttons at the same time for about 6 seconds. You can do this using any remote, even one that has not been paired to your AppleTV.
Advanced users only: To increase the ID of your remote, hold down menu and play/pause for about 6 seconds. This will also pair your remote.
The remote ID is stored in /etc/atvremoteid.

Logitech Harmony and other programmable remotes

Logitech’s Harmony remote controls have the AppleTV in their database. In addition to the buttons on the original Apple remote, there’s a few extra buttons as well; Rewind, Forward, Play, Pause, Stop, Previous, Next, Page Up and Page Down. atvclient offers full support for these buttons and it should work out of the box. You may have to unpair your Apple remote though (there’s a button for that on the Harmony as well).
You can find the device profile for the AppleTV under “Media Center PC’s”, manufacturer “Apple”, device id “Apple TV”. This may also work with other programmable remotes, but I have only tested this with the Harmony.

In addition, atvclient supports multi-remote mode. To enable multi-remote mode, use the ‘-m’ flag, or put the following line in /etc/default/atvclient:

Then follow the instructions here to setup your remote.

Known issues

  • atvclient does not work after resume from hibernation. A reboot is needed to get the USB device to send IR commands.
  • universal remote is not working; I’m still looking for the magic word to send to get the IR controller to recognize other remotes.