The Wombat is great for adapting USB keyboards and mice to classic ADB Macintoshes, and ADB keyboards and mice to modern USB computers. But what about game controllers? They’re not supported. It’s an often-requested feature, but one that’s not as easy to implement as it might seem. The main problem is that unlike keyboards and mice, there doesn’t exist any uniform standard for communicating with game controllers: neither for ADB nor for USB.

In the past when people have asked about game controller support, it’s not always clear if they’re asking to use USB game controllers via the Wombat on a vintage Mac, or if they’re asking to use classic ADB game controllers like those from Gravis via the Wombat on a modern PC. From reviewing the comments and emails I’ve received, I think interest is roughly evenly split between USB-to-ADB and ADB-to-USB game controller support.

I’m using the term “game controller” here to include both joysticks (typically analog) as well as gamepads (typically a collection of buttons with digital on/off status). The challenges involved in both are similar, but the details differ.

USB-to-ADB Game Controller Implementation

Of the two possible directions for adapting game controller communications, this is probably the easier one: connecting USB game controllers via the Wombat to play classic games on a vintage Macintosh. For the moment, let’s limit our thinking to just gamepads with digital buttons. A simple way to implement basic support might be to program the Wombat to make gamepads appear like a keyboard to the Mac, with a fixed key map. For example the D-pad buttons could send arrow key press events, ABXY could literally type A, B, X and Y, and the Select button, Start, and shoulder buttons would send other keyboard key events.

This may be doable, but there are some difficulties. The main issue is that as far as I understand, there’s no true standard way for USB game controllers to communicate their state to a USB host. Some use DirectInput, some use XInput, some use regular USB HID as if they were a standard keyboard or mouse. The Wombat would probably need to support all of these methods, and somehow determine which one to use. DirectInput and XInput differ from regular USB HID, and supporting those input methods would require developing a new feature for the Wombat firmware.

The other big challenge is that apparently there’s no standard order in which USB game controllers report the state of their buttons. One might report its D-pad as buttons 0 through 3, another as buttons 2-5, another as buttons 6-9. That would seem to prevent the Wombat from using any kind of fixed button-to-key mapping, like automatically treating the D-pad buttons as arrow keys, because it wouldn’t know which are the D-pad buttons.

Maybe the games themselves could be configured in their preference settings to expect directional movement input from a weird key combination like X/1/B/A, but I don’t know if all games are that flexible. Probably some are hard-coded to expect arrow keys for movement and space bar to jump or shoot. Users would also probably be confused or frustrated if the behavior and default button-to-key mapping were different depending on the exact brand of USB gamepad they used, seeing different behavior from nearly identical-looking gamepads.

It would be better to include a configuration / mapping layer somewhere, but where? The Wombat lacks any UI of its own, and isn’t suited to that task. Maybe a text configuration file could be loaded from a USB thumb drive. It seems clunky, though.

The USB gamepad wouldn’t necessarily need to appear as a standard keyboard to the ADB Macintosh. Another option could be to make it appear as if a Gravis gamepad were present. This would also require installing the Gravis control panel on the Mac. Fortunately the Gravis ADB protocols have been documented by Tashtari, so it is technically possible, but I’m not sure it would really solve any problems. If the Wombat doesn’t know whether USB gamepad button 1 is D-pad right or the Start button, then it can’t do a sensible job of emulating a Gravis gamepad, no matter how the Gravis control panel is set up. Ultimately I’m not sure that emulating a Gravis device would provide any clear benefit over emulating a keyboard and/or mouse.

Maybe the situation isn’t as bad as I fear, and in practice USB game controllers are more consistent than I think? I could buy a sample set of the 5 or 10 most common or most popular USB game controllers, and analyze how they work. But that could be expensive and time-consuming.

As for joysticks, I know a lot less about how they work, both on the ADB and USB side. According to one report, typical ADB joysticks behave like a mouse+keyboard to the Macintosh, where the “cursor” snaps back the same distance it traveled in the axis when pressure is no longer applied to the stick, and the buttons get mapped to keyboard buttons. I’d probably need to purchase some ADB joysticks to experiment with, to confirm their behaviors and see if there are differences across models and brands.

ADB-to-USB Game Controller Implementation

I’ve thought much less about this direction. To me, it seems the less compelling of the two. There are real reasons to want USB-to-ADB game controller support: you want to play a classic game on your classic Mac, but classic ADB game controllers are very hard to find. A USB game controller plus the Wombat could then serve as a substitute. The purpose of ADB-to-USB game controller support would be more for nostalgia or for laughs maybe. Yeah you could use your ADB Gravis Mousestick II to play a modern game on your Windows machine, but it’s a little silly when you probably already have a perfectly good USB joystick, or can purchase one for a few dollars.

