uinput-mapper is a program that can clone and remap (in clones) input devices to other (newly created) input devices (locally or over the network). It also offers a nice API to both the /dev/input/* and /dev/uinput devices in Python.

For any questions regarding a HGB project see: Contact

Quick Links:

Source: http://github.com/MerlijnWajer/uinput-mapper


Initially we wrote this program to create two virtual joysticks from a single keyboard, which was really just two real arcade joysticks exposed over a keyboard. To be able to use these joysticks separately and to have SDL recognise them, I wrote a program with uinput to create two joystick devices. The program quickly evolved into uinput-mapper, a generalisation of the concept. The result is a set of command line utilities and python modules that allow you to remap all kind of input devices to new input devices. You can split and merge input devices, as well as write programs using the python modules to create "programmable" input devices.

uinput-mapper in distributions and other projects

Source: http://github.com/MerlijnWajer/uinput-mapper



This section will discuss how to use uinput-mapper to easily create input devices from existing devices as input using the two uinput-mapper tools:

The idea in a nutshell:

input-read will read one (or several) input-devices to stdout.
input-create will read from stdin and create a clone (or mapping) of the input presented.


input-read reads events from input devices. These usually reside in /dev/input/. input-read can read input events from any amount of input devices.

If you want to pass along events to input-create; start input-read with the -D flag and pipe the output to input-create; input-read will automagically detect the configuration of the passed input devices and pass those along to input-create as well. More on this later; at the input-create section.

To grab a device, pass the -G flag, followed by an input device. Grabbing a device is useful if you do not want other programs to interact / read from the input device.

Important: The order in which you pass input devices to input-read matters to input-create! Furthermore, any device passed with -G will be put after all the other input devices. Therefore, it is best to always put the input devices that you want to grab as the final arguments, like so:

input-read /dev/input/event1 /dev/input/event4 -G /dev/input/event2

Finally, the -C flag will marshall the events in such a way that is more compatible with other versions of python. It is only to be used with the -D option, but may be advisable if you run into problems.

$ input-read --help
Usage: input-read /dev/input/event<0> ... /dev/input/event<N>

Read input devices.

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -D, --dump            Dump will marshall all the events to stdout
  -v, --verbose         Enable verbose mode (do not combine with -D)
  -G GRAB, --grab=GRAB
  -C, --compat          Enable compatibility mode; for Python < 2.7


input-create reads events from stdin; typically events from input-read (with the -D flag). input-create will also recieve the initial device configuration from input-create. input-read reads all the keys that exported by all the input devices (and possible other properties) and passes these over stdout to input-create. By default, input-create will use this configuration, but it is very simple to modify the configuration.

A very basic example, simply cloning an input device:

   1 ./input-read -D /dev/input/event3 | ./input-create

See uinput-mapper/Config for an detailed explanation of the configuration. Here we will only discuss the input-create options.

input-create by default takes no arguments, but if you wish to pass a configuration file, simply add it to the arguments.

If you used -C on input-read, you must also use -C on input-create. For the effect of -C, see the input-read section.

The -S flag will make input-create send synchronisation events to all newly created input-devices. This is particularly useful if you are creating multiple input devices from a single input device. If you run into problems where input-create is magically not sending events, use -S.

Usage: python create.py /path/to/config1 ... /path/to/configN

Create input devices.

  --version      show program's version number and exit
  -h, --help     show this help message and exit
  -C, --compat   Enable compatibility mode; for Python < 2.7
  -S, --sync     Synchronise all events on an synchronise event
  -v, --verbose  Enable verbose mode


The configuration is done in Python, it is mostly a large dictionary but can be extended with function. The configuration can be quite simple, but it can also grow quite complex. See the config page for a full explanation on the configuration. For some quick examples, have a look at Use Cases with Configurations for possible configurations and use cases.


TODO: Add a lot more here. (Permission problems, sync problems, etc)

No events seem to be passed over the network.

Solution: Pass the compatibility flag to both input-read and input-create. (-C)

Future plans

Implementation in Python

Implementation of uinput-mapper in Python.

API: TODO: Document this properly

Linux input

Low level Python interface to Linux' "input.h".

Required for reading input event as well as the creation of aforementioned.


Linux uinput


cinput combines the input and uinput modules and provides a higher level api.

Currently it exposes two classes:


TODO: Screenshots of the new program

uinput-mapper (last edited 2014-09-29 23:26:38 by MerlijnWajer)