Support for Gravis Xterminator Digital gamepad

timixretroplays commented 1 year ago

Background

The Gravis Xterminator Digital gamepad was a gameport-only controller released in ~1997. It features a pass-through gameport connector and supports using multiple daisy-chained controllers. It only supports a variant of the Gravis GrIP protocol and does not feature a 4-button "1P" mode like the GamePad Pro does.

The Xterminator is readily available on Ebay, but currently cannot be used with any modern system due to its dependence on the GrIP protocol - it would be great to see the Necroware adapter support this controller. Currently, with the Xterminator plugged into my home-built Necroware adapter in GrIP mode, no new device appears in the list of Game Controllers in Windows, which I assume means it fails the validation used to confirm that a GamePad Pro is connected.

Implementation

The Xterminator Digital gamepad has an analog thumbstick, a digital D-pad, nine digital face buttons, a POV hat, a throttle slider, two analog triggers and two digital rear buttons.

The "S" button on the front is a "Hot Set Switch Button", originally used for "your favourite cheat moves" - I believe this is "BTN_MODE" in the Linux driver so it should be readable like any other button. Likely the original Gravis software would have reserved this button to switch to a different mapping or to run a macro on its own - this behaviour can be recreated using additional software (JoyToKey, reWASD etc) and would be out of scope for the context of Necroware adapter support.

Support for the Xterminator GamePad exists within the Linux GrIP driver, and it should be possible to implement Necroware support using this and the existing GamePad Pro support for reference: https://github.com/ilbers/linux/blob/master/drivers/input/joystick/grip.c

Note that the Linux driver supports a separate "GrIP mode" for four different devices - the GamePad Pro, the Blackhawk Digital (joystick) Xterminator Digital (this gamepad), and the Xterminator Dual Control (another joystick). If this approach is acceptable, I will raise additional issues to request support for the Blackhawk and DC joysticks; while the Dual Control originally shipped with a USB adapter, its pinout and design are undocumented, and I can see multiple DCs for sale on eBay right now without that adapter, so it would be great to see them supported by the Necroware adapter as gameport devices.

It should be possible to detect which type of GrIP device is attached based on the data packets received from the device, so the DIP switch config of 0001 should be sufficient to switch the adapter to support all possible Gravis GrIP devices.

Testing

I personally own an Xterminator Digital GamePad and will enthusiastically test any any attempt to implement support for it.

PXL_20230514_102142113 PXL_20230514_102103022 PXL_20230514_102053242

Rikki-Tikki-Tavi-12 commented 7 months ago

Is this still a current issue?

TinaFritz75 commented 2 months ago

Hello, I've the same Gravis Xterminator Gamepad and would like to use it as well. Apparently, it does not function with the Necroware Gameport Adapter - I thought, it was already implemented in the meantime when I bought it, but sadly, it's a no.

