Hacking my Logitech gamepad

Introduction

A while ago, I was browsing through my drawers, and guess what I found: a Logitech Dual Action gamepad I got for my birthday a long time ago. I never really used it, since the only game I got that supported it back then was Lego racers. And when I switched to Ubuntu I never even really bothered to get it to work with the games I played then. Imagine playing WoW with a Playstation-like controller. The only game that even reacted to the thing was Supertux (which is an awesome game by the way). Too bad that the analog controllers kept flooding data, causing Tux to walk nonstop. Even choosing an option in the menu without the mouse was more of a game itself, since the selected option ran from high to low, and I had to try four times before I actually got the "Start game" option. Calibrating it like the people in the Ubuntu support channel suggested didn't really help. Ever since then I didn't really look back at it. But when I saw it lying there and realized I had nothing else to do, I decided to do something cool: I wanted to sit back in my chair and watch a House episode, while being able to pause it with my gamepad!

The device

The gamepad I have has got 10 numbered buttons. Buttons one to four are on the right hand side each pointing in one direction, button one being on the east side and the numbers to up counterclockwise. Buttons five and seven are on the left "shoulder" side and six and eight are on the right one. Buttons nine and ten are in the middle and are rather small. On the left hand side is one big button that is used to indicate directions digitally. I will refer to these directions as though they are on a map, for instance, "up" would be north. There are to analog sticks on it too, but I didn't feel like taking the effort to decode those signals. The output is USB, presumably 1.0. But if you have another device and plan to do something similar

Capturing the signal

First, I had to find out which USB device in /dev/ I had to open in order to read the signals fired when buttons are pressed. I was shocked to find out there are a lot of ttyS* devices. Lucky for me, I quickly found it the device would not be serial. Lsusb and dmesg with some grepping told me that Ubuntu had read the device as a "Logitech, inc. Dual Action Gamepad", which was a good sign, because it meant that there actually had been some interaction. I had no luck trying to cat all the /dev/usbdev* devices, even with sudo the permission was blocked. Eventually, I found out the device was located at /dev/input/js0, which is actually rather logical. Catting it resulted in output when I pressed the buttons, confirming I had the right device.

Grabbing hold of the device

To decode the signal, I first used a PHP script with the class I found on phpclasses. I didn't get really lucky with that. As soon as the device only moved a bit, I was flooded with data, I assumed it came from the analog sticks. So I figured I had to use a more stable way of reading the device, and thus I resided to MonoDevelop. C# is one of my favourite programming languages, and in another article I will elaborate on why that is so. But for now, let's have a look at how I read the device. I used the built-in FileStream class and opened /dev/input/js0 as a regular file. Doing this meant I did not have to use the (at the moment buggy) .NET 2.0 compiler included in Mono which is rather buggy at the moment, but does include the SerialReader class. FileStream worked just as well for me, it had no trouble opening the device as a file and reading from it, so thumbs up to the guys over at Mono!

How to decode it

After some plumming with the device, I decided to put it in an infinite loop, and read one byte each iteration. I quickly discovered that on each button press, 8 bytes were sent by the device. So I coded it to read 8 bytes each iteration. I also converted these bytes to hexadecimal numbers and put colons inbetween. After a while I figured out that every byte had a certain format. I could not figure out the first, third and fourth byte, but the second seemd to be some kind of counter which counted from 0 to 255 how many times that button was pressed. Why this was included in the firmware is beyond me. Also, the fifth definately was 01 when the button was pressed down and 00 when it was released. The sixth bit also indicated something with the direction buttons. The seventh byte was to distinguish between whether it was a normal numbered button, one one under the direction pad, or a signal from the analog stick. Lastly, the eight bit told me what the number of the button it was, if it was a numbered button. So if I pressed button 1, the output looked like this:

For button 2, the last byte was 01 and so forth to button 10. When I pressed buttons on the direction pad, the seventh byte became 02, and I had to put the sixth byte to work. This is the output of a regular press on the East button:

Here, the last byte tells me the direction: 04 for horizontal, 05 for vertical. The fifth byte is FF for East and 01 for West. Same with 05 on the end: FF for North and 01 for South. I didn't research the analog sticks at all, because I wanted to keep the source simple and I couldn't think of anything I could put them to use with in combination with a video.

