Author Topic: Ultimarc Servo-Stik plugin for Linux  (Read 140 times)


  • Full Member
  • ***
  • Posts: 42
    • View Profile
Ultimarc Servo-Stik plugin for Linux
« on: February 12, 2018, 11:43:30 PM »
EDIT: don't use this method! The author of RGBCommander just made a utility that switches the ServoStik via commandline, works great. I'll update this plugin once he posts it.

Leaving this here in case it's useful, but repeat, don't use this method, since switching your ServoStik controller board into "hardware mode" is irreversable.

I couldn't find a reliable way to control my ServoStik under Linux so I made a plugin to control it using "hardware mode" and these cheapie USB relays ($4 shipped!):

Works beautifully with Attract Mode and my joystick is finally always in the right mode for whatever game I'm playing. Whoohoo!

Setup notes:

- put the Servo-Stik's control board into "hardware mode" as described here:

Note that this makes it so you can't control the Servo-Stik via USB anymore, which is a shame. And the change is permanent! So proceed with caution, and you might want to read my "alternative methods" section below before proceeding.

Once you make this change you're essentially switching the mode of the Servo-Stik with a relay acting as a toggle switch.

- Get your relay using the instructions here, I got the single relay for $4 shipped to California.

- Strip the wires from a USB mini cable. Connect the red and black wires to a 5v power supply (the 5v pins on the USB relay didn't seem to provide enough power for reliable operation), then connect the white wire to the NO pin of the relay, the green wire to the NC pin of the relay, and roll up the shielding and connect it to the common pin of the relay.

- When you're done it'll look something like the attached image, except that I wouldn't recommend getting power from the relay board itself as in the picture, things were really flaky for me until I connected the power to a stripped down 5v wall wort.

- You'll need to install the usbrelay program as described here (, or in Debian variants you can just run "sudo apt-get install usbrelay". After installing run "usbrelay" to see the address of your relay and adapt this plugin if needed. You can adapt it either through Attract Mode's plugin configuration section, or directly in the code of the plugin.

On my system this command turns on the relay:

usbrelay HURTM_1=1

And this turns off the relay:

usbrelay HURTM_1=0

If you have things wired up you should see your Servo-Stik magically switching between 4 and 8 way. If not, run simply "usbrelay" to get the address of the relay ("HURTM" in the example above). I don't know if the address varies from relay to relay. If you have a different address you'll need to edit the plugin either directly or by going to it's plugin config section of Attract Mode. You should be able to switch the mode of the Servo-Stik with the above lines of code at this point. If not, go over the steps above carefully.

- With the configuration here, I'm turning on the relay for 2 and 4 way games, and turning it off for 8 way games. Works great.

- And note that this plugin was adapted from;msg=14283;topic=1898.0

Feel free to email directly with any questions, since I don't think the post notification feature is working on this board. My email is wrybread at gmail dot you know what.

Alternate methods:

- I'm really impressed with the Servo-Stik, but it would be nice if we didn't have to put the control board into "hardware board" to control it in from a relay or switch, since doing so is a permanent change, meaning we can't control it via USB ever again. Andy, if you're listening, how about adding a couple of pins to the board so this is always possible, even in regular USB mode? Or a jumper to return the board to regular USB mode?

- I tried RGBCommander, which was able to control the ServoStik, but not in conjunction with Attract Mode since my version of MAME (.175) isn't supported. Most of my ROMs didn't work with later versions of MAME so I abandoned that route, but more notes on the issue are in this thread

- the author of RGBCommander said he has a commandline utility to switch the Servo-Stik, which would solve the issue completely, but as of now he hasn't released it yet. Please do?

- I'd love to make a Python script to control the Servo-Stik directly using pyusb, but couldn't find very many details on the protocol. Andy sent this over, maybe someone can make sense of it?

Code: [Select]
Private Sub button4_Click()
    OutputReportData(3) = 0
    OutputReportData(2) = 0
    OutputReportData(1) = 0
    OutputReportData(0) = 0
    Call ReadAndWriteToDevice
End Sub
Private Sub button8_Click()
    OutputReportData(3) = 1
    OutputReportData(2) = 0
    OutputReportData(1) = 0
    OutputReportData(0) = 0
    Call ReadAndWriteToDevice
End Sub

Anyway, plugin attached and pasted below, hopefully it's useful to someone.

Code: [Select]

This is an Attract-Mode plugin to use a ServoStik under Linux (or other OS's)
with a USB relay. These USB relays are dirt cheap, under $5 shipped to the U.S.,
and work beautifully with a ServoStik in hardware mode.

More notes on the relays here:

More setup notes for this plugin here:

wrybread at gmail dot you know what
February 12, 2018


// user config
class UserConfig </ help="Plugin to use a ServoStik joystick in hardware mode under Linux. See the header of the ServoStikUSBRelay plugin for more information." /> {

// path to usbrelay if necessary
</ label="Executable name", help="Full path to the usbrelay utility if necessary", order=1 />
command = "usbrelay";

// command to turn on the relay
</ label="Command relay on", help="Command to turn on the relay for 2 and 4 way games", order=2 />
command_relay_on = "HURTM_1=1";

// command to turn off the relay
</ label="Command relay off", help="Command to turn off the relay for 8 way games", order=3 />
command_relay_off = "HURTM_1=0";


// process the local config
local config=fe.get_config();

// register the callback for when games are launched
fe.add_transition_callback( "joytray_plugin_transition" );

// function to  process each game's launch
function joytray_plugin_transition( ttype, var, ttime ) {

if ( ScreenSaverActive ) return false;

switch ( ttype )  {

case Transition.ToGame:

// turn relay on for 4 way games
if (fe.game_info( Info.Control ) == "joystick (4-way),joystick (4-way)") fe.plugin_command_bg(config["command"], config["command_relay_on"] );

// turn relay on for 2 way games
else if (fe.game_info( Info.Control ) == "joystick (2-way),joystick (2-way)") fe.plugin_command_bg(config["command"], config["command_relay_on"] );

// turn relay off for 8 way games
else fe.plugin_command_bg( config["command"], config["command_relay_off"]);



return false; // must return false

« Last Edit: March 06, 2018, 12:48:19 PM by wrybread »


  • Full Member
  • ***
  • Posts: 42
    • View Profile
Re: Ultimarc Servo-Stik plugin for Linux
« Reply #1 on: March 06, 2018, 12:51:36 PM »
This method is now outdated! The author of RGBCommander released a utility that switches the ServoStik from commandline in Linux, confirmed working awesome. Once he posts it I'll update my plugin.