Table of Contents

Ergodex DX1 Open Source Drivers

Ergodex created the device in 2005 and released it to the world where it received much praise, especially from left-handed gamers who until now have had to suffer with remapping the keys on every single game they play to the opposite side of the keyboard. Some games, including many popular games, don't even allow keyboard remapping thus forcing their users to struggle to play the games how their narrow minded right-handed developers designed them. The Ergodex is a godsend to left-handed people as it allows you to place up to 50 keys where ever you like on the pad and assign any keys (and macros) to each key and have the pad automatically reconfigure itself depending on the current application in use. It's also great for many other users, for right-handed users it allows you easier (and faster) access to more keys. Many disabled users are also finding it very useful. In fact the device is so good it recevied an award from popular science in 2005 Best of what's new 2005.

Unfortunately Ergodex have not created any drivers for MacOS X or Linux, nor even Windows XP64 bit, now Windows Vista is out and there's still no offical drivers for these 4 important operating systems! Ergodex will not give ANY information regarding support for these 4 operating systems for which drivers do not exist. Nor will they give ANY information regarding driver updates and new features - not that the existing drivers on Windows XP 32bit don't work, they do, and very well, it's just that we want more from our DX1's than Ergodex seem to be willing to provide.

This site aims to bring together as many developers as possible in order to first document the USB protocol the device uses and second to write new drivers, primarily for Windows 7, Windows Vista and Windows XP and (all 64 and 32bit editions) while attempting to keep as much of the code as reusable as possible so that it may be used to create MacOS X and Linux drivers too.

This project was started in February 2007, just after the retail release of Windows Vista.

Join In

If you want to help with the project please drop me, hydra, an email at this address: me at dominicclifton dot name

Please note, due to excessive edits by spammers all wiki accounts have NO write access until they are verified personally by me, please email me if you'd like your account verified or just email me with any changes you'd like to see added if that's too much trouble. Sorry about this, damn spammers!

If you've not used IRC before then grab a copy of HydraIRC (which I, Hydra, also wrote ), install it, start it, create a profile then click the irc: link above to join the channel or use file/connect and paste in the irc: link from above and click “Ok”. Shortly after you should see a connection to irc.freenode.net being made and then a new window will appear for the channel. If the channel is empty just wait and someone will appear. If you want to page me then just say my name (Hydra) in the channel.

Pystromo - Originally only targeted at improving Linux support for the Belkin Nostromo n52 with arbitrary macros, it was expanded to cover any USB device in linux

Donations

Donations can be sent to “paypal at hydrairc dot com”. Any amount gladly received and will go towards paying for the hosting of this site.

Many thanks to those that have already donated, your donations have been graciously received - Hydra

Current Status

2009/10/17 - Hydra

I played my first game of Team Fortress 2 using my Ergodex programmed with a test keymap! The keymap is currently hard coded into the padcontroller command line utility.

2009/10/13 - Hydra

While waiting for MS to hurry up and give me a product key I *cough* installed a *cough* test version of Window s7 on my main box which now no-longer has Windows XP on it. Now there's a milestone if there ever was one.

2009/10/05 - Hydra

I ordered Windows 7 64bit and I'll be upgrading my main machine to use Windows 7 as soon as possible. I'm going to try and get very basic drivers before Windows 7 comes out but progress should be good once my main box is upgraded as i can't live without my ergodex.

2009/07/15 - Hydra

The drivers can now sends data received from the device to the app that wants read notification. Driver wise there's not much left to do now, application wise there's lots to do!

2009/07/02 - Hydra

An app can now send write requests to the driver, the test tool now successfully issues the 'get device information' command using the new code.

2009/07/01 - Hydra

More significant progress! An application can request that the driver notify the app when the driver recieves data from the device, the priority of the application is also boosted when notification is sent. This means that there is now device→application communication where as before all other communication was app→driver.

I also decided to keep the driver dumber that I was previously going to in order to keep the amount of code in the driver itself as small as possible. The main reasons for this are: code duplication of things like keymap processing in non-dx1 drivers, it's simpler, less driver code to maintain, kernel mode code is time consuming to create, debug and maintain, you can't use OO (no C++ in KMDF), there's no IDE integration for Visual Studio for KMDF code, my lack of expertise in kernel-land is a time-sink and I'll make faster progress, more reusable cross-platform C++ classes (i.e. the ones I wrote back in 2007!).

2009/06/29 - Hydra

Added the ability to enable/disable the test mode and set the led's to indicate a test mode.

2009/06/28 - Hydra

Made good progress today, my new WDMF driver can continuously read data from one or more (tested with 2) DX1 pads and dump it to a kernel debug console. The command line tool can be used to trigger various actions within the driver and I'm very happy at being at this stage as it's quite an accompishment for me as until know I didn't really know much about writing drivers, real kernel debugging, the differences between WDM, KMDF, UMDF and how PnP power management, io requests, usb device management and configuration really worked, now I do! I also managed to leverage some features of KMDF which made implementing 4 parallel IO read requests *very* simple indeed. I must also say that there's some great whitepapers and documentation on MSDN regarding kernel device driver data flow, objects and such like. Thanks Microsoft tech dudes!!!

