Developer crafts Linux support for Logitech Harmony remote controls

Logitech’s Harmony series of programmable universal remote controls ship with Windows and Mac OS X configuration programs. That wasn’t enough for Phil Dibowitz, though — he set out to build his own Linux support.

Remotes from the Harmony line feature fully programmable buttons, an infrared (IR) receiver that can learn commands from other remotes, LCD screens (some in color) with reprogrammable labels, and user-defined macros with which you can script multiple-command sequences involving multiple devices. All of these advanced features are configured through a GUI application that accesses Logitech’s remote database of home theater devices and uploads your settings to the remote over a USB cable.

Harmony on Linux: Pass the word

Dibowitz bought a Harmony 880 remote last year after upgrading his home theater system, but eventually got annoyed at having to switch over to his Mac every time he needed to adjust the remote’s configuration. Already familiar enough with the kernel USB subsystem to make contributions, he had been on the lookout for a more ambitious hacking project for a while. Writing a Linux driver for the remote fit both needs perfectly.

He started with USB dumps captured on a Windows machine. Initial progress was slow, so he wrote to Logitech for help. “My first ticket to support miraculously got forwarded to a developer, but not on the Harmony team. He spent about a month trying to get someone from the Harmony team to contact me, then gave up. I sent another ticket, and got a “we don’t support Linux” response. I replied and explained I wasn’t asking for Linux support, I was doing the Linux support *for* them … but they said they couldn’t release the information I wanted.”

Out of frustration, he blogged about the experience, a decision that, through a chain of connections, eventually enabled him to link up with someone who could provide answers. Dibowitz’s initial post drew tremendous traffic, and the feedback included several email messages directing him toward others who had tackled the same task. One was to a cash bounty publicly offered by Banshee developer Aaron Bockover. Dibowitz wasn’t interested in the money, but one of the donors — Paul Cutler — put him in touch with Kevin Timmerman.

Timmerman had already reverse-engineered much of the Harmony remote’s communications in the process of planning to build a proprietary application for custom programming. He offered Dibowitz his code for communicating with the remotes. Together they whipped it into shape, and with Timmerman coding on Windows and Dibowitz on Debian, it was cross-platform, too.

Installation and use

From the project’s Web site you can download the GPLv3 code in source form. The latest release is 0.11, and it supports all Harmony models up through the 880/885.

According to Dibowitz, the two presently unsupported models — 890/895 and 1000 — use TCP-over-USB for communication, rather than USB HID like the rest of the product line. Support will come eventually, he says, but it is not stable yet.

The only major prerequisite is libusb, which is a standard part of most modern distributions. Compilation requires a simple make and make install, which will build and install a single executable to /usr/bin/harmony.

The trade-off for such simple compilation and installation is that it requires an extra step or two to run. First, reading and writing data to the remote requires raw I/O access, so you need run harmony as root.

Also, there is a slim chance that when you plug your Harmony remote into a USB port, another USB driver will erroneously grab it and bind to it. The harmony program will do its best to regain control, but if it cannot, you may have to unbind the offending driver from the command line. The harmony documentation recommends the procedure described by Greg Kroah-Hartman at LWN.net.

You can run harmony -h for a detailed list of options. Right now, harmony can read a stored configuration off of the remote (the -c switch), write a configuration to the remote (the -C switch), read the time (-k) or write the time (-K), power-cycle the remote (-r), learn an IR command from another remote (-l), or copy the firmware off of the remote (-f).

If you have used the Mac or Windows configuration programs from Logitech recently, the above description may not sound like much. Logitech’s config programs are GUI-based with lots of forms for identifying your home theater components, labeling buttons on the remotes’ LCD screens, and setting up macros. But the big secret is that all the fancy GUI is doing is connecting to the Logitech Web site. You can step through the exact same procedures to set up your remote by visiting members.harmonyremote.com. Using the Web forms on that site, you set up your remote’s configuration, then download the result in an .EZHex file. Then you write it to the remote with the command-line harmony tool. The same username and password combo used for the Logitech GUI configurator works to accessing the Web site.

If you are wary of accidentally bricking your remote by using harmony, one simple way to alleviate your fears is to log in to members.harmonyremote.com, download the stored .EZHex file for your remote, and then compare it to the config you can extract by running harmony -c.

Harmonious future

Dibowitz admits a Linux GUI would be nice. “At the very least, there needs to be a very minimal GUI that can get associated with the EZhex file extension and called by your browser and show a little progress bar for users who don’t live in terminal windows like me.” He is currently working on refactoring the code to break it into a libharmony shared library and a separate command-line tool. That will allow a wide range of front-end interfaces, from a standalone GUI tool to integration with other media-centric apps.

Future releases might not require running as root, either. It is required now because libusb (and thus harmony) require the RAWIO capability. But Dibowitz notes, “There was a new feature added to the kernel in 2.6.23 that allows you to assign capabilities to files, so once that becomes common, you can just give the binary CAP_RAWIO and then the root requirement goes away.”

In the nearer term, though, he hopes to stabilize TCP-over-USB so he can enable 890 and 1000 support. Anyone interested in hacking on the code, he says, is welcome to join. “In the meantime, I’m still trying to get specs out of Logitech….”