USBJoystickMapping

Overview

The MiST features a virtual gamepad that USB and DB9 controllers translate to, in order to standardize the many different existing gamepad layouts. It will accept devices that support HID with a default mapping, that can be overridden via the mist.ini file.

This virtual gamepad features the following:

• Directions: right, left, down, up
• A, B, Select, and Start buttons
• X, Y, L, and R buttons
• L2, R2, L3, and R3 buttons

For defining mappings, they are arranged into an array of 16 values:

right	left	down	up	A	B	SELECT	START	X	Y	L	R	L2	R2	L3	R3

The rest of the internal buttons can be used for additional functionality by binding to keyboard shortcuts (in particular X, L, and R), as described here.

Default mapping

By default all HID devices map to a gamepad with 4 directions and twelve buttons (DB9 devices have only 2 buttons):

Hardware	right	left	down	up	btn 1	btn 2	btn 3	btn 4	btn 5	btn 6	btn 7	btn 8	btn 9	btn 10	btn 11	btn 12
MiST	right	left	down	up	A	B	SELECT	START	X	Y	L	R	L2	R2	L3	R3
Hex	0x01	0x02	0x04	0x08	0x10	0x20	0x40	0x80	0x100	0x200	0x400	0x800	0x1000	0x2000	0x4000	0x8000

Custom mapping can be applied per button by configuring the corresponding value to be the hexadecimal sum of the numbers above. For example if one wanted to map "btn 7" to A + B, one would enter 0x10 + 0x20 = 0x30. (if you translate the values to binary, you will notice there is one bit per button on a 16-bit array, and e.g. 0xFFFF would press all buttons and directions at once).

mist.ini mapping

The mapping can be overidden by entering a line like the below in mist.ini, in this example we map the iBuffalo SNES pad:

joystick_remap=0583,2060,1,2,4,8,10,20,20,8,400,800,40,80

The first two numbers, 0584 and 2060 are the VID (Vendor ID) and PID (Product ID) hex codes that the devices report. These can be seen by plugging the USB controller in Windows and looking at hardware properties, or on Linux using the lsusb command.

DB9 joysticks have a virtual 00db VID and 0000 or 0001 PID codes (check in example mappings).

The next four numbers are the mapping for the directional gamepad. These act like a digital gamepad ("POV hat"), overriding any analog joystick values if pressed. The mapping used in the example above is the default:

right	left	down	up
0x01	0x02	0x04	0x08

After this are buttons (up to twelve) arranged in order that the devices reports them. The exact ordering can vary but it can be seen by plugging a USB device in Windows, looking at controller properties, and pressing buttons to see which number they correspond to.

In the mapping string from the example above we've used these values:

Hardware	btn 1	btn 2	btn 3	btn 4	btn 5	btn 6	btn 7	btn 8
Hex	0x10	0x20	0x20	0x08	0x400	0x800	0x40	0x80
MiST	A	B	B	Up	L	R	SELECT	START

This will result in the following mapping:

This provides two ways to hold the game pad for B, A buttons, and maps one extra button to "Up" for use as a jump button on several Amiga/ST games. L and R are usually not used by cores, but they're used by the OSD to activate "Pageup" and "Pagedown" when pressed with up/down while going through file selection.

OSD mapping

From firmware_220113, it's possible to create a mapping interactively in the Joystick Setup/Test OSD page. You can simply "teach" MiST to a specific mapping by pressing the appropriate button when it's asked for.

To use this feature, go to the Input Devices OSD page, then select the appropriate controller. By default, the actual mapping can be tested by pressing the buttons and check where it is mapped. Press F1 to start the learning process. Just press the button which is asked for, use F1 if there's no such button on the controller (or you don't want it to be mapped).

After all buttons are programmed, you can save the new mapping via F2 to all cores into MISTCFG.INI file. Warning! This will override all (even core-specific) mapping lines in MIST.INI. Alternatively you can choose to save the current mapping for the current core only into the [CORENAME].CFG file.

The priority of the mapping configs from the lowest to highest:

• MIST.INI
• MISTCFG.INI
• [CORENAME].CFG

---

Tutorial - creating your own mappings

The mapping is very flexible so you can experiment to find your favorite setup per gamepad, even remapping directions to buttons (and vice-versa) if you wish to do so.

At the moment up to eight sets of mappings are supported in the .ini (but more can be added if requested).

Creating your own mappings

Base Test of HID gamepad

The first step is to find out if your controller is at all recognized by the MiST. Plug it in, turn on the MiST, then open the OSD (F12 or middle MiST button on the front panel) and go to the Joystick 1 test screen.

If the gamepad is recognized (and it is not among the gamepads already known by the MiST) then it will display a raw VID and PID numbers (this is the "device ID" reported by USB HID interface of the gamepad). Write these down as they will be used for the mapping.

Next press the directions and buttons and find if any of them seem to be mapped correctly already. Below is an example where four button and directions are where we would like to have them.

Using the character positions of the "USB" information at the bottom, write a mapping for the MiST.INi using default mapping for each position (leaving the others at zero). The first two numbers are the VID/PID numbers, and the next four are the directions. Then we map two buttons (A and B) to their defaults, then skip a few buttons to set L and R to their default mappings as well:

joystick_remap=1235,ab21,1,2,4,8,10,20,0,0,0,0,400,800,0,0

If you we to use this mapping, you'll notice that in the test the buttons set at zero no longer work. (this can be handy if there is a button on the controller you'd like to ignore)

The next step is to map additional buttons to the desired MIST "virtual" button. You can check the position of any given button in the configuration string by pressing only that button:

