Daniel Ford

My latest project is figuring out the interface between a game pad and the Eclipse Debugger.

In a previous blog entry, I described how I used a “Nostromo^TM SpeedPad n52″ key pad accelerator designed for “first person shooter” games, to create a dedicated Eclipse “debugging key pad”. This worked well, making it easy to launch debug sessions, step through code, toggle breakpoints and perform other tasks by pushing keys dedicated to specific debugger commands.

Of course, nothing is perfect. When I first started using the pad I figured I would never use the mouse or function keys again, but after many months of use, that didn’t turn out to be true. I found myself defaulting to using the mouse for quick debugging sessions and only later when things got involved did I remember that I had a dedicated key pad that made things a bit easier. Surprised by this, I started observing my behavior as I interacted with the debugger and made note of when I used the key pad and when I didn’t.

I concluded that the simple answer was that using the mouse was the path of least resistance since my hand was usually already on it when I wanted to start debugging. My hand also tended to stay on it because I was focused on the code and the program behavior rather than optimizing my interface device selection. That wasn’t the full story, however.

There are aspects of the key pad that act as impediments to using it. The first is that it isn’t used very frequently, but it still takes up a chunk of desk space. As a result it tends to migrate out of “home” position to someplace behind the keyboard, typically towards the back of the desk where it gets in papers or other clutter. The second is that getting the key pad back into position to use it is a chore. It is a bit heavy and “clunky” and there are usually other things on the desk that need to be moved out of the way to make space. The key pad also isn’t wireless, so it has a USB cable that needs to be dragged along without snagging on anything. Not being wireless is actually a more fundamental defect of the key pad as it restricts it from being placed in a more accessible and stable place where it won’t migrate and can be easily retrieved. These drawbacks often combine to make using the key pad just a little more work than using the mouse, particularly for short debugging sessions.

Having explored key pads and always keen to try something new, I started wondering about using a game pad to control the debugger; if a key pad is useful, maybe something with joysticks and buttons for two hands will be better. Starting off, I come to the project extremely handicapped as I am one of the few people on this planet who never plays video games. So, until now, I have had little familiarity with game pads as an interface device, either using them, or interfacing to them.

My first task was to purchase one and see how they worked. While browsing through my favorite store, Frys, I tripped over the Saitek P2900 Wireless Pad. It had all the characteristics I wanted: cheap ($29.95), wireless and, of course, lots of buttons.

If you’re not familiar with a game pad, the device looks like a small bird with round swept back wings. It is designed to be gripped with two hands such that the “wings” rest in the palms with the thumbs above the top surface and the index fingers curved around the front. The other fingers grip the wings from underneath. Typically, there are a set of buttons and a joy stick within easy reach of each thumb and two buttons, placed one above the other, for each index finger to press.

The Saiteck P2900 comes with seven buttons for the right thumb and a joy stick, and a “Point of View” (POV) button and joy stick for the left thumb. Each index finger has two buttons, with the lower one being slightly larger than the one above it. My index fingers naturally rested on the lower buttons.

Installing the P2900 was easy, it comes with a receiver that plugs into a USB port and there are some downloadable drivers and some configuration software you can get off of the Saitek site.

The configuration software consists of two useful programs, a “Control Panel” and a “Profile Editor”. The Control Panel gives instant visual feedback on game pad button presses and movements of the joysticks. It makes it easy to identify the buttons and verify the functionality of the device. The Profile Editor allows you to map controls on the game pad to keyboard and mouse events. For instance, allowing you to create a “macro” of key presses from a single button. With no surprise, this is very much like the profile editor for the key pad.

The next step after getting the game pad installed was to figure out the mapping between its controls and the commands that control the debugger. This was easier than it sounds. From my experience using the key pad, I knew that assigning a command to every possible button press combination available on the interface device was not that useful. Basically, the problem is that you forget what you assigned to what. Simpler is better.

From the assignments I made to the key pad, I knew that stepping in, out, and over code were by far the most useful key assignments, with “Resume” (execution) and “Launch Last Debugged” being close seconds. The command “Toggle Breakpoint” was the surprise contender for third place as I didn’t realize how often I performed that operation.

