From c583ba3961db8636f15252809209136f59dfc3a2 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 18 Feb 2018 21:38:06 +0100 Subject: Documentation for the evdev backend --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/README.md b/README.md index c79ac8e..da972ea 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,81 @@ NRPNs are not yet fully implemented, though rudimentary support is in the codeba The channel specification syntax is currently a bit clunky. +### 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 | +|---------------|-----------------------|---------------|-----------------------------------------------| +| `input` | `/dev/input/event1` | none | `evdev` device to use as input device | +| `exclusive` | `1` | `0` | Prevent other processes from using the device | +| `name` | `My Input Device` | none | Output device presentation name. Setting this option enables the instance for output | +| `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 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 sources. 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 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. + +Input devices can currently only be specified by device node directly. There may be a facility to open input +devices by presentation name in the future. + ### The `loopback` backend This backend allows the user to create logical mapping channels, for example to exchange triggering @@ -265,6 +340,7 @@ In order to build the MIDIMonster, you'll need some libraries that provide support for the protocols to translate. * libasound2-dev (for the MIDI backend) +* libevdev-dev (for the evdev backend) * A C compiler * GNUmake -- cgit v1.2.3