2009/06/26 - Hydra

I had big issues getting my drivers working again after I changed the .inx/.inf files which has taken me all morning to solve. I did find and bookmark some good documents on the subject of device driver installation, driver stores, driver signing and pnputil so it wasn't a total waste of time. Right, now back to coding

2009/06/25 - Hydra

The name for the driver project has been decided - 'Pad Controller'. The idea being that the software will support multiple pads, and will (maybe) later support other kinds of pads (like Nostromo n52's, etc).

With the release date of Windows 7 set for October 22nd 2009 and an updated Windows Driver Kit now available I thought it about time I got on the case of getting this project moving. Luckily in the process of changing jobs I've got a weeks paid holiday, starting today, and I plan to use the time before my next job to get some drivers released! I've already upgraded my other development machines to Windows 7 RC1 in preperation and I'm about to begin coding in earnest.

12:52 - I got my Windows 7 RC1 x64 box doing remote debugging via Firewire (the previous Windows 7 version on the same box wouldn't play ball) and I documented how to set up and use kernel debugging for the USBSAMP WDK driver example and a DX1 including setting break points and stepping though source in WinDBG. I'll put the docs on the wiki soon. Next up: learning the API's used in the USBSAMP example.

2009/04/15 - Hydra

In order to debug the device and see trace messages i need to use remote kernel debugging but annoyingly I've not been able to establish a 1394 remote debug session to my Windows 7 box, however I have managed to establish a connection to Windows Vista running on my laptop so I'll try adding a spare PCI 1394 card to the Windows 7 box and/or try installing Windows 7 on my laptop instead of Vista.

Today I also managed to get WinDbg on the host to display DbgPrint messages called from the code running on the target. I also figured out how to get the driver's debugging symbols loaded in WinDbg and can successfully view and change memory, set breakpoints and step though the source code in the debugger. This means that should (when!) I encounter any issues in the driver then I'll at least be able to see what's going on!

2009/04/14 - Hydra

I've installed Visual Studio 2008 and The Windows 7 DDK on my 64 bit Windows 7 development machine and have successfully compiled and tested a basic usb driver from the DDK and read data from a connected DX1. I had to jump though a few “driver-signing” hoops to get this far. Currently the 64 bit driver is only test signed and eventually I'll need a way to sign it properly.

I've also decided to take the approach used by the official ergodex drivers (different from the other available drivers) in that the driver itself will be constantly retrieving data from the DX1 rather than a user-mode application (or UMDF driver) doing so. The main reason is response time within games or other time-sensitive applications, like music. User-mode apps and drivers are slower than kernel mode drivers.

This means that I won't be able to use some of the code I've already written (it's C++, not plain C) but it'll be better in the long run.

2009/04/13 - Hydra

I downloaded the latest Windows 7 DDK from Microsoft Connect today and rebuilt and re-tested the padmonitor code. I created a (local) git repository for the project which I'll get around to hosting or moving to svn + trac. I also plugged my second Ergodex DX1 into my main machine and had one pad using my drivers one one using the ergodex drivers and as expected they co-existed quite happily. I tweaked the pad monitor shutdown code and everything seems to be 100% working for me right now as per the last code-related update around this time last year! More progress soon!

2009/02/25 - Hydra

Just a quick status update: I've purchased a second Ergodex DX1 (and set of keys) via ebay and I'm impressed with Windows 7 (I lost interest in Vista, hence no project activity) and I'm keen to progress this project further during the coming months and will be developing Windows 7 drivers featuring multiple-pad support which will probably work with Vista/XP too. Keep an eye on future developments!

As a side note it's such a shame to see Ergodex stagnate when they could be doing so much more with the technology, even simple things like a box of different sized keys would go along way with me.

2009/01/19 - JH

Posted a compiled Mac OSX Intel binary for Rab's Linux driver on the download page. Also instructions on how to compile your own if you're so inclined.

2008/10/06 - Rab

Posted the Linux “driver” that I wrote last year on the download page. It's not all that exciting, but it will allow you to use your DX1 under Linux for most scenarios. It's totally separate from the C++ windows driver being worked on (much simpler, but not as feature rich as the C++ one is aiming for).

2008/03/23 - Hydra

Ok, so i ripped all the startup and shutdown code from my monitoring app today and also gave each CPadDevice it's own thread and figured out why some of the older code i'd written was causing problems.

Now I have the main UI in one thread, the CPadMonitor class in it's own thread (so it can do macro related stuff without the UI thread getting in the way, plus i didn't see an easy way of coupling the ui's main loop with one or more pad's io loops), the pad monitor can spawn any number of pad devices and it owns, starts and stops their threads.

Everything seems to be working ok so far.

I've also figured out why, and equally importantly where i need critical sections in the code and moved some parts of the code around so that i need less of them.

Previously what was happening was i was queuing up commands in one thread while the thread that processed commands was running and screwing around with the command queue. Now the startup commands are queued by the same thread that processes them.

If you remember I'd never written any multi-threaded code and thus knew nothing of how to design them and what all the pitfalls and gotchas are.

I'm much happier about the code now, no horrible hacks anywhere in sight.

Still not happy with the CreateFile() usage of the USB pipes though, it seems i can't prevent the same pipe being opened more than once. Another reason to put the IO code in the driver.

Next I'm going to code device detection routines so that other people can try what i've written so far as currently it's hard coded to use one specific usb port on my machine.

I've updated the Doxygen Documentation on the site which has been generated from today's code, a source code and binaries snapshot is available on request via the Downloads page.

It's good to finally make some progress.

In other news it appears that there seems to have been some financial issues between Ergodex and the developers of the original software which is why there hasn't been an update of the software for a while. It appears that Ergodex are trying to get other developers to work on the code but I certainly wouldn't hold my breath (and if you are those other developers I'd be asking for cash up front if I were you!). This underlines the fact that we need some open-source software so that owners of these wonderful pads can continue to use them forever. Since there are these financial difficulties between the original developers and Ergodex it's highly unlikely that we'll ever see multiple pad support or any new major features (think shift states, etc) from Ergodex. Since I, and others, have been sitting on the fence waiting for something to come from Ergodex, knowing that there's not going to be anything gives us all a reason to get on with writing replacement software.

2008/03/15 - Hydra

Interesting comment from Anon below. Hope that's not the case, and if it is the case perhaps Anon wouldn't mind getting in contact with me?

In the meantime in some bizarre timing coincidence I actually did a spot more work on my open-source drivers today. I basically cleaned up some of the pad monitor shutdown code in vain attempts to solve the threading memory corruption issues and while it's cleaner it's still broken but this time in a different way.

As all the device communication code works perfectly I'm thinking of scrapping the current application and pad monitor code and might just write a single threaded application that can still support multiple DX1 pads. If I don't take this approach I fear I'll never get the drivers written at all.

Even though I've got a new PC I'm still not running Vista or XP64 and still only have one DX1 pad.

If everyone reading this clubs together and donates a few pounds I could buy a second DX1 or a CH-Products Pad which would certainly give me a good reason to spend more time on this project.

2008/03/09 - Anon

Ever wonder why there is no new Ergodex software released? Perhaps it is because they never paid the people that developed the software.

2007/11/16 - Hydra

I really need some decent examples of how to start, suspend and stop threads and send messages from/to worker threads from/to a main task and how to use critical sections in C++. if anyone knows of any good web-sites or can recommend any current books that give a good overview on these topics PLEASE CONTACT ME ASAP!

2007/07/31 - Hydra

Currently on hold until I find some time to learn more about C++/Win32 multi-threading, thread-synchronisation, semaphores, critical sections and who knows what else. Or, until someone submits a patch to help me out. Just ask if you want to help out with my current C++ codebase.

2007/04/05 - Hydra

Looks like I started this project at just the right time as it appears the ergodex.com website is now down and has been for the last 2 days! I better get cracking on these drivers… :) I will probably setup some forums here soon, now that there's (currently) no forums available on the ergodex.com site.

2007/03/16 - Hydra

I'm back from my snowboarding holiday now (which was awesome) and have been loaned a second Ergodex DX1 pad which will allow me to implement and test multiple pad support! Many thanks goes to Richard Veitch for the loan of the second DX1.

More progress on the Pad Monitor core, some UI interaction and status reporting now in place. Added a screenshot to the new Development Screenshots wiki page.

2007/02/12 - Hydra

Excellent progress made on the Pad Monitor core. I now have the lots of nice C++ OO code written for creating command requests, parsing responses, processing command queues, processing input, raising events based on responses, matching responses to commands, matching responses to commands and raising events based on completed commands. All multi-threaded too! The pad data processing thread is separate from the UI thread, enabling rapid processing of “macro key” presses and releases.

C++ code for input steam (including dealing with corrupt data, short reads, etc) has been done.

2007/02/09 - Hydra

Added the Software Components page to the wiki with my ideas on how to implement a software solution that could potentially work with many kinds of HID devices.

2007/02/08 - Hydra

A test driver has been written and works on Windows XP 32bit. Recompiling for XP64, Vista 32 and Vista 64 should not present any problem and will be tested and made available for download soon.

2007/02/07 - Hydra

Completed reverse engineering the parts of USB protocol that are required in order to write drivers.

Copyright

No information from this site is to be in any commercial projects.

Anyone wanting to use the information from this site for purposes other than the goals of this project should contact the project maintainer first.

All code written will most-likely be licensed under the GPL license.

Images used on this page are copyrighted to their respective owners, if any images are used on this site and shouldn't be please remove them and fill in the edit summary accordingly, provide alternates where possible.