1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
### 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
This backend does not take any global 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 (prefix-matched) |
| `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.
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 received
* `minimum`: The axis minimum value
* `maximum`: The axis maximum value
* `fuzz`: A value used for filtering the input stream
* `flat`: An offset, below which all deviations will be ignored
* `resolution`: Axis resolution in units per millimeter (or units per radian for rotational axes)
For real devices, all of these parameters for every axis can be found by running `evtest` on the device.
#### 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](https://www.kernel.org/doc/html/v4.12/input/event-codes.html). The most interesting event types are
* `EV_KEY` for keys and buttons
* `EV_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.
Relative axes (`EV_REL`-type events), such as generated by mouses, are currently handled in a very basic fashion,
generating only the normalized channel 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.
`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.
|