Putting aside the question of rationale, Gravis protocol support would be a must for ADB-to-USB game controller support. All of the most popular ADB game controllers were made by Gravis, so the Wombat definitely would need to know how to talk to them. Translating the input from the Gravis controller and emulating a USB game controller or joystick might be simpler than the reverse task, because I could probably just choose one of the three common interfaces (DirectInput, XInput, USB HID) instead of needing to support all three. And I wouldn’t need to worry about non-standard button mappings, since I’d only need one mapping, and could just copy the mapping from any popular USB game controller. I think.

As you can see, this is all about as clear as mud, and maybe it gives you more appreciation for why game controllers have remained unsupported by the Wombat. It’s just not a straightforward task, and there’s no obvious “best” solution. I’m sharing my thoughts here and looking for your feedback on all of this. Which direction of game controller emulation would be most valuable to you? How would you imagine it working, exactly? Have I overlooked or misunderstood anything important about the implementation details? Do you have any experience with USB game controllers and how they typically work, how they select between the various communication protocols and so on? If you all can help me sketch out a plan that makes sense here, I’ll try to implement it.

Mea culpa time here. Since the beginnings of the Wombat there have been reports that certain USB keyboards and mice weren’t recognized by the device. Nothing happened when typing or moving the mouse, and the Wombat’s activity LED didn’t blink. The affected devices were usually fancier keyboards and mice with lots of buttons and features, as opposed to plain vanilla $8 two-button mice and generic 101-key keyboards. I had always chalked this up to some unknown issue in the Microchip USB stack code for handling of peripherals with multiple USB interfaces or a single interface with multiple types of data. It was something in the bowels of that code, which I didn’t write and didn’t understand too well, so I treated it as a regrettable known incompatibility.

Recently a few Wombat customers reported more problems like these related to the Logitech Bolt USB receiver, and I decided to take another look. One helpful customer sent me a dump of the Bolt’s USB HID report descriptor as reported by Linux. I dug through the code with the help of AI, attempting to analyze how the USB stack would handle this report descriptor. It looked hopeless, until…

After wading through thousands of lines of mind-numbing USB goo, I found the smoking gun. Upon completing a USB transfer, the code was storing the number of bytes transferred in an 8-bit local variable and then comparing it to the 16-bit expected transfer size. The result was that any transfer larger than 255 bytes would always fail! Please queue the laugh track and sad trombone sound effects.

What does this have to do with composite USB devices? Nothing, except that composite USB devices have more interfaces with more data to report, resulting in larger report descriptors that are more likely to exceed 255 bytes.

Firmware 0.3.11 was released yesterday to fix this bug. It’s not just something relevant to the Logitech Bolt. If you’ve been using the Wombat in USB-to-ADB mode and encountered certain keyboards or mice that just mysteriously didn’t work with the Wombat, please try the new firmware. There’s a good chance that this will fix it.

The Wombat ADB-USB input converter is now back in stock! Thanks for everybody’s patience during this manufacturing delay.

The Wombat is a bidirectional ADB-to-USB and USB-to-ADB converter for keyboards and mice.

• Connect modern USB keyboards and mice to a classic ADB-based Macintosh, Apple IIgs, or NeXT
• Connect legacy ADB input hardware to a USB-based computer running Windows, OSX, or Linux

No special software or drivers are needed – just plug it in and go. The Wombat is great for breathing new life into your vintage Apple hardware collection.

You’ll find the Wombat here in the BMOW Store. For more details, please see the product description page.

A few days ago I received an urgent note from the facility in China where the ADB-USB Wombat Input Converter is manufactured. They’d just finished assembling 250 new Wombats, and all of them were failing the automated functional tests. Was there a systematic assembly flaw in this entire batch of boards? Or was it a problem with the test apparatus?

I developed the Wombat tester (pictured above with a Wombat riding on top) back in 2017. It’s a board with some simple electronics and an array of spring-loaded pogo pins that make contact with a Wombat board placed on top of it. Grab a newly-assembled Wombat, press it down onto the bed of pins, press a button, and in a few seconds you’ll have a functional test result. Hooray for high-speed testing. The Wombat tester that’s used by the Chinese factory is the original one that I hand-built six years ago.

The tester’s schematic is terrible, and I have no one to blame but myself. It looks like a pile of disconnected components where you can’t really make sense of anything. There are only three chips – everything else is connectors or pogo pins. IC1 is a triple 2-channel analog switch, IC2 is a power distribution switch, and IC3 is a simple quad-OR:

