HID Remapper Manual
What is HID Remapper
HID Remapper is a programmable adapter for USB input devices with a wide range of applications including desktop computing and gaming accessibility. Instead of plugging input devices like mice, keyboards or game controllers directly into your computer or game console, you plug HID Remapper into your computer and you plug the input devices into HID Remapper. Then you can configure it to take the inputs coming from the device that's plugged into it and map them to other inputs, similar or very different, that will be sent to your computer. HID Remapper can act as a mouse, keyboard or a game controller. You can use it for simple things like button remapping or changing mouse sensitivity, but you can also use it to completely change the types of inputs that are generated: for example you can use it to make a joystick work as a mouse or make a keyboard work as a game controller.
It has some functionality built in, like basic remapping, layers and macros, and it can also be extended to do pretty much anything using a system of expressions, which are little programs that let you define custom behaviors.
HID Remapper works entirely in hardware, no special software has to be running on your computer. Configuration is done from a web browser and it is saved on the device.
It can be made using off-the-shelf microcontroller boards like the Raspberry Pi Pico.
The entire project is open source, both the firmware and the (optional) custom hardware.
In addition to the remapping functionality, it can overclock the polling rate on certain devices up to 1000 Hz.
There's a separate Bluetooth version of HID Remapper which translates Bluetooth inputs to USB.
Where to get help
This manual is the main user documentation for HID Remapper. The GitHub repository contains information on some of the more technical aspects. The project's YouTube channel has some videos demonstrating its use in various scenarios.
If you think something is not working correctly or you have any questions, please file an issue on GitHub or email me at jfedor@jfedor.org.
Why in hardware
A lot of what HID Remapper can do can also be done in software, without any additional hardware. Devices like mice and trackballs often come with manufacturer's software that lets you remap the buttons or define macros and there are also generic third party utilities that let you do similar things with devices from any manufacturer.
Doing it in hardware does have certain advantages though. For example if you use multiple computers with different operating systems, a utility like this might be available for all of them, but it probably won't be the same utility, so you would have to do the configuration multiple times. Or maybe you want to remap inputs on a work laptop and the IT department won't let you install any unapproved software. Finally, maybe your target system is something like a Chromebook or a Nintendo Switch and it simply doesn't have the possibility of doing it in software.
What you can plug into HID Remapper
HID Remapper can receive inputs from several types of devices, primarily standard USB input devices, meaning devices implementing the HID class as defined by the USB specification. This includes almost all mice, keyboards, most “left hand” input devices like 3D mice and media editing tools, and many game controllers like gamepads, joysticks, steering wheels and pedals.
Wireless receivers are supported and multiple devices can be connected at the same time using a USB hub (with different mappings for each device if desired).
It also supports Xbox One/Series controllers, including the Xbox Adaptive Controller, but not Xbox 360 controllers. If your controller has multiple modes, try them all to see if one works.
Additionally, HID Remapper can take inputs from MIDI controllers like keyboards if they connect over USB. You will probably want to use the Monitor tab to map the MIDI inputs because they are not listed along with the regular inputs when you create a mapping.
Besides USB inputs, you can also wire buttons or switches directly to GPIO pins on the microcontroller board running the HID Remapper firmware and map them as you would any other key or button.
HID Remapper custom board v6 has 3.5mm jacks wired to GPIO pins so you can use off-the-shelf adaptive buttons with a 3.5mm plug without the need to solder anything.
HID Remapper custom board v8 has a single 3.5mm jack that can take analog inputs from joysticks. It can be used to adapt joysticks with a 3.5mm plug to USB, for use with the Hori Flex controller, or simply a PC.
Please note that there's no guarantee that any specific device will work even if it belongs to one of the device classes mentioned above. In some cases the device doesn't work because of an issue with its HID report descriptor. Those can often be worked around by defining custom usages.
What you can plug HID Remapper into
HID Remapper acts as a standard USB input device, either a mouse/keyboard combo or one of several game controller types.
When in keyboard and mouse mode, it's compatible with any host that works with regular keyboards and mice, including computers running Windows, macOS, Linux and ChromeOS. If your mobile device like phone or tablet works with regular USB keyboards and mice, it will also work with HID Remapper. HID Remapper can act as a boot protocol keyboard, so it should work in older BIOSes and bootloaders.
When in one of the game controller modes, HID Remapper generally works with all the operating systems mentioned above, though level of support and button mapping correctness may vary depending on specific software used.
When in Switch gamepad mode, HID Remapper can be plugged into a Nintendo Switch in both portable and docked modes.
In general it does not work out of the box with other modern era consoles, though it can be made to work with additional effort (see Console compatibility section).
Compatibility with retro/classic replica consoles will depend on whether your particular console works with all standard USB controllers or expects a specific one. Try all the modes.
Where to get or how to make an HID Remapper
Where to get or how to make an HID Remapper
There are three main ways to get or make your own HID Remapper. You can either buy the Feather RP2040 USB Host board from Adafruit, make it yourself using a Raspberry Pi Pico (or two), or you can use the provided files to manufacture a custom board at JLCPCB or a similar service. The functionality is the same in all cases (with some exceptions).
If you get the Feather RP2040 USB Host board from Adafruit, the device is ready to use, you just need to flash it with the right firmware (remapper_feather.uf2). Hold the Boot button on the board, then press the Reset button. A USB drive should appear on your computer. Copy the UF2 file to that drive. That's it.
See the HARDWARE.md document on the GitHub repository for details on how to make the Pico variants of the device.
See the Custom boards section for details on the custom board option.
Accessibility applications
HID Remapper is a universal tool not limited to any specific use case, but its flexibility makes it well suited for a wide range of accessibility applications, both in general desktop use and gaming in particular. It can be used to make input devices work outside their primary role, for example to make a joystick work as a mouse, or a touchpad work as a joystick. It can be used to combine several input devices and make them work as one gamepad. In addition to basic remapping, it can add toggle functionality to buttons, it can make one button work as a combination of buttons, it can make a button send joystick or trigger inputs, and it can do macros and layers.
HID Remapper can be used to add external buttons or switches to your setup, by wiring them to GPIO pins on the microcontroller board. HID Remapper custom board v6 can be used as a full blown accessibility controller out of the box, with 3.5mm jack inputs similar to the ones on the Xbox Adaptive Controller or the Hori Flex.
HID Remapper as an adaptive controller for Nintendo Switch
It can also be used together with existing accessibility controllers like the Xbox Adaptive Controller or the Hori Flex, which have USB inputs, but are very limited in what devices you can plug into those inputs. By using HID Remapper as an adapter, you can take any USB input device and make it compatible with the XAC or the Flex, and that includes devices like keyboards or mice, that weren't even originally meant to be used as a gamepad.
Plug any USB device into the Xbox Adaptive Controller
HID Remapper can be plugged into the Xbox Adaptive Controller, but you can also plug the Xbox Adaptive Controller into HID Remapper and this way make it compatible with the Nintendo Switch.
Xbox Adaptive Controller on the Nintendo Switch
HID Remapper custom board v7 is designed to add USB inputs to the PlayStation Access controller. The Access controller doesn't have USB inputs on its own, but it does have 3.5mm jack inputs that support external buttons and joysticks. HID Remapper custom board v7 has 3.5mm outputs that can be wired to inputs on the Access controller and it can be configured to send inputs coming from USB devices to those outputs.
Use any USB joystick with the PlayStation Access controller
Console compatibility
While HID Remapper can emulate several types of game controllers, unfortunately that doesn't mean that it just works on all modern era game consoles.
The only console it works with out of the box with no caveats is the Nintendo Switch, just select the Switch gamepad emulated device type and that's it.
Keyboard adapter for Nintendo Switch
If you're using the Hori Flex controller with the Switch and you want to add more inputs to it coming from USB devices that are not directly compatible with the Flex, you can use HID Remapper to adapt any USB input device and make it compatible. Select the XAC/Flex compatible emulated device type, plug your input device into HID Remapper and plug HID Remapper into one of the USB input ports on the Hori Flex. Keep in mind the Flex controller can only receive analog stick inputs over USB, not buttons, and that each port is limited to a single stick.
Analog sticks with the Hori Flex
If you don't have a Hori Flex setup yet, but are considering one, also consider just using HID Remapper custom board v6 instead.
On the PlayStation 5, there are a few ways to use HID Remapper. You can use an adapter like the Brook Wingman FGC2 to make HID Remapper compatible with the PS5. Select PS4 arcade stick emulated device type, plug your HID Remapper into the FGC2 adapter and plug that into the PS5. This will work in all PS5 games.
Alternatively, if you only want to play PS5 fighting games, you can plug HID Remapper directly into your PS5, but you're going to need an additional device like the Mayflash Magicboots PS4 dongle to satisfy the console's authentication requirements. Select the PS4 arcade stick emulated device type, plug a USB hub into HID Remapper and plug the authentication device and any other USB devices you want to use into the hub. In addition to dongles like the Magicboots, licensed PS4 arcade sticks can also be used (you can then use them for both their inputs and for the authentication bits that they provide). You cannot use a DualShock or DualSense controller as an authentication device.
Use a keyboard to play SF6 & Tekken 8 on PS5
Additionally, if you're using a PlayStation Access controller with your PS5, you can use HID Remapper custom board v7 to adapt USB input devices to 3.5mm jack signal compatible with the Access controller.
For Xbox consoles, it's possible that some adapters can be used to make HID Remapper compatible with them, but I have not personally tested that.
If you're using an Xbox Adaptive Controller as part of your setup, you can use HID Remapper to adapt USB devices that are not directly compatible with the XAC and make them compatible. Select the XAC/Flex compatible emulated device type, plug your USB device into HID Remapper and plug HID Remapper into one of the USB input ports on the Xbox Adaptive Controller. The XAC can receive all types of inputs over its USB input ports, except for analog triggers: the triggers will only work as on/off buttons. Keep in mind that the input labels that you configure on your HID Remapper will be correct if you plug it into the USB input port on the left side of the Xbox Adaptive Controller. It can still work with the USB port on the right side, but some inputs will be swapped around.
See the Emulating game controllers section for some tips on how to configure mappings for game controller outputs.
Configuration overview
HID Remapper configuration website tour
HID Remapper is configured using a website, so you don't have to install any special software on your computer. Because it uses WebHID to connect to the device, it only works in the desktop version of Chrome. Other Chrome-based browsers like Edge and Opera might also work.
The configuration is stored on the device so after you finish configuring your HID Remapper, you can unplug it from the computer you used for setup and plug it into another one.
At the top of the configuration website, you'll find three buttons, Open device, Load from device and Save to device.
When you click the Open device button, the browser will ask you to pick the device you want to connect to.
Being connected to your HID Remapper means that you can now load the configuration from it, save the configuration to it, and also that if you have a device with some non-standard inputs plugged into your HID Remapper, those inputs should now show up on the list when you set the input on a mapping.
Clicking Load from device replaces the configuration you see on the screen with the configuration that is currently stored on your HID Remapper.
If you make any changes to the configuration, they are not active until you click the Save to device button, which puts the configuration you see on the screen on your HID Remapper.
Unless you're starting from scratch, a typical session with the configuration website will consist of connecting to your HID Remapper, loading the configuration from it, making some changes, saving them to the device, testing them and possibly repeating the latter steps until it behaves the way you want.
Certain configuration changes like the emulated device type require a device restart so you will have to unplug and replug your HID Remapper for the new setting to become active.
Configuration can be exported from the website to a JSON file that can later be imported. You can use those files as a backup or as a convenient way of having multiple configurations and switching between them without having to start from scratch.
HID Remapper configuration export/import
If you can't or don't want to use the browser-based configuration tool, there are also command-line tools on the GitHub repository that work with the same JSON format as the files used by the configuration website.
The next few sections describe different parts of the configuration website and the ways you can configure HID Remapper. The website also includes many example configurations. Some of them are simple and only serve to demonstrate a particular feature, while others could conceivably be used as-is in real life, or at least as a starting point.
Mappings
Mappings are the primary way you configure HID Remapper. They are the rules that tell HID Remapper how to translate the inputs that it's receiving from the devices that are plugged into it. Every mapping has an input and an output. Simplifying things a bit, whenever HID Remapper receives some input, it looks for a mapping with that input, takes the output of that mapping and sends it to the PC that it's plugged into.
You may have noticed that even with no mappings defined, in the default configuration, your mouse and keyboard still work when you plug them into your HID Remapper. That's because by default the Unmapped inputs passthrough option is enabled. See the dedicated section for more details on that option.
You can add mappings by clicking the Add mapping button at the bottom, and you can delete mappings by clicking the x button to the left of each mapping. The order in which the mappings are defined doesn't matter.
If you want the left button on your mouse to work as the right mouse button, create a mapping with Left button as the input and Right button as the output.
Similarly to keys or buttons, you can also remap axes. For example if you want horizontal mouse movements to be mapped to vertical cursor movements on the computer, add a mapping with the input set to Cursor X and the output set to Cursor Y.
If you want to change mouse sensitivity, or cursor speed, you can use the scaling part of a mapping. By default it is set to 1, but you could create mappings with the same axes for inputs and outputs and for example set scaling to 2 to make the cursor move twice as fast, or set it to -1 to invert the direction of the movement. (Usually it's best to first increase the CPI on the device if possible as that will give you better precision.)
You can have a mapping that has a button or a key as input and an axis as output. For example if you add a mapping with Right arrow as input and Cursor X as output, it will make the cursor move right when the right arrow is held on the keyboard. If you add another mapping with Left arrow as input and scaling set to -1, it will make the cursor move left when the left arrow key is held.
It is possible to make a mapping that has mouse cursor movement or scroll as the input and a key or button as the output. This will result in the key being pressed whenever that input is nonzero (mouse is moving or scrolling). You can have it send a different key when the mouse is moving to the right and to the left, or scrolling up and down. Just create two mappings with the input set to, say, V scroll and set the scaling parameter to 1 on the first one and to -1 on the second one.
What outputs are available depends on the emulated device type chosen. If it's set to Mouse and keyboard, you will be able to send mouse movement and buttons and keyboard keys. If you set it to one of the gamepad device types, you will be able to choose buttons and joystick and triggers. Note that the input device type is independent from the output device type. You can of course map gamepad buttons to gamepad buttons or joystick axes to joystick axes, but you can also map keyboard keys or mouse buttons to gamepad buttons if you want (and vice versa).
You can have more than one mapping with a certain input and you can have more than one mapping with a certain output.
When you have two mappings with X as their inputs, one with Y as the output and one with Z as the output, whenever you press X, both Y and Z will be pressed. This can be used for simple button combinations. For example if you wanted to make your right mouse button work as Ctrl-C, you could create two mappings, one with Right button as input and Left Control as output, and another with Right button as input and C as output.
When you have multiple mappings with the same output, you just have alternative ways of sending that key or button. It's as if your keyboard had two X keys.
The following sections discuss a few more advanced ways in which mappings can be used beyond the basic map-X-to-Y.
Sticky
The sticky flag on a mapping lets you add toggle functionality to keys or buttons. When used with mouse buttons, it's sometimes called drag-lock. The way it works is if you have a mapping with X set as the input and Y set as the output, and the sticky flag is enabled, then whenever you press and release X, from the computer's point of view Y remains pressed until you press X again. This is useful if you don't want to have to keep holding a button when dragging something with your mouse, or if some game wants you to keep holding a button for a long time.
Add drag-lock to any mouse with HID Remapper
Drag-lock using only one button
Tap-hold
Tap and hold flags on a mapping are a way of assigning different functions to the same key or button, depending on whether it was pressed and released quickly (tapped), or held for a longer time.
For example, you might want to map your Caps Lock key as Control, but still want to be able to toggle Caps Lock on and off. Because Control is typically used as a modifier, in other words it's pressed and held while you press some other key, we can get away with mapping a quick tap of the Caps Lock key as Caps Lock and a longer hold of the Caps Lock key as Control.
To do that, you would create two mappings, first with Caps Lock as input and as output, and the tap flag enabled, and second with Caps Lock as input, Left Control as output, and the hold flag enabled.
How short does a tap have to be to be considered a tap and not a hold? This is configurable using the Tap-hold threshold setting in the Settings tab. By default it's set to 200 milliseconds.
Tap-hold functionality can be used together with the sticky flag. For example you could make it so that the Shift key works as a toggle when tapped (meaning it stays pressed until it's tapped again), but also behaves as a normal Shift key when it's held. This way you could get a Caps Lock-like functionality from the Shift key and use the Caps Lock key for something else. To do that, create two mappings with Left Shift (or Right Shift) as both the input and the output, and enable the tap and sticky flags on the first mapping and the hold flag on the second mapping.
Layers
Layers are another mechanism for assigning multiple functions to the same keys. They are effectively separate sets of mappings that you can switch between on a temporary or semi-permanent basis. It might sound familiar if you ever used a custom ergo keyboard.
It works as follows. Every mapping has a set of layers on which it is enabled. A special mapping can be added with some button as input and Layer X as output. This means that when that button is pressed, layer X is active and therefore mappings from layer X are applied. If no layer is explicitly activated, layer 0 is active. More than one layer can be active at the same time. This mechanism has many useful applications, from completely separate keyboard layouts to things like a "sniper button" on a mouse - increasing precision when a certain button is held.
Or you could make it so that while the middle mouse button is held, moving the mouse scrolls instead of moving the cursor. (To invert the scrolling direction, set the scaling parameter to a negative value.)
If you want a layer to be active while a key or button is pressed, just make a regular mapping as described above. If you want the key to activate a layer until it is pressed again, enable the sticky flag on that mapping. If you also want to use the same key for some other function, you can additionally enable the tap flag on the layer activating mapping and then create another mapping with the same key as input and the hold flag enabled.
Macros
Sometimes you want a certain button to send multiple outputs, not at the same time, but one after another, for example to input a special character by typing something like Alt-0165 or to emulate a double click. You can do that with the macros feature. Each macro is defined as a list of steps that will be sent one after another. Every step can consist of multiple keys or buttons, for example you can have a macro that looks like this: Left Shift+H, E, L, Nothing, L, O that will type the string "Hello" or you can have a macro that looks like this: Left Alt+Numpad 0, Left Alt+Numpad 1, Left Alt+Numpad 6, Left Alt+Numpad 5 that will enter the yen symbol (on some systems).
Or, to emulate a double-click, you could define a macro that looks like this: Left button, Nothing, Left button. The Nothing part is necessary for the computer to register a button-up event, otherwise the first macro would type "Helo" and the last one would just work as a single click. The inputs that are on the same row (separated with "+" in the short form) are sent together in the same step, while consecutive rows (separated with "," in the short form) are sent one after another.
To make a button send a certain macro, add a mapping with that button as input and with Macro X as output.
Every step (row) of a macro is held for a duration defined by the Macro step duration setting in the Settings tab. By default it's set to 1 millisecond. This works fine for macros that are meant to enter some text, but if your macro performs mouse clicks or presses a sequence of gamepad buttons that are meant to execute a certain action in a game, you might find it necessary to make the macro step longer. Currently this setting is shared between all macros and the maximum step duration is 256 milliseconds.
If you need different step lengths for your macros, you can try to work around this limitation by setting the macro step duration to the greatest common divisor of the desired step lengths and then making duplicate rows in the macros.
Per-device mappings
HID Remapper: per-device mappings
HID Remapper can take inputs from multiple devices at the same time if you use an external USB hub or a variant with a hub built in. By default, the mappings you define apply to all the devices that are plugged into your HID Remapper. Often you don't have to worry about it, for example if you plug in a mouse and a keyboard and define some mappings that apply to mouse inputs and others that apply to keyboard inputs, even though technically they will all be applied to both devices, it doesn't matter because your mouse doesn't send keyboard inputs and your keyboard doesn't send mouse inputs.
But in some situations you might have multiple devices connected that send the same kinds of inputs, and you might want them to be mapped differently. For example you could connect two identical joysticks and might want one of them to work as the left analog stick on a gamepad and the other to work as the right analog stick. This is possible with per-device, or more accurately, per-port mappings.
When you click on the input part of a mapping and you get a list of all the possible things that you can map, at the top there's a dropdown labeled Port. By default it's set to all, which makes the mapping apply to all devices plugged into your HID Remapper. You can change it to a certain port number and then this mapping will only be applied to the device plugged into that specific hub port. If you're not sure which port is which, the Monitor tab will show the port number next to the inputs (see the Monitor section for details).
Coming back to the joystick example, we could create four mappings in total to achieve the desired result. First mapping would have Left stick X as input, Left stick X as output and the port number set to 1. Second mapping would have Left stick Y as input, Left stick Y as output and the port again set to 1. Then a third mapping would have Left stick X as input and Right stick X as output with the port set to 2. And the fourth mapping would have Left stick Y as input, Right stick Y as output and the port again set to 2. This would make the joystick plugged into port 1 work as the left analog stick and the joystick plugged into port 2 work as the right analog stick.
Unmapped inputs passthrough
HID Remapper: Unmapped inputs passthrough
Often you only want to remap one or two keys and want the rest to retain their normal functions. It would be inconvenient to have to define mappings for all the other keys that would just map each key to itself. Fortunately, that's not necessary. As you may have noticed, if you just plug a mouse or a keyboard into HID Remapper and don't define any mappings, with the default configuration it will just work as if all the inputs were passed to the host transparently. That is because by default the Unmapped inputs passthrough option is enabled.
When this option is enabled, HID Remapper goes through all the inputs that it's capable of sending to the computer, for example all the keys on a keyboard, and for every key it checks if there's an explicit mapping that has that key as the input.
If it doesn't find one, it internally creates a mapping with that key as the input, and the same key as the output. It only does this internally, so you won't see these mappings when you load the configuration from your HID Remapper.
The setting can be enabled separately for each layer and HID Remapper considers the layers on which the user-defined mappings are active when deciding whether to add the automatic passthrough mappings. If there's a mapping that maps the X key on layer 0, but not on layer 1, and Unmapped inputs passthrough is enabled on layer 1, then HID Remapper will create the passthrough mapping on layer 1. However, when using per-port mappings, it is enough for an input to be mapped on any hub port for it to be considered mapped.
Even with the Unmapped inputs passthrough option enabled, you can of course still unmap certain keys if you don't want them to keep their default function. All you have to do is create a mapping with that key set as input and Nothing set as output.
Equivalent configurations can be achieved by enabling the Unmapped inputs passthrough setting and then unmapping certain keys or buttons, or by disabling the setting and then mapping all the keys that you want to keep their default functions to themselves. Which option is more convenient will probably depend on whether there's more keys that you want to remap than ones that you want to keep their default function.
Keep in mind that HID Remapper can only send the kinds of inputs that exist in the currently selected emulated device type. If the emulated device type is set to Mouse and keyboard and you plug a gamepad into your HID Remapper, then even though the Unmapped inputs passthrough setting is enabled, the joysticks and triggers on the gamepad will not be passed through transparently. You would have to set the emulated device type to one of the gamepad types, and then of course if you plug in a keyboard, HID Remapper will no longer pass the keyboard inputs transparently to the computer.
Emulating game controllers
HID Remapper can act as several types of game controllers. Mapping things to gamepad outputs is generally the same as when emulating a mouse or a keyboard, but there are a few aspects specific to buttons, joysticks and triggers on a game controller.
One thing to keep in mind is that if you have the emulated device type set to a certain game controller like the Switch gamepad and you define a set of mappings that map some keys to buttons on this game controller, and then you change the emulated device type to some other game controller, like the Stadia controller, the outputs will change in a way that is perhaps unexpected. Because there is no one convention for button semantics on a game controller, button 3 might be a different button on each controller type. The outputs on mappings keep their internal hex codes (usages), so you might have to re-do the outputs on your mappings when changing emulated controller types.
For the same reason, when you plug different controller types into HID Remapper, buttons that have the same logical role like the south face button, or the right trigger button, might show up as different codes. Unfortunately this is something that the HID specification doesn't really cover and different hardware manufacturers chose different conventions.
When mapping joystick axes, simple one-to-one mappings work as usual. If you just want to map the right analog stick to work as the left analog stick, all you have to do is create two mappings, one mapping Right stick X to Left stick X and another mapping Right stick Y to Left stick Y.
If you want to map keys or buttons to act as analog sticks, you can do it using the scaling parameter on mappings. All you need to know is that internally, the joystick axis positions are represented by numbers going from 0 to 255 and that left is 0, right is 255, up is 0 and down is 255. Neutral position is 128 on both axes. So for example if you wanted to map the WASD keys to work as the left analog stick, you could make four mappings, first mapping W to Left stick Y with scaling set to 0, second mapping A to Left stick X with scaling set to 0, third mapping S to Left stick Y with scaling set to 255 and fourth mapping D to Left stick X with scaling set to 255.
Using the same mechanism, if you wanted to map some key to actuate the left stick 50% to the right, you could set the scaling parameter to 192, which is halfway between the neutral position (128) and the fully to the right position (255).
It's similar for the analog triggers, they go from 0 when not pressed to 255 when fully pressed.
When it comes to the d-pad, even though its internal representation is different, it is exposed as four buttons that can be mapped separately, on both the input and the output side.
Keep in mind that it is not possible to send both left and right or up and down at the same time. If you define mappings and press buttons that would result in simultaneous opposing cardinal directions being pressed, HID Remapper will resolve this situation by not sending either of the directions. This is known as neutral SOCD resolution in fighting game context. If you want your d-pad to work according to some other rules, you can do that using expressions.
HID Remapper generally lets you map anything to anything, so you might wonder if it can map a mouse to an analog stick on a game controller. It can, and you will find an example configuration that does that in the Examples tab, just keep in mind that because mouse and joystick are a fundamentally different type of input, there is no one correct or obvious way to do it. Depending on what you're trying to achieve or what game you want to play, you may have to adjust the parameters of this mapping.
For most mappings that deal with analog stick axes that are not simple one-to-one mappings, you will have to use expressions. This way you can do things like apply dead zones and perhaps even sensitivity curves.
Monitor
When creating a mapping and setting its output, you get an exhaustive list of outputs that are possible. It contains all the things that HID Remapper can send to the computer given the currently selected emulated device type.
But when it comes to inputs, there can be no exhaustive list because in theory you can connect any type of device to your HID Remapper and it can send any inputs, some of which might even be vendor-specific and not appear in any specification. The list of inputs that you get contains all the standard mouse and keyboard inputs and if you change the Input labels setting to gamepad, also some game controller inputs.
If you're currently connected to an HID Remapper and a device is plugged into it that can send inputs that don't appear on the list, they will be listed below all the standard mouse and keyboard inputs. Unfortunately they will appear as hex codes and will not have human readable labels. So while it is possible to map them, it may be hard to figure out which code corresponds to what physical input on your device.
Fortunately the Monitor tab can help with this. If you are connected to your HID Remapper and a device with unobvious inputs is plugged into it, when you go to the Monitor tab and start pressing buttons, moving joysticks, or manipulate the device in other ways, you should see the inputs that it generates. If the input is known to HID Remapper, it will get a human readable label. If it's not, it will only get a hex code. But because you can see which input generates which hex code, you can now map it. For inputs more complex than just keys or buttons, you will also see associated values. This can be useful if you need to know which position of a certain lever, stick or knob corresponds to what value or if you need to know the minimum and maximum values that it generates.
You could make note of the hex code corresponding to the input that you want to map, but there's also an easier way. Next to each entry in the Monitor tab there's a little "+" button that creates a mapping with that input set as the input. You can then set the output to complete the mapping.
If you have a USB hub plugged into your HID Remapper, or if you're using a variant with a built-in hub, you will also see port numbers next to the entries in the Monitor tab. You can use these numbers to set up port-specific mappings (see the Per-device mappings section).
Custom usages
DualSense touchpad inputs with HID Remapper custom usages
This is an advanced feature that you shouldn't have to use in most cases.
The way USB input devices work is that every time they have something to report, for example when you press a button or move a joystick, they send some bits to the computer. But the format of those bits is not fixed, every device is free to define it, within certain rules. Because every device can use a different format, when you first plug a device in, it declares its format in something called the HID report descriptor. That's how a computer, or indeed HID Remapper, knows how to interpret the data coming from the device. The descriptor may go something like "the first byte is the horizontal mouse movement, the second byte is vertical mouse movement, the third byte is mouse buttons" and so on.
But on some devices, their report descriptor doesn't describe the data format properly or fully. Some things might be missing or some parts of the reported data might be described incorrectly.
For example, on the PlayStation 5 controller, all the buttons, joysticks and triggers are described correctly, but the touchpad and motion control data isn't. The relevant bits are still sent over USB, but the report descriptor doesn't tell us where exactly to find them. On other devices, a certain field might be specified in the descriptor, but it might be incorrectly flagged as a relative input, when it is in fact an absolute input.
These devices still work in their intended use scenarios because the system they're normally connected to doesn't rely on the report descriptor to know where in the reported data certain fields are. For example, a PlayStation 5 console doesn't need to read the report descriptor of the DualSense controller, it has the relevant information hardcoded in its system software. Other devices might have that information hardcoded in their device specific drivers that are required to make them work on Windows or other operating systems.
But HID Remapper is a generic tool that is meant to work with any USB input device so if a device doesn't declare its data fields properly, we are left with some or all of its input not functioning.
The custom usage mechanism is a way of providing HID Remapper with that missing or corrected information. To make use of it, you have to know where in the report the data for the missing inputs is located and how many bits it uses. The details are beyond the scope of this document, typically you would capture some of the raw data coming from the device using a tool like Wireshark, press the buttons in question or manipulate the device in some other way and try to figure out which bits are changing and in what way. After you figure this out you can add a custom usage for that input in the Settings tab.
Capture USB traffic with Wireshark
Every custom usage has the following fields: Vendor ID, Product ID, Interface, Report ID, Relative flag, Signed flag, Usage, Size and Position.
Size and Position are specified in bits. Position starts at zero. For example if you know that a certain joystick axis is sent in the third byte of the input report, you would set Position to 16 and Size to 8.
Relative inputs are used when the device reports a change in position (delta), like a regular mouse. Absolute (non-relative) inputs are when the device reports the position itself, like a joystick. This is something manufacturers of non-standard devices often get wrong.
Signed just determines if the value can go below zero. A signed 8-bit value has a range from -128 to 127, an unsigned 8-bit value has a range from 0 to 255.
Usage is the hex code that our custom defined input will be seen as. It can be something that already exists in the device's report descriptor, then it will be redefined, or it can be a new code. It can be a well known code that exists in the HID specification or it can be completely made up. In any case, this will be what shows up in the Monitor tab and what you will then map.
If the device uses report IDs in its reports, then Report ID has to be set correctly. If the device doesn't use report IDs, set it to zero.
Vendor ID, Product ID and Interface can either be set to values correct for your device or they can be set to zero, then this custom usage will apply to all interfaces on all devices.
If you want to delete a certain usage (because it interferes with another occurrence of the same usage or just spams the Monitor tab), you can do it by defining a custom usage with the Size field set to zero.
Custom usages are applied when the device is plugged into HID Remapper so if you make changes, you have to either unplug and replug the device or unplug and replug HID Remapper.
Expressions
Simple things should be simple, complex things should be possible. In HID Remapper, basic A-to-B mappings cover the first part. Additional mapping features like scaling, layers and sticky/tap/hold flags try to push a few more use cases into the "simple" category, but they cannot handle every possible scenario. If you want your outputs to depend on the state of multiple inputs in some non-trivial manner, if you want your outputs to be time-dependent, like a turbo feature on a game controller, if you want to apply smoothing to your mouse inputs, or do anything else beyond what the basic mapping system will allow, you will need to implement the logic yourself.
You could of course modify HID Remapper's source code and compile your own custom build of the firmware, and it might be the correct choice, depending on what you're trying to do.
Compile custom HID Remapper firmware using only a web browser
But there is another option. HID Remapper has a built-in expression system that is meant to allow some level of custom logic through configuration, without resorting to custom builds of the firmware.
Expressions are essentially little programs in a special programming language. From inside these expressions you can fetch input states coming from the devices plugged into HID Remapper, perform some kind of logic or arithmetic and then use the results of this computation as inputs in regular mappings.
There are two ways this can be done. Every expression can have a result, and you can set the input of a mapping to, say, Expression 1. Expressions can also store values in registers, which are like variables in other programming languages, and you can set the input of a mapping to, say, Register 1. In addition to being used in mappings, registers are also a way of storing values between subsequent expression executions.
Expressions are executed once every millisecond, regardless of whether any new inputs arrived from the devices connected to HID Remapper, so they can perform actions on their own, based on time or previous state. For example, you could write an expression that implements a mouse jiggler, moving the cursor every few seconds with no interaction from the user.
For details on expression syntax and what exactly they can do, see the EXPRESSIONS.md document on the project's GitHub repository.
Firmware updates
How to update HID Remapper firmware
From time to time, new versions of HID Remapper firmware are released. They typically contain bug fixes and occasionally new features.
Sometimes the changes are minor and the configuration website remains compatible with both the latest firmware and the previous version. In other cases, if there are changes in the internal protocol used between the website and the device, the website will only be compatible with the latest version.
In the latter situation, when you go to the configuration website and try to connect to your device, it will tell you that you don't have the latest firmware on your HID Remapper. The message will have a link to a version of the configuration website that is compatible with your current firmware. You can either just continue using the older version of the website with your HID Remapper if you don't want to update your firmware at this time, or you can use it to put your HID Remapper in firmware flashing mode and upgrade your firmware. For details on the upgrade procedure, see the relevant section of the README document on the project's GitHub repository.
When updating firmware, the current configuration on your HID Remapper is preserved. For extra peace of mind you can export your configuration to a JSON file before performing the update. That way if you need to revert to the old version of the firmware for any reason, you'll be able to import the configuration from the JSON file (configuration is lost when going from a newer firmware to an older firmware).
Bluetooth version
There's a separate version of HID Remapper that takes inputs from Bluetooth devices and translates them to USB. Just like the regular USB-to-USB version, from the computer's point of view it looks like a regular USB mouse and keyboard or game controller, so you can use it without any additional drivers. You can even use it with a Nintendo Switch.
Most of the remapping functionality is identical to the regular USB HID Remapper.
The Bluetooth version runs on certain boards with the nRF52840 chip. For details on which boards are currently supported and how to program them with the right firmware, see the BLUETOOTH.md document on the project's GitHub repository.
It's important to note that the Bluetooth version only works with Bluetooth LE devices, not Bluetooth Classic. If you're not sure if your Bluetooth device is LE or Classic, you can install Nordic's nRF Connect app on your phone or tablet, put your device in pairing mode and try scanning for it from the app. If it shows up in the scan then it uses Bluetooth LE, if not then it probably uses Bluetooth Classic.
While most of the functionality is there, certain HID Remapper features are currently missing from the Bluetooth version. For example, it cannot currently act as a boot protocol keyboard, which means it might not work in some older BIOSes or bootloaders, and it doesn't support GPIO inputs or outputs.
GPIO inputs
In addition to its main USB-to-USB remapping functionality, HID Remapper also lets you connect additional buttons or switches directly to GPIO pins on the microcontroller board and then use them as inputs in mappings. This way you can add a few more buttons to your trackball or keyboard, or even build whole new devices like macro pads and game controllers.
HID Remapper as Flatbox firmware
GPIO stands for general purpose I/O and most microcontroller boards have a few of them available for you to use. To connect a button or a switch to such a pin, wire one pin (terminal) on the button to the GPIO pin, and the other to GND. A button just makes a connection between its two terminals, so it doesn't matter which terminal you connect to the GPIO pin and which you connect to GND. If you want to connect multiple buttons, you can wire them all to the same GND pin on the microcontroller.
From this point they work as any other key or button. You should be able to see them in the Monitor tab and you can use them as inputs in mappings, just set the input to GPIO X.
Some variants of HID Remapper have 3.5mm jacks that are meant for plugging in external buttons or switches. This is the same as the GPIO pins described above, just without having to worry about wiring and soldering. You can use any button or switch with a 3.5mm plug, they are often sold as accessories for the Xbox Adaptive Controller or the PlayStation Access controller. You can use them with HID Remapper to build your own adaptive controller.
GPIO outputs
The same GPIO pins that can be used as inputs can also be used as outputs. You could wire them to LEDs and use those for Caps Lock or layer state indicators, or you could wire them to relays to control some external hardware.
Add a Caps Lock LED to your keyboard
Or, if you have another board that takes inputs on its GPIO pins, you could wire HID Remapper output pins to those input pins and use it as a USB decoder. This can be useful if you have some device that doesn't take USB inputs by itself (depending on the specific device, you might be able to just replace it with HID Remapper, but that's not always possible).
There are two GPIO output modes that you can choose from in the Settings tab. First mode is called 0=low, 1=high and in this mode HID Remapper will drive the pin low if the value of the output is 0 and drive the pin high if the value of the output is 1. This mode should be used if you have your GPIO pins wired to things like LEDs, relays or optocouplers. The second mode is called 0=high impedance, 1=low. In this mode HID Remapper will put the pin in a high impedance state if the output value is 0 and drive the pin low if the output value is 1. This mode should be used in situations where you would normally use a switch or button, for example when wiring the output to a GPIO pin on another board that uses pull-ups on its inputs.
It's probably a good idea to have some basic understanding of electronics when using this feature.
Custom boards
HID Remapper runs on certain off-the-shelf microcontroller boards, some of which can be used as-is, while others require some additional work to add a USB host port.
Additionally, a number of boards have been designed as part of this project specifically to run HID Remapper. They're all open hardware and the design files can be found on the project's GitHub repository. You can have them manufactured at a service like JLCPCB.
With some exceptions, the functionality of the custom boards is the same as any other HID Remapper, but each offers some form of convenience over a DIY solution or using other existing microcontroller boards.
Currently the following custom HID Remapper boards exist:
The v1 board is the basic ready to use HID Remapper.
The v2 board doesn't have USB connectors and is meant to be built into existing devices like trackballs by soldering the appropriate wires directly to the board.
The v3 board has the form factor of a USB dongle (you plug it directly into your computer).
The v4 board has eight 3.5mm connectors wired to GPIO pins, meant to be used with external buttons or switches.
The v5 board has a built-in four port USB hub.
The v6 board has a built-in four port USB hub and eighteen 3.5mm connectors wired to GPIO pins that can be used with external buttons or switches. It can act as a ready to use adaptive controller for a PC or a Nintendo Switch.
HID Remapper as an adaptive controller for Nintendo Switch
The v7 board is primarily a companion device for the PlayStation Access controller. It has four analog and ten digital outputs that can be connected to the 3.5mm input ports on the controller. This way you can use any USB device as an input to the PlayStation Access controller, which doesn't have USB inputs of its own.
Use any USB joystick with the PlayStation Access controller
The v8 board has one 3.5mm TRRS jack that can be used for analog inputs. For example it could be used to add analog stick inputs to the Hori Flex controller. The jack also works for one or two digital buttons or switches.
Analog inputs with HID Remapper custom board v8
Most of the boards come with optional 3D printable cases.
For details on how to order and use the custom boards, see the relevant document on the project's GitHub repository.
Polling rate overclocking
Overclock mouse polling rate with HID Remapper
USB input devices can work at various polling rates and it's up to the device to declare the rate at which it wants to be polled. The host (your PC, or HID Remapper for devices that are plugged into it) generally respects the device's wishes and polls it at the declared rate. But it turns out that some devices are capable of operating at polling rates higher than what they declare. And because higher polling rates can be desirable as they result in smoother inputs and lower latency, it is sometimes worth it to try polling your mouse or other device at a higher rate than the default one.
HID Remapper can do this using the Override polling rate option in the Settings tab, which can be set up to 1000 Hz. By default it's set to don't override, which means that the device's default rate will be used.
When the option is set to some polling rate, HID Remapper will poll the device at that rate, but there's no guarantee that the device will be able to actually report using the higher rate. It works for some devices, but not all.
The setting could conceivably also be used to lower the rate at which the device is polled if that's what you want to try.
HID Remapper itself uses 1000 Hz for all communications with the PC, regardless of what polling rates it uses for the devices that are plugged into it.
MIDI
HID Remapper is primarily meant to work with HID class devices like mice, keyboards and game controllers, but it is also compatible with MIDI controllers like keyboards or drum pads, as long as they connect over USB. While they are typically used for making music, they are ultimately input devices, they just use a different protocol.
Input types like notes (with velocity), CC, PC, channel/key pressure (aftertouch) and pitch bend are supported.
The individual inputs are not listed on the screen where you pick the input on a mapping so you will have to use the Monitor tab to see what inputs your controller generates and map them.
Please note that while HID Remapper understands inputs from MIDI controllers, it cannot act as a MIDI controller itself. You can only use it to map MIDI controller inputs to regular mouse, keyboard or game controller outputs.
Q&A
What if the configuration website goes down?
There's nothing special about the configuration website, all of its files are available on the GitHub repository, anyone can take them and host them at some other place, and it will work with your HID Remapper. You could even serve them from your local machine.
If I plug a webcam or a USB microphone into HID Remapper, will it still work as a webcam/microphone?
No. HID Remapper doesn't pass everything transparently between the PC and the devices plugged into it. It doesn't work as a generic USB hub. It only acts as a mouse/keyboard combo or a game controller, depending on what the emulated device type is set to.
Can I use a different board than the Pico to make an HID Remapper?
Yes, you can pretty much use any board with the RP2040 chip.
When I plug a gamepad into HID Remapper, my mouse cursor goes all the way to the lower right corner and stops working.
This is because the (left) stick on a game controller shares the hex code (usage) with mouse movement and the neutral position of a stick axis is represented by 128. So when the emulated device type is set to Mouse and keyboard and the Unmapped inputs passthrough setting is enabled, the stick's neutral position gets translated to nonsensical mouse movement outputs. Perhaps in the future this will be handled better by HID Remapper itself, for now either disable the Unmapped inputs passthrough option or map the stick axes to Nothing.
Is there a way to send inputs to HID Remapper from a PC while it's connected to another device like a Nintendo Switch?
It's not currently possible, but take a look at the HID Forwarder project, maybe it does what you need. You could use it together with HID Remapper.