In this example we are pressing button "X" on the gamepad but it is being recognized as Start due to its position in the reporting done by USB. The test screen tells us this is the 4th hardware button, so we need to add the mapping for "virtual X" at the right location:

joystick_remap=1235,ab21,1,2,4,8,10,20,0,100,0,0,400,800,0,0

Repeat this as required and you will have a mapping that fits your need.

Create your own mappings with Windows

VID / PID codes on Windows

To get VID and PID from Windows, you can plug the controller in Windows, then open the Device Manager and right click on the icon for the controller and select "Properties" (do not confuse it with "Game Controller settings"). Then go to the "Hardware" tab, select "HID-compliant game controller" then click the Properties button. In the windows that pops up select the "Details" tab and choose "Hardware IDs" in the drop down selection. You should have something like the below where you can read a VID and PID numbers:

These are used in the first part of the mapping. As an example let's assume we do not want to remap directions, so we'll keep the first set of mappings as the default. This string will map only the directions and disable all buttons:

joystick_remap=0583,2060,1,2,4,8

USB Buttons

Finally the last step is to map hardware buttons to the MiST virtual joystick. After the VID, PID, and four directions, each entry on the mapping string directly maps to the button number as displayed by Windows.

Go back to the Device Manager but select "Game Controller settings" this time. This brings up a menu with all your connected controllers. Choose the right one and select "Properties" to view how Windows recognized the gamepad. In this window you can press a button and the corresponding number will light up.

In the example below we press the START button on the gamepad, and can see it maps to USB button number 8:

This means that in order to map the physical START button to the START of the virtual joystick we must apply mapping to the 8th USB button. We know (from table above) that virtual gamepad START mapping is 0x80, so to assign this button we would use this string (assuming no other buttons are mapped):

joystick_remap=0583,2060,1,2,4,8,0,0,0,0,0,0,0,80

The string above will map the four directions, then skip 7 buttons, and assign the 'virtual' START button to the eight USB button. Subsequent buttons are ignored unless more values are added at the right:

Hardware	right	left	down	up	btn 1	btn 2	btn 3	btn 4	btn 5	btn 6	btn 7	btn 8	btn 9	btn 10	btn 11	btn 12
MiST	right	left	down	up								START
Hex	0x01	0x02	0x04	0x08								0x80

Using this method you can work out which USB button number corresponds to each physical button and map it to the desired MiST virtual button. It is recommended that you at least map four: A, B, SELECT, and START:

joystick_remap=0583,2060,1,2,4,8,10,20,0,0,0,0,40,80

Which corresponds to:

Hardware	right	left	down	up	btn 1	btn 2	btn 3	btn 4	btn 5	btn 6	btn 7	btn 8	btn 9	btn 10	btn 11	btn 12
MiST	right	left	down	up	A	B					SELECT	START
Hex	0x01	0x02	0x04	0x08	0x10	0x20					0x40	0x80

Combining buttons

A few keyboard shortcuts have been defined based on the virtual gamepad; out of these one of the most useful is START+SELECT to open the OSD. Let's assume you have a gamepad with many buttons and button 12 happens to be conveniently located to be used as a standalone OSD button.

To trigger the keyboard shortcut one needs to have both START and SELECT pressed. This means we need to assign both as mapping to button 12 to trigger it. This is done by summing the values of START and SELECT together, 0x40 + 0x80 = 0xC0, and assigning the value to the 12th USB button:

joystick_remap=0583,2060,1,2,4,8,10,20,0,0,0,0,40,80,0,0,0,C0

Which is in our mapping table:

Hardware	right	left	down	up	btn 1	btn 2	btn 3	btn 4	btn 5	btn 6	btn 7	btn 8	btn 9	btn 10	btn 11	btn 12
MiST	right	left	down	up	A	B					SELECT	START				SELECT + START
Hex	0x01	0x02	0x04	0x08	0x10	0x20					0x40	0x80				0xC0

Many other combinations are possible - giving you full flexibility on customizing how your HID-compatible controllers work with the MiST.

Tools

There's a Windows tool that can help creating these mappings.

Example mappings

No standard exists for the button mapping of USB joysticks and gamepads. The following examples will provide some sane default mapping useful for most MIST cores.

Currently the MIST.INI file can only support up to four mappings, so make sure to only copy the ones you need

NEOGEO-daptor
joystick_remap=04D8,F421,1,2,4,8,20,10,20,8,80,40,0,0

HORI RAP Premium VLX (2016 model)
joystick_remap=0F0D,0070,1,2,4,8,10,20,10,20,8,0,0,0,40,80

iBuffalo SNES gamepad
joystick_remap=0583,2060,1,2,4,8,10,20,100,200,400,800,40,80

Logitech F310 - SNES style button mapping
joystick_remap=046d,c216,1,2,4,8,200,20,10,100,400,800,0,0,40,80,0,0

Dragonrise SNES gamepad
joystick_remap=0079,0011,1,2,4,8,100,10,20,200,400,800,0,0,40,80

Since firmware 201006:

To map DB9 joystick port 1 BTN2 to UP for Jotego's Bubble Bobble Arcade:

[bublbblr]
joystick_remap=00db,0001,1,2,4,20,10

SNES iBuffalo - advanced examples

# 90-degree rotation of gamepad (left = "up") 
joystick_remap=0583,2060,8,4,1,2,10,20,20,8,1400,2800,40,80
# switch direction and buttons
joystick_remap=0583,2060,10,20,20,8,1,4,8,2,1400,2800,40,80