Let the code flow

So now it's time to show you the code! The complete source is available in this file (licensed under the CC-BY license). First take a look at the beginning, which libraries I include, or "use" to speak in .NET terms:

As you can see, I use the default System library in combination with System.IO for reading the file, System.Threading to prevent the GUI from crashing and Gtk to make a notification icon. I also included the C# bindings to libegg, found on the mono wiki. Just include this file in your project, MonoDevelop will take care of the rest. Now, to continue on with the main function:

I use Application.Init() and Application.Run(), which are rather obvious. The three lines inbetween though, I will explain. Here we create a fifo, or named pipe. This allows us to communicate with MPlayer through a configuration setting I will explain later. All you have to know now that we can write data to this fifo, and MPlayer will act on certain commands. By trying to remove it and then creating it again, we made sure that the fifo is actually there. Obviously, you can change your_pipe_name into anything, but don't forget to change it everywhere or the script won't function properly. The MenuIcon function creates a tray icon, with the stock button "Pause". Because when the program is launched, we aren't actually recording off the device yet. The user has to click it before we begin interpreting it's signals. Let us continue with the code that gets executed as soon as the tray icon is clicked.

So if the user clicks the icon with his left mouse button, I check whether we are already capturing. If we aren't, I destroy the current tray icon, create a new one (I couldn't find a way to just change the icon, any hints?) and open the input device as a regular file. Then I start a thread and tell acknowledge that we are capturing. On the other hand, if we are not capturing, I also destroy the tray icon and put a pause image there, I abort the thread which does the capturing and I close the USB port. This is very important, because it allows me to open it again should the user click the icon again. Lastly, I acknowledge that we stopped capturing. Now for the most important piece of code, the actual capturing

Now don't be scared of all that code, it actually is pretty simple. First, I use the for loop to read 8 bytes which I convert to a string which looks like the examples given earlier. Then I check whether it is a numbered button, and if so, I execute the action bound to that button by using the MplayerCommand function. I also check whether it is a press on one of the buttons on the direction pad, decode that signal, and execute the appropriate code. I also write the address to the console for debug purposes and I clean the address so it can be filled again in the next iteration.

Last things to take care of

Now for the last bit of C# code to be explained, the function MplayerCommand. This actually is really simple:

Now that function name may be a mouthful, but the only thing it does is launch process from the command line. And since I couldn't find a way to execute bash commands through this, I made a little script called "mpipe" and called it here. I also placed the script in /usr/bin and gave it the appropriate chmod. Here is the script code:

So there you have it, the strings I give MplayerCommand are written in the fifo via the bash script. Now only one thing we have to configure, and that is for MPlayer to read from the fifo that we create everytime. We can do this by simply editing the "config" file located in the .MPlayer map in your home directory. Most file managers hide the directories and files that begin with a "." but nautilus can make them visible if you press Ctrl+H. It is also no problem to edit it from the commandline, i.e. "vi .MPlayer/config in your favourite terminal.

Known issues

• On my Logitech Dual Action gamepad, it crashes as soon as I press (not move!) one of the analog sticks. Since I don't really press them that often, I didn't bother to fix this bug (It has an uncaught exception error)
• Sometimes my gamepad (and maybe other devices) starts flooding a lot of data. My program has no trouble decoding it when running, but for debug purposes, it might be a tad bit annoying
• It can only control MPlayer. It is my favourite video player and I don't really use any other. If you want to extend it, you are more than welcome

Licensing

The file is licensed under the CC-BY license which means you can edit and redistribute, even use it in commercial and closed source applications as much as you like, as long as you give me some kind of credit, like a link back to this page. If you like it or have any questions, be sure to mail me at tobias.kappe [shift-2] tiscali.nl and I'll be glad to answer your questions.

Epilogue

So there you have it folks, controlling MPlayer via a your gamepad. You could ofcourse use also use this to do other things, i.e. starting your favourite filemanager, but I found it most useful to prevent me from having to stand up and reach for my keyboard when I wanted to pause a movie. Furthermore, don't be shy to try this with another device, heck, if your toaster got a USB output, I'd say go for it! It's also a fun way to impress friends you want to convince to switch over to Linux.

Comments