XKeysJoystickNotes

This page explains how to program X-keys switch interfaces to send joystick input for use as a selection mechanism in OptiKey.

Background

An X-keys switch interface is a USB device that pretends to be another USB device, such as a mouse, keyboard, or game controller.

To use a switch as a selection method in OptiKey, you would usually tell the switch interface to pretend to be a keyboard and follow instructions for changing the selection method.

Sometimes you might want to tell the switch interface to pretend to be a joystick. See the main wiki article on game controller / joystick input for more details on why you might want to do this and how to configure OptiKey.

The rest of this page describes how to actually program the X-keys switch interface to pretend to be a joystick.

Programming the X-keys switch interface

These instructions will use the X-keys 3-switch interface as an example. The procedure for the 12-switch interface is essentially identical.

Hardware setup

These instructions assume you are only connecting one switch to your switch interface. If you want to connect multiple switches, you may need to purchase a splitter device (for the 3-switch interface) or use multiple ports (on the 12-switch interface).

Plug your switch into the end of the switch interface. Plug the switch interface into a USB port on your computer or a USB hub (preferably a hub with an external power supply).

Installing MacroWorks 3.1

Go to the X-keys website download page, and download the MacroWorks 3.1 installer. Run the installer and follow the prompts to complete the installation.

When you first run MacroWorks with your switch interface plugged in, it will prompt you to do some setup tasks. Accept the default options and click OK before moving on.

Programming GameButton actions

1. Open MacroWorks.
2. You should see a dialog box titled Select Mode. Click on Hardware.

If you don't see this dialog box, go the Mode menu and verify that Hardware Resident Mode is selected.

3. Press the switch you want to program. This should open another window.

4. Click on the Function tab.

5. Click Show Functions.

6. Another window listing functions should appear. Click on the + next to Game Controller. Then double click on Game Button.

After you double click, the text GameButton[1,1] should appear under Press Macro Event. This indicates that the game controller button 1 should be pressed whenever you press the switch.

7. Click on the white line under Release Macro Event. Double click on Game Button in the Functions Window. You should see GameButton[1,1] appear under the Release Macro Event. We want to release button 1 when the switch released, so change the State box from 1 to 0. Your screen should look like this:

8. Close the Functions window. Click Save in the Macro Window. You've finished specifying the script. Now we need to write it to the memory of the X-keys device.

Writing to the device

1. In MacroWorks, click file and then click Write to Device.
2. Wait for the process to finish. This may take from a new seconds to a couple minutes.

Changing the PID

Finally, we need to change the PID so Windows will recognize the device as a joystick/game controller. You want to do this only AFTER writing your program to the device. Once you change the PID, you won't be able to edit your script without changing the PID back to the original PID.

1. Click on the Tools menu and then hover over Advanced. Click Endpoints/PID changer.

2. From the drop down menu, select 1223 | Joystick | Mouse | Multimedia. (For the 12 switch interface, select 1194 | Joystick | Mouse | Multimedia.) Click OK.
3. You should see messages from MacroWorks and Windows showing the one device was unplugged and a new one was plugged in. You should now be ready to use the TestControllers.exe tool and proceed with OptiKey configuration as described here.

Other hints and resources

Notes

Once you've changed the PID, a game controller should show up in the Control Panel. However, the Windows game controller properties may not correctly display your switch presses. This isn't necessarily a problem. Try with OptiKey before you assume it's not working.

Debugging

If your switch interface is not working or is working intermittently, you can try:

• Make sure you're programming in hardware mode.
• Exit MacroWorks after the programming is complete. (Right click on the icon on the taskbar and click exit from the menu.) If this works, be sure to remove MacroWorks from your startup programs list so it doesn't restart automatically.
• If you're using a USB hub, instead plug directly into the computer. If this isn't possible, try a USB hub with an external power supply.
• Update the firmware of your X-keys device.
• Contact tech support at P.I. Engineering. They are generally very helpful and responsive.