From 0c333567f599206cb0be6b74f02e59820536e0b2 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 31 Mar 2019 09:00:12 +0200 Subject: Move backend documentation out of main README --- backends/evdev.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 backends/evdev.md (limited to 'backends/evdev.md') diff --git a/backends/evdev.md b/backends/evdev.md new file mode 100644 index 0000000..dfe5ec9 --- /dev/null +++ b/backends/evdev.md @@ -0,0 +1,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. \ No newline at end of file -- cgit v1.2.3 From c75721e77ecada3c88f4b493c1e3036c151bfe88 Mon Sep 17 00:00:00 2001 From: cbdev Date: Wed, 24 Jul 2019 21:33:23 +0200 Subject: Clarify backend documentation --- backends/evdev.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'backends/evdev.md') diff --git a/backends/evdev.md b/backends/evdev.md index dfe5ec9..d750f1e 100644 --- a/backends/evdev.md +++ b/backends/evdev.md @@ -30,6 +30,8 @@ instances. The configuration value contains, space-separated, the following valu * `flat`: An offset, below which all deviations will be ignored * `resolution`: 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. #### Channel specification @@ -69,4 +71,4 @@ than `0`, respectively. As for output, only the values `-1`, `0` and `1` are gen `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. \ No newline at end of file +but may or may not work with the internal channel mapping and normalization code. -- cgit v1.2.3 From 4e604b493e0dc855b6ea6978e5cf8e2de5d2b8d5 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sun, 28 Jul 2019 23:40:40 +0200 Subject: Fix evdev relative axes, add detect option --- backends/evdev.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'backends/evdev.md') diff --git a/backends/evdev.md b/backends/evdev.md index d750f1e..995b44c 100644 --- a/backends/evdev.md +++ b/backends/evdev.md @@ -7,7 +7,9 @@ This functionality may require elevated privileges (such as special group member #### Global configuration -This backend does not take any global configuration. +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|-----------------------| +| `detect` | `on` | `off` | Output the channel specification for all events coming in on configured instances to help with configuration. | #### Instance configuration @@ -18,7 +20,8 @@ This backend does not take any global configuration. | `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. +| `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: @@ -34,6 +37,13 @@ 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. + +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 @@ -64,10 +74,6 @@ Input devices may synchronize logically connected event types (for example, X an 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 -- cgit v1.2.3 From a23ce7718ab61e73586d2738329d6bbace0b764b Mon Sep 17 00:00:00 2001 From: cbdev Date: Thu, 1 Aug 2019 20:54:17 +0200 Subject: Implement evdev relative axis inversion --- backends/evdev.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'backends/evdev.md') diff --git a/backends/evdev.md b/backends/evdev.md index 995b44c..88dfc85 100644 --- a/backends/evdev.md +++ b/backends/evdev.md @@ -38,12 +38,18 @@ 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. +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 -- cgit v1.2.3 From bbeade8898200a8024169ece30c620016fd5eaf1 Mon Sep 17 00:00:00 2001 From: cbdev Date: Thu, 1 Aug 2019 20:58:21 +0200 Subject: Implement midi backend detect option --- backends/evdev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'backends/evdev.md') diff --git a/backends/evdev.md b/backends/evdev.md index 88dfc85..d57201d 100644 --- a/backends/evdev.md +++ b/backends/evdev.md @@ -9,7 +9,7 @@ This functionality may require elevated privileges (such as special group member | Option | Example value | Default value | Description | |---------------|-----------------------|-----------------------|-----------------------| -| `detect` | `on` | `off` | Output the channel specification for all events coming in on configured instances to help with configuration. | +| `detect` | `on` | `off` | Output channel specifications for any events coming in on configured instances to help with configuration. | #### Instance configuration -- cgit v1.2.3