The game pad however, is a bit different from the key pad and offers some additional options. The obvious differences are the POV switch on the left and the two joy sticks. I experimented with assigning the step commands to the POV switch such that pressing in the “down” direction (the bottom switch) would “Step Into” a method while pressing “up” would “Step to Return”. Pressing “right” would “Step Over” and pressing “left” would “Step Into Selection”. I also assigned the same commands to the buttons for the left and right index fingers. I didn’t stick with this assignment for the POV switch very long as I found I just used the index finger buttons and concluded that the POV switch would be much better used as a navigation control. I simply assigned the up and down arrows to the “up” and “down” POV keys and “Next Member” and “Previous Member” commands to the “left” and “right” POV switches. This makes it useful for browsing through code and positioning the cursor to place a breakpoint.

For the buttons on the right, I’m still experimenting with what’s best. I assigned the “back row” (buttons 1, 4 & 10) to launching and terminating the debugger. Right now launching works correctly, but terminating isn’t working as expected, I’m not sure why yet. In the “front row” of buttons the rightmost two (3 and 9) are assigned to “Toggle Breakpoint” and “Left Mouse/Run To Line”, respectively. The later assignment causes the current line in the file under the mouse pointer to be selected and then execution to run to it and stop. Button 2, is assigned to “Alt-Tab” which toggles Windows between the last two applications. If you do it right, this will be the (Eclipse) debugger and the thing you’re debugging (an RCP?). This is a very handy assignment that lets you quickly flip back and forth.

The assignments for the joy sticks are also still a work in progress. I found that they are much harder to control and target than a mouse or a trackpoint. This might not be an issue in a video game if you’re piloting some kind of spacecraft, but in a program window its almost impossible to point and select anything. I’ve assigned it to control the mouse pointer and if you push it, it does a left mouse-click. So far this is okay for selecting big things like entire applications or an Eclipse view. I have yet to assign anything to the left joy stick.

My current profile for the S2900 is available here

Game Pad Stand

Having configured the game pad, I moved on to finding a home for it on my desk while avoiding the key pad’s placement issues. Being wireless, this particular game pad can rest almost anywhere in my work area. This is a mixed blessing though, as the lack of a fixed cord means that it could also migrate anywhere as well. It could easily end up out of sight under some papers, making it effectively useless. The best solution to this problem would be to have some easy to reach resting place that would be above desktop clutter.

My computer’s monitors are supported by “M7″ flat panel monitor arms made by Humanscale. These clear up a lot of desk top surface by putting the support for the monitors at the back of the desk and give about 20cm of free clearance below them. My solution for the game pad’s home was to create a custom stand that attaches to the back of one of my monitors and hangs down below it such that the game pad “floats” just below the monitor and just above the back of my (wireless!) keyboard.

To create the stand I first took a wire clothes hanger and experimented with bending it to form a suitable support. Once I had the proper shape I purchased an aluminum rod (4 feet, 1/4 inch, they don’t sell them in Metric sizes in the US) at my local hardware store and used a bending tool to reproduce the shape of my clothes hanger.

The next problem I solved was how to attach the stand to the back of the monitor. I did this by making some clips for the aluminum rod out of thin stainless steel strips and attaching them to the support plate of the monitor stand using the same screws that attach the plate to the monitor.

After a few adjustments for height, I tightened the screws and was done. The finished results are in the pictures below.

This photo shows the game pad hanging behind the keyboard with the key pad to the left.

This is a side view of the game pad stand.

Conclusion

Will the game pad be better than the key pad? I don’t have enough experience yet to make any conclusions, but so far I like it. It’s a little more comfortable to hold and I can lean back in my chair with the device without the need to keep my left hand in a particular position on a key pad rigidly tethered by a USB cord. The key assignments are still a work in progress, but I like having the step command keys under the two index fingers, they feel like very natural assignments. The one disadvantage I see is that being a two handed device, using the mouse has some overhead not present when using the key pad.

As for the stand, I like it. It is sturdy and it keeps the game pad in one easy to reach place that doesn’t conflict with anything else in my work area.

