PADMAP.TXT Format and the reference gamepad - Wuerfel21/usbnew GitHub Wiki

PADMAP.TXT File format

When implemented in an application, gamepad button maps can be defined using a PADMAP.TXT file in the root of your SD card.

# hashes start comments
<app ID> <device ID> <button 1> <button 2> ...

app ID is the name of the application the rule should apply to or * to apply as a default in all applications. device ID is the VID and PID of the device, as a single block of 8 uppercase hex digits. The buttons are decimal numbers indicating which device buttons are mapped to the virtual buttons in order. The particular meaning of the buttons is up to the application, but the first 10 buttons roughly correspond to the reference gamepad (see below).

Example of rules:

# Application  VID+PID   N  E  S  W L1 R1 L2 R2 Sl St

      *       0E6F1112   4  1  2  3  0  0  0  0  9 10 # NeoGeo mini
      *       1C590026   1  2  3  4  5  6  0  0  7  8 # THE GAMEPAD
   megayume   0F0D00C1   1  8  2  3  4  7  0  0  9 10 # RetroBit 6-button controller (special map for MegaYume)

The Reference Gamepad

This is the reference gamepad:

image

It has the following 10 buttons, in this order:

  1. A northern face button
  2. An eastern face button
  3. A southern face button
  4. A western face button
  5. An upper left shoulder button
  6. An upper right shoulder button
  7. A lower left shoulder button
  8. A lower right shoulder button
  9. A "Select" button
  10. A "Start" button

This is the layout of the average USB controller. Many conform to it exactly. Generic (appid *) PADMAP rules should translate from a divergent controller's button numbers to this standard layout.

On positional mapping

One's first instinct might be to map the "A" button on the controller to the virtual "A" button in your software. For various reasons, this is a bad idea and thus generic PADMAP and the reference gamepad concept use location instead of button labels to encourage better mappings.

The most comfortable pair of buttons to reach on a diamond-layout gamepad is West/South. (i.e. 3/4). Unlike South/East and West/North, the buttons are colinear with your finger's natural positon. The same could be said about North/East, but, especially on most designs with analog sticks, this is generally a slightly less comfortable resting place.

image image

So by using positional mapping, the correct "feel" of the controls is maintained at the cost of minor confusion at button prompts (which with emulated games, will come up, anyways)

(Note that the non-colinear pairs of course have their place, too. South/East are almost universally used as menu confirm/cancel because they require more deliberate action)

Detailed PADMAP specification

If you want to implement PADMAP parsing from scratch, this is the full specification:

  • Data is stored in a file called PADMAP.TXT in the SD root directory
  • Each line (terminated by CR or LF or EOF) is one "rule"
  • Each line may have any amount of leading and trailing whitespace (space or tab)
  • Empty lines are to be ignored.
  • A line starting with a # is a comment.
  • The first word determines which application it applies to. "*" indicates a generic rule ("*abcd" does not!)
    • A normal application name should only contain ASCII letters and numbers.
  • Irrelevant app-specific rules should be treated as comments (not parsed) to allow special extended syntax
  • The next word should be 8 hex digits (uppercase only) containing the device ID (VID/PID)
  • Following from that is a series of decimal numbers defining which HID button (1 based) to map to each virtual button. Zero means to not map the button. A # can also start a comment at this point.
  • Any excess buttons are to be ignored, any missing buttons to be filled with zero
  • The first 10 buttons are standard and correspond to the common-ish layout of most HID controllers. See above for more detail
  • An app-specific rule can override a generic rule (regardless of position in the file).
  • A generic rule should not override preset rules compiled into the application
  • An application should be able to load at least 16 rules (~256 bytes of buffer after parsing) on top of any built-in ones (not counting overridden rules). Excess rules should be discarded, but overrides can still happen when the buffer is full.

Technically valid rules:

coolfuture asdf lmao # Extended format data for "coolfuture", should not be parsed
 * 12345678 # Empty rule
 * 87654321 1 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 # Over-long rule
   # comment can start after leading whitespace!

Invalid rules:

* # Rule without ID
* 11223344 -1 # negative number
* 55667788 asdf lmao # Extended format data in generic rule
* abcdef00 # lowercase hex digits!
⚠️ **GitHub.com Fallback** ⚠️