The evdev
backend
This backend allows using Linux evdev
devices such as mouses, keyboards, gamepads and joysticks
as input and output devices. All buttons and axes available to the Linux system are mappable.
Output is provided by the uinput
kernel module, which allows creation of virtual input devices.
This functionality may require elevated privileges (such as special group membership or root access).
Global configuration
Option | Example value | Default value | Description |
---|---|---|---|
detect |
on |
off |
Output channel specifications for any events coming in on configured instances to help with configuration. |
Instance configuration
Option | Example value | Default value | Description |
---|---|---|---|
device |
/dev/input/event1 |
none | evdev device to use as input device |
input |
Xbox Wireless |
none | Presentation name of evdev device to use as input (most-specific prefix matched), can be used instead of the device option |
output |
My Input Device |
none | Output device presentation name. Setting this option enables the instance for output |
exclusive |
1 |
0 |
Prevent other processes from using the device |
id |
0x1 0x2 0x3 |
none | Set output device bus identification (Vendor, Product and Version), optional |
axis.AXISNAME |
34300 0 65536 255 4095 |
none | Specify absolute axis details (see below) for output. This is required for any absolute axis to be output. |
relaxis.AXISNAME |
65534 32767 |
none | Specify relative axis details (extent and optional initial value) for output and input (see below). |
The absolute axis details configuration (e.g. axis.ABS_X
) is required for any absolute axis on output-enabled
instances. The configuration value contains, space-separated, the following values:
value
: The value to assume for the axis until an event is receivedminimum
: The axis minimum valuemaximum
: The axis maximum valuefuzz
: A value used for filtering the input streamflat
: An offset, below which all deviations will be ignoredresolution
: Axis resolution in units per millimeter (or units per radian for rotational axes)
If an axis is not used for output, this configuration can be omitted.
For real devices, all of these parameters for every axis can be found by running evtest
on the device.
To use the input from relative axes in absolute-value based protocols, the backend needs a reference frame to
convert the relative movements to absolute values. To invert the mapping of the relative axis, specify the max
value
as a negative number, for example:
relaxis.REL_X = -1024 512
If relative axes are used without specifying their extents, the channel will generate normalized values
of 0
, 0.5
and 1
for any input less than, equal to and greater than 0
, respectively. As for output, only
the values -1
, 0
and 1
are generated for the same interval.
Channel specification
A channel is specified by its event type and event code, separated by .
. For a complete list of event types and codes
see the kernel documentation. The most interesting event types are
EV_KEY
for keys and buttonsEV_ABS
for absolute axes (such as Joysticks)EV_REL
for relative axes (such as Mouses)
The evtest
tool is useful to gather information on devices active on the local system, including names, types, codes
and configuration supported by these devices.
Example mapping:
ev1.EV_KEY.KEY_A > ev1.EV_ABS.ABS_X
Note that to map an absolute axis on an output-enabled instance, additional information such as the axis minimum and maximum are required. These must be specified in the instance configuration. When only mapping the instance as a channel input, this is not required.
Known bugs / problems
Creating an evdev
output device requires elevated privileges, namely, write access to the system's
/dev/uinput
. Usually, this is granted for users in the input
group and the root
user.
Input devices may synchronize logically connected event types (for example, X and Y axes) via EV_SYN
-type
events. The MIDIMonster also generates these events after processing channel events, but may not keep the original
event grouping.
EV_KEY
key-down events are sent for normalized channel values over 0.9
.
Extended event type values such as EV_LED
, EV_SND
, etc are recognized in the MIDIMonster configuration file
but may or may not work with the internal channel mapping and normalization code.