The Xterminator Dual Control 'Joystick' and the Necroware Gameport Adapter, on the other hand, also don't work together - but, I've an original Gravis Gameport Adapter just for that and it runs fine (it's really only for the Joystick, the Gamepad does not function with it). So, it should be easy to implement, if the programmer get one of them to work around, I guess?

Anyway, thanks for reading. I hope, someone with knowledge about it, could get that into the firmware.

Rikki-Tikki-Tavi-12 commented 2 months ago

@TinaFritz75 I had a look at the code, and I don't think it would be very hard to implement support for it. The basic protocol already works, it's just a matter of reading the Xterminator packages correctly. Do you want to send me the hardware?

timixretroplays commented 2 months ago

Hi all. Since writing this ticket over a year ago, I've had several developments in my own research:

There's a couple of different 'versions' of the Gravis GrIP protocol - the GamePad Pro uses a relatively simple one, the Blackhawk and Xterminator gear uses another, and the GrIP multisystem (2 gameport sockets, 4 9-pin GrIP-pad sockets) uses another
All of these were reverse-engineered 20+ years ago and open-source implementations written, mostly for Linux - I have bookmarks for this code
There are also actually two different versions of the Xterminator gamepad - one uses the same GrIP protocol as the Blackhawk and Xterminator Dual Control joystick, the other does something different I haven't found any information about yet
I have personally collected basically one of everything Gravis ever made, and am keen to use this collection to help implement and test support for these devices.

While I've since been able to code and build my own adapter for the GamePad Pro in GrIP mode, I don't quite yet have the programming skills to fully understand the code to talk to these other controllers. I have literally everything else on a shelf here, though, so if someone's keen to check out the resources I've found and take a whack at it, I can support it from the hardware side.

I won't have time until probably the weekend sometime to sit down and list/write out everything, so ask me anything about this pad in the meantime and I'll try and answer it.

Rikki-Tikki-Tavi-12 commented 2 months ago

@timixretroplays When you have the time, could you elaborate on why you think there are two different versions of the Xterminator gamepad? What did you find about the possible third version of the protocol, not mentioned in the Linux source file?

To be clear, I don't have an oscilloscope good enough to reverse engineer protocols. My only scope is single channel, non-recording. I wouldn't want to go deeper than adapting what is already in the Linux file.

timixretroplays commented 2 months ago

Okay so, I don't remember anymore exactly how I discovered there are two different Xterminator gamepads, but I've now collected one of each. One comes with a dumb USB to gameport adapter in addition to the Y-adapting gameport plug and will work when plugged into USB (I assume the adapter just links buttons 1 and 2 to the two USB data lines, and VCC and GND as appropriate, but I haven't tested this), the other just has the Y-plug for gameport and nothing will happen if you try plugging it in using the USB adapter. Photos in this post are of the USB-enabled Xterminator gamepad.

It's easy to tell between them. The non-USB one is model #44011, has "Xterminator (and then in tiny text) Digital Game Controller" in green text on the box, just says "GRAVIS Xterminator" on the gamepad itself. The USB-compatible is model #44111, says "Xterminator Digital Gamepad" in white on the box (and says "USB and gameport compatible"), and also says "GRAVIS Xterminator DIGITAL" on the pad itself. (Both gamepads are digital, but one is... more digital than the other.)

Here's probably the biggest, best thread I've found about reverse-engineering the USB one: https://www.avrfreaks.net/s/topic/a5C3l000000UW4wEAG/t137104

Someone named Hyratel pops up later in the thread to share this implementation: https://gist.github.com/Hyratel/4e689925743fb789b5cf3cca3812511a he mentions the timing is super tight on a 32U4-based Arduino, clearly it can be made to work but for my own project I plan to start with a Raspberry Pi Pico 2 as it's just as accessible but a lot faster.

I'm in contact with Hyratel on Mastodon, we chatted a bit about the Blackhawk Digital which basically uses the same "Xterminator" packet as the XT and XDC and I have a (paused) project to re-implement that for myself on a 32U4.

I can't find my source for the tidbit about the two Xterminator pads having different GrIP protocols, it's possible I invented that in my head and both will work fine from the same gameport-pin-bashing code. I haven't gotten as far as testing either XT pad with any code yet.

The Linux GrIP driver is here: https://github.com/ilbers/linux/blob/master/drivers/input/joystick/grip.c it reads "GPP" (GamePad Pro) and "XT" (Xterminator) packets, but I currently have no way to test if it works with both XT pads.

Regarding the third mysterious GrIP spec, here's the most extensive code I've found that talks to the GrIP Multiport: https://android.googlesource.com/kernel/msm/+/android-wear-5.1.1_r0.2/drivers/input/joystick/grip_mp.c I cannot explain how it ended up in Android Wear 5.1, but it's not like this code's changed in 20+ years. This was written by someone else (Brian Bonnlander, not Vojtěch Pavlík) and is better commented, and is clear enough to me to see that the Multiport is a two-way device - data gets sent to it as well as received from it.

PXL_20240922_080227977 PXL_20240922_080242585 PXL_20240922_080322959

Rikki-Tikki-Tavi-12 commented 1 month ago

It seems to me like implementing support for the USB-capable version would be lower priority, since it the USB adapter is still readily available. It would be interesting to know what the USB adapter actually does. There could be an IC molded into the plastic, or it could just be connecting some wires up, maybe with a resistor in there for identification. In the latter case, I would guess that one of the gamepads in line registers as a USB hub (the one at the usb adapter, probably).

necroware / gameport-adapter

Support for Gravis Xterminator Digital gamepad #61