I had only two pieces of information:

1. The functional test was failing ADB communication. USB communication was apparently OK.
2. An engineer found that bridging pins 6 and 7 on IC2 allowed the test to finish successfully.

The engineer suspected IC2 had failed and was searching for a replacement. Given the clues and the schematic diagram, what do you think is the most likely cause of the failure?

IC2 pins 6 and 7 are two separate power supplies: one that’s normally supplied by the ADB host, and another that’s supplied by the USB host. Only one should be active at a time, so bridging them together is not a valid test. Because bridging helped the failing ADB test to succeed, it suggested maybe the ADB5V supply was not turning on when it should. Yes, that could be due to IC2 failure, but could also have other causes.

The ADB5V supply is enabled by the control signal /ADB5VON at IC2 pin 3. That signal comes from the quad-OR gate at IC3, so maybe that was the source of failure? The quad-OR is also responsible for generating the USB power supply control signal. Both signals are dependent on three signals named UNK3, /UNK3, and GNDOUT. Because bridging the IC2 supply pins helped somehow, we can probably conclude the USB supply was active, meaning that /VBUSBON had to be asserted. If the quad-OR was working correctly, that means UNK3 and GNDOUT both must have been low.

What’s with these UNK3 and /UNK3 signals? Tracing back further, we see that /UNK3 is generated form IC1, where one channel of the analog switch is rigged up to behave like an inverter. The non-inverted signal UNK3 has a pull-down resistor at R2. Ultimately the UNK3 signal comes from J7 pin 3, which is one of the pogo pins. The signal comes from the Wombat board being tested, via the pogo pin.

Hmm… what would happen if that pogo pin were misaligned or broken? UNK3 would be disconnected and floating, but the R2 pull-down resistor would bring it low. With GNDOUT also low, /VBUSBON would always be asserted and /ADB5VON would never be asserted. The ADB power supply would never turn on, the USB supply would always be on, and the behavior would be consistent with the observed clues.

Mulling this analysis over a cup of coffee, I replied to the factory: “Check if pogo pin 3 at J7 is bent”. Their response came the next day: “Steve, you are really a professional engineer! The guess you made is correct. After trying again, the tester board started working normally.”

Success! That was a very satisfying fix, based on minimal information and without physical access to the faulty circuit.

The BMOW Wombat enables the use of USB mice with ADB computers, such as classic Macintosh and Apple IIgs systems. It’s a great feature, but sometimes the mouse tracking speed appears too fast or too slow for convenient use, even after making adjustments in the host OS’s mouse control panel. Firmware version 0.3.9 introduces a new Wombat feature to help: hardware mouse scaling.

With each long-press of the USB mouse wheel button (longer than half a second), the Wombat increases the mouse tracking hardware scale by a factor of 2. This scale is in addition to any mouse scaling that’s applied in the host OS’s control panel. The available scaling factors are 1/2/4/8/16x. For the Razer Basilisk v2 mouse shown in the video, I found that 8x scaling felt about right, but your tastes may be different.

Firmware 0.3.9 also disables an error-checking feature in the Wombat’s parser for USB HID report descriptors, because some USB devices have a minor error in their report descriptor, including this Basilisk mouse. The descriptor uses a sort of universal grammar for HID devices to describe what they do and what kind of data they can send and receive. The Basilisk has an error in its report descriptor where it specifies a maximum possible value of 572 for a report item that’s only 8 bits in size. The Wombat report parser was seeing this error and rejecting the whole device. Disabling the error check enables the Basilisk to work with no ill effects. This change may also “fix” some other USB mice and keyboards that previously weren’t recognized by the Wombat.

Download the latest Wombat firmware now, and let me know how it works for you.

Firmware version 0.3.8 is now available for the Wombat ADB-to-USB input converter. This version fixes a minor problem with the latching Caps Lock key on ADB keyboards in ADB-to-USB translation mode. If you accidentally bumped the Caps Lock key without depressing it fully, you could sometimes end up with Caps Lock enabled even though the key wasn’t latched down. Firmware 0.3.8 resolves this little annoyance. You can download the latest Wombat firmware from the project home page.

Are you new to the Wombat? It’s a bidirectional ADB-to-USB and USB-to-ADB converter for keyboards and mice. With the Wombat you can connect modern USB keyboards and mice to a vintage computer like an ADB-based Macintosh, Apple IIgs, or NeXT. Or you can do the reverse, and hook up vintage ADB keyboards and mice to a modern USB-based computer running Windows, OSX, or Linux. Want to rock an AEK II on your new M2 MacBook Air? The Wombat is your solution. Get yours now from the BMOW Store.