I really like the idea of Design-by-Contract (DBC), but when I tried to use it in my own code, I found a few problems. It wasn’t that DBC was particularly flawed, it was just that I usually program in Java and it isn’t part of the language as it is in Eiffel. This meant that I had to use some extra external tools to enforce the “contracts” I had written into my Javadoc. This turned out to be a bigger pain than I had anticipated. Things may be better now, but I discovered that either the tools I wanted to use were not actively being maintained or were just hard to use. They also added an extra “instrumentation” processing step to the normal edit/compile/run cycle that became something more to manage. I think, today, if I used AspectJ, I could probably make things run more transparently with less management on my part, but it wasn’t around with I came up with the following solution.

What I thought was the most useful and powerful feature of DBC was the “class invariant”. This was a check that the contents of a class instance were “correct”. Basically, it is a kind of “self test” on the state of the data structures in a running program. Given the lack of general knowledge and discussion of DBC, at least that I’ve observed, this little “gem” of an idea seems to have gone relatively unnoticed. As programmers, we generally don’t have a clue about the state of our running code until we notice something that isn’t quite right (a bug). Then we fire up the debugger and manually take the code out for a spin. With the class invariant we instrument our code such that we can ask the question “Is everything ok?” and have the code itself look for problems.

My solution is to dump the overhead of external tools and instead simply implement the DBC “class invariant” as a method within the class itself. This has the advantage of having no external dependencies and of making its invocation be completely under my control. To aid my efforts, I created a simple interface called SanityChecker that contains a single method sane() that returns true if the class instance is “sane” (i.e., validates the class invariant contract) or false if it is “insane” (i.e., a bug has been detected).

public interface SanityChecker {

boolean sane();

}

The trick to its usefulness is to implement it such that it throws an assertion exception if it detects that something is wrong. Here’s an example:

void sane() {

boolean retValue = super.sane();

// The length of the jobs queue should be less than ten

retValue = retValue && (jobs.length() < 10);

assert(retValue);

return retValue;

} // sane

Basically, this makes sure the super-class thinks it is “sane”, and then asserts its own sanity.

The idiom retValue = retValue && <boolean test> followed by an assertion of the value of retValue is a typical pattern. If followed, then once a problem is detected, an assertion will be thrown, or the rest of the tests will be skipped and the value of false returned. By having sane() return a value rather than simply relying upon the assert keyword sanity testing can occur even if assertions are not enabled.

The sane() method should be called when the instance is expected to be “stable” so the consistency checks should complete with no problems (if all is well). Typically, I find I use it like this:

main() {

// Do my big processing loop

while(true) {

assert topDataStructure.sane();

// Do the rest of the work here

} //while

} // main

The assert statement causes the state of the class instance referenced by topDataStructure to be validated before my code makes any changes to it. I implement the sane() method such that the class also asserts the sanity of any other classes it references (that implement the SanityChecker interface). They in turn, do the same. This causes the validation process to ripple throughout the program’s class instances (be careful to avoid cycles) and ensures that everything is as expected before the next iteration of the main processing loop gets its chance to muck things up. As a bonus, if a problem is detected, it is usually pretty easy to figure out which iteration of the loop is the culprit, this makes debugging much easier.

The net effect, for me at least, is that my code either runs, basically “bug free”, or it throws an exception and stops. And, if it does stop, the exception pinpoints the problem for me with high precision. Also, if I disable assertion checking (i.e., no “-ea” flag) then none of this checking is performed and the system runs without any baggage. The solution is simple, flexible, doesn’t require external tools and is extremely powerful; I’m happy.

Taking this idea further, one could imagine a simple extension to Java in which the class Object would include an additional method called sane(), like it does with toString(). As described above, it would return true by default and any classes that wanted to, could override it. It would be “simple” to trigger a debugger to run a “sanity check” and have the contents of the heap be validated automatically. This would be a lot simpler and more accurate than manually digging through with the debugger to “eyeball” class instances and make sure they look “ok”.

One of the things I learned early on in my career was just how powerful a force consumer demand was as a driver for technological innovation. Conventional “wisdom” tends to see the development of new technology as the driver for new consumer products, things like CD players, advanced computer graphics for PC’s, high-capacity storage devices, etc., but the reality is the exact opposite. Basically, if it wasn’t for a bunch of kids playing video games, we’d all still be using punch cards. I could go on about this, but my real purpose is to motivate people to examine the extremely innovative technology being developed for consumers and take inspiration from it.

Here’s an example. I spend a lot of time in front of Eclipse and really love it as a development environment. However, there is one thing that bugs me, I hate interacting with the debugger. Now, don’t get me wrong, I really like the debugger, it truly is my “friend”, I just hate pushing the “F” keys or using the mouse to click on tiny icons to make it step through a program. It just isn’t as fluid as I would like it to be.

One day while prowling Frys, I discovered the “Nostromo^TM SpeedPad n50″ and then about a year later (not at Frys) I discovered its “big brother” the “Nostromo^TM SpeedPad n52″, which I see is being updated as the “Nostromo^TM SpeedPad n52te”. These are “keyboard accelerators” designed for”first shooter” role playing games.

Basically, these devices are small USB keyboards that combine a number of standard keyboard keys (10 for the n50, 15 for the n52 and n52te) and controls (e.g., a roller wheel) together for quick access by a single (left) hand. Using configuration software, one can assign macros of customized key sequences (with timing delays if desired) to each key or control. The keyboards also have a “shift/shift lock” function that set it into three different modes identified by different colored (Red, Blue, and Green) LEDs on the device. This gives 60 (4×15) different macro assignments for just the keypad alone! Suddenly, Eclipse’s support for accelerator key sequences takes on a whole new importance.

Standing in the aisle at Frys, holding the n50 box in my hand, I realized that I could rev-up my partnership with the Eclipse debugger and go “first-person shooter” against the bugs in my code. I wouldn’t have to hunt around for a little spot on my screen with my mouse to just step the program. I could hammer away at my new “death-to-bugs” keyboard and fly through the code bringing order and correctness to all.

Getting it home, my first challenge was to figure out a good key assignment. I wanted to assign everything I possibly could, but soon realized that the keyboard would be a “paper weight” if I couldn’t remember what was assigned to what. So, I decided on simplicity and consistency at the expense of maximum utilization (i.e., I didn’t assign all the keys). I basically, settled on two main sets of assignments, unshifted for general Eclipse control (the mode I’m usually in) and shifted (Red) for debugging. I did make assignments for the other shift modes (Blue and Green), but use them less frequently.

In “Eclipse mode” (Unshifted), I assigned a mixture of Eclipse and editor controls, but I’m still experimenting with the best assignment. One thing I did correctly was to assign “Run Last Launched” and “Debug Last Launched” to the far left keys on two separate rows. This makes it fast and easy to start whatever I’m working and be ready for the debugger when it pops up. I also assigned “Add break point” to quickly insert a breakpoint. These three assignment are shared with the debugging mode (Red) so that I don’t have to remember which mode I’m in to use them, they always work.

For debugging (Red), I clustered the functions of “resume”, “step to return”, “step into (filtered)”, and “step over” together in that order so that with my fingers resting on the “home keys” my index finger would be sitting on “step over”. This way I could comfortably control most of the code execution I needed without moving my hand or leaving that row. On the row of keys above I added macros for “set break point”, “step into” and “run to line” (in the order).

I’ve played with assignments to the roller wheel, and some of the other keys clustered around the thumb position (to launch missiles more quickly, I guess), but I find them either awkward to use or they lack responsiveness and precision in their control.

To help my memory, I created a “cheat sheet” with the key assignments that I then pasted to some cardboard cut from a cereal box. I have it on my desk near the key pad for reference. I’ve uploaded the configuration file with my macro assignments and the word document for the cheat sheet.

I’ve looked closely at other game peripherals available in the stores to see how I might exploit them for my purposes. I really like some of the sophisticated Joysticks I see, and the Gamepads look like they just have to be useful to a serious programmer. However, I think to really exploit them we’ll need to rethink debugger interfaces, but that’s a subject for another post.

Cheat Sheet
Macro Assignments

Enjoy.

Dan