aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--README.md429
-rw-r--r--backends/artnet.md41
-rw-r--r--backends/evdev.md72
-rw-r--r--backends/loopback.md28
-rw-r--r--backends/midi.md54
-rw-r--r--backends/ola.md41
-rw-r--r--backends/osc.md81
-rw-r--r--backends/sacn.md58
8 files changed, 386 insertions, 418 deletions
diff --git a/README.md b/README.md
index 8dfcdd8..6265581 100644
--- a/README.md
+++ b/README.md
@@ -30,42 +30,6 @@ on any other (or the same) supported protocol, for example to:
* [Usage](#usage)
* [Configuration](#configuration)
* [Backend documentation](#backend-documentation)
- + [The `artnet` backend](#the-artnet-backend)
- - [Global configuration](#global-configuration)
- - [Instance configuration](#instance-configuration)
- - [Channel specification](#channel-specification)
- - [Known bugs / problems](#known-bugs--problems)
- + [The `sacn` backend](#the-sacn-backend)
- - [Global configuration](#global-configuration-1)
- - [Instance configuration](#instance-configuration-1)
- - [Channel specification](#channel-specification-1)
- - [Known bugs / problems](#known-bugs--problems-1)
- + [The `midi` backend](#the-midi-backend)
- - [Global configuration](#global-configuration-2)
- - [Instance configuration](#instance-configuration-2)
- - [Channel specification](#channel-specification-2)
- - [Known bugs / problems](#known-bugs--problems-2)
- + [The `evdev` backend](#the-evdev-backend)
- - [Global configuration](#global-configuration-3)
- - [Instance configuration](#instance-configuration-3)
- - [Channel specification](#channel-specification-3)
- - [Known bugs/problems](#known-bugs--problems-3)
- + [The `loopback` backend](#the-loopback-backend)
- - [Global configuration](#global-configuration-4)
- - [Instance configuration](#instance-configuration-4)
- - [Channel specification](#channel-specification-4)
- - [Known bugs / problems](#known-bugs--problems-4)
- + [The `osc` backend](#the-osc-backend)
- - [Global configuration](#global-configuration-5)
- - [Instance configuration](#instance-configuration-5)
- - [Channel specification](#channel-specification-5)
- - [Supported types & value ranges](#supported-types--value-ranges)
- - [Known bugs / problems](#known-bugs--problems-5)
- + [The `ola` backend](#the-ola-backend)
- - [Global configuration](#global-configuration-6)
- - [Instance configuration](#instance-configuration-6)
- - [Channel specification](#channel-specification-6)
- - [Known bugs / problems](#known-bugs--problems-6)
* [Building](#building)
+ [Prerequisites](#prerequisites)
+ [Build](#build)
@@ -112,389 +76,18 @@ The last line is a shorter way to create a bi-directional mapping.
Example configuration files may be found in [configs/](configs/).
## Backend documentation
-This section documents the configuration options supported by the various backends.
-### The `artnet` backend
-
-The ArtNet backend provides read-write access to the UDP-based ArtNet protocol for lighting
-fixture control.
-
-#### Global configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `bind` | `127.0.0.1 6454` | none | Binds a network address to listen for data. This option may be set multiple times, with each interface being assigned an index starting from 0 to be used with the `interface` instance configuration option. At least one interface is required for transmission. |
-| `net` | `0` | `0` | The default net to use |
-
-#### Instance configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `net` | `0` | `0` | ArtNet `net` to use |
-| `universe` | `0` | `0` | Universe identifier |
-| `destination` | `10.2.2.2` | none | Destination address for sent ArtNet frames. Setting this enables the universe for output |
-| `interface` | `1` | `0` | The bound address to use for data input/output |
-
-#### Channel specification
-
-A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
-
-Example mapping:
-```
-net1.231 < net2.123
-```
-
-A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
-```
-net1.1+2 > net2.5+123
-```
-
-A normal channel that is part of a wide channel can not be mapped individually.
-
-#### Known bugs / problems
-
-The minimum inter-frame-time is disregarded, as the packet rate is determined by the rate of incoming
-channel events.
-
-### The `sacn` backend
-
-The sACN backend provides read-write access to the Multicast-UDP based streaming ACN protocol (ANSI E1.31-2016),
-used for lighting fixture control. The backend sends universe discovery frames approximately every 10 seconds,
-containing all write-enabled universes.
-
-#### Global configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `name` | `sACN source` | `MIDIMonster` | sACN source name |
-| `cid` | `0xAA 0xBB 0xCC` ... | `MIDIMonster` | Source CID (16 bytes) |
-| `bind` | `0.0.0.0 5568` | none | Binds a network address to listen for data. This option may be set multiple times, with each descriptor being assigned an index starting from 0 to be used with the `interface` instance configuration option. At least one descriptor is required for transmission. |
-
-#### Instance configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `universe` | `0` | none | Universe identifier |
-| `interface` | `1` | `0` | The bound address to use for data input/output |
-| `priority` | `100` | none | The data priority to transmit for this instance. Setting this option enables the instance for output and includes it in the universe discovery report. |
-| `destination` | `10.2.2.2` | Universe multicast | Destination address for unicast output. If unset, the multicast destination for the specified universe is used. |
-| `from` | `0xAA 0xBB` ... | none | 16-byte input source CID filter. Setting this option filters the input stream for this universe. |
-| `unicast` | `1` | `0` | Prevent this instance from joining its universe multicast group |
-
-Note that instances accepting multicast input also process unicast frames directed at them, while
-instances in `unicast` mode will not receive multicast frames.
-
-#### Channel specification
-
-A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
-
-Example mapping:
-```
-sacn1.231 < sacn2.123
-```
-
-A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
-```
-sacn.1+2 > sacn2.5+123
-```
-
-A normal channel that is part of a wide channel can not be mapped individually.
-
-#### Known bugs / problems
-
-The DMX start code of transmitted and received universes is fixed as `0`.
-
-The (upper) limit on packet transmission rate mandated by section 6.6.1 of the sACN specification is disregarded.
-The rate of packet transmission is influenced by the rate of incoming mapped events on the instance.
-
-Universe synchronization is currently not supported, though this feature may be implemented in the future.
-
-To use multicast input, all networking hardware in the path must support the IGMPv2 protocol.
-
-The Linux kernel limits the number of multicast groups an interface may join to 20. An instance configured
-for input automatically joins the multicast group for its universe, unless configured in `unicast` mode.
-This limit can be raised by changing the kernel option in `/proc/sys/net/ipv4/igmp_max_memberships`.
-
-### The `midi` backend
-
-The MIDI backend provides read-write access to the MIDI protocol via virtual ports.
-
-#### Global configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `name` | `MIDIMonster` | none | MIDI client name |
-
-#### Instance configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `read` | `20:0` | none | MIDI device to connect for input |
-| `write` | `DeviceName` | none | MIDI device to connect for output |
-
-MIDI device names may either be `client:port` portnames or prefixes of MIDI device names.
-Run `aconnect -i` to list input ports and `aconnect -o` to list output ports.
-
-Each instance also provides a virtual port, so MIDI devices can also be connected with `aconnect <sender> <receiver>`.
-
-#### Channel specification
-
-The MIDI backend supports multiple channel types
-
-* `cc` - Control Changes
-* `note` - Note On/Off messages
-* `nrpn` - NRPNs (not yet implemented)
-
-A channel is specified using the syntax `channel<channel>.<type><index>`. The shorthand `ch` may be used instead
-of `channel`.
-The earlier syntax of `<type><channel>.<index>` is officially deprecated but still supported for compatability
-reasons. This support may be removed at some future time.
-
-Channels range from `0` to `15`. Each channel consists of 128 notes (numbered `0` through `127`) and 128 CC's
-(numbered likewise), a channel pressure control (also called 'channel aftertouch') and a pitch control.
-Each Note also has an additional pressure value associated with it.
-
-Example mappings:
-```
-midi1.ch0.note9 > midi2.channel1.cc4
-midi1.channel15.cc1 > midi1.channel0.note0
-```
-#### Known bugs / problems
-
-Currently, no Note Off messages are sent (instead, Note On messages with a velocity of 0 are
-generated, which amount to the same thing according to the spec). This may be implemented as
-a configuration option at a later time.
-
-NRPNs are not yet fully implemented, though rudimentary support is in the codebase.
-
-To see which events your MIDI devices output, ALSA provides the `aseqdump` utility. You can
-list all incoming events using `aseqdump -p <portname>`.
-
-### 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.
-
-### The `loopback` backend
-
-This backend allows the user to create logical mapping channels, for example to exchange triggering
-channels easier later. All events that are input are immediately output again on the same channel.
-
-#### Global configuration
-
-All global configuration is ignored.
-
-#### Instance configuration
-
-All instance configuration is ignored
-
-#### Channel specification
-
-A channel may have any string for a name.
-
-Example mapping:
-```
-loop.foo < loop.bar123
-```
-
-#### Known bugs / problems
-
-It is possible to configure loops using this backend. Triggering a loop
-will create a deadlock, preventing any other backends from generating events.
-Be careful with bidirectional channel mappings, as any input will be immediately
-output to the same channel again.
-
-### The `osc` backend
-
-This backend offers read and write access to the Open Sound Control protocol,
-spoken primarily by visual interface tools and hardware such as TouchOSC.
-
-#### Global configuration
-
-This backend does not take any global configuration.
-
-#### Instance configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|-----------------------|-----------------------|
-| `root` | `/my/osc/path` | none | An OSC path prefix to be prepended to all channels |
-| `bind` | `:: 8000` | none | The host and port to listen on |
-| `destination` | `10.11.12.13 8001` | none | Remote address to send OSC data to. Setting this enables the instance for output. The special value `learn` causes the MIDImonster to always reply to the address the last incoming packet came from. A different remote port for responses can be forced with the syntax `learn@<port>` |
-
-Note that specifying an instance root speeds up matching, as packets not matching
-it are ignored early in processing.
-
-Channels that are to be output or require a value range different from the default ranges (see below)
-require special configuration, as their types and limits have to be set.
-
-This is done in the instance configuration using an assignment of the syntax
-
-```
-/local/osc/path = <format> <min> <max> <min> <max> ...
-```
-
-The OSC path to be configured must only be the local part (omitting a configured instance root).
-
-**format** may be any sequence of valid OSC type characters. See below for a table of supported
-OSC types.
-
-For each component of the path, the minimum and maximum values must be given separated by spaces.
-Components may be accessed in the mapping section as detailed in the next section.
-
-An example configuration for transmission of an OSC message with 2 floating point components with
-a range between 0.0 and 2.0 (for example, an X-Y control), would look as follows:
-
-```
-/1/xy1 = ff 0.0 2.0 0.0 2.0
-```
-
-#### Channel specification
-
-A channel may be any valid OSC path, to which the instance root will be prepended if
-set. Multi-value controls (such as X-Y pads) are supported by appending `:n` to the path,
-where `n` is the parameter index, with the first (and default) one being `0`.
-
-Example mapping:
-```
-osc1./1/xy1:0 > osc2./1/fader1
-```
-
-Note that any channel that is to be output will need to be set up in the instance
-configuration.
-
-#### Supported types & value ranges
-
-OSC allows controls to have individual value ranges and supports different parameter types.
-The following types are currently supported by the MIDImonster:
-
-* **i**: 32-bit signed integer
-* **f**: 32-bit IEEE floating point
-* **h**: 64-bit signed integer
-* **d**: 64-bit double precision floating point
-
-For each type, there is a default value range which will be assumed if the channel is not otherwise
-configured using the instance configuration. Values out of a channels range will be clipped.
-
-The default ranges are:
-
-* **i**: `0` to `255`
-* **f**: `0.0` to `1.0`
-* **h**: `0` to `1024`
-* **d**: `0.0` to `1.0`
-
-#### Known bugs / problems
-
-Ping requests are not yet answered. There may be some problems using broadcast output and input.
-
-### The `ola` backend
-
-This backend connects the MIDIMonster to the Open Lighting Architecture daemon. This can be useful
-to take advantage of additional protocols implemented in OLA. This backend is currently marked as
-optional and is only built with `make full` in the `backends/` directory, as the OLA is a large
-dependency to require for all users.
-
-#### Global configuration
-
-This backend does not take any global configuration.
-
-#### Instance configuration
-
-| Option | Example value | Default value | Description |
-|---------------|-----------------------|---------------|-------------------------------------------------------|
-| `universe` | `7` | `0` | OLA universe to send/receive data on |
-
-#### Channel specification
-
-A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
-
-Example mapping:
-```
-ola1.231 < in2.123
-```
-
-A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
-```
-ola1.1+2 > net2.5+123
-```
-
-A normal channel that is part of a wide channel can not be mapped individually.
-
-#### Known bugs / problems
-
-The backend currently assumes that the OLA daemon is running on the same host as the MIDIMonster.
-This may be made configurable in the future.
-
-This backend requires `libola-dev` to be installed, which pulls in a rather large and aggressive (in terms of probing
-and taking over connected hardware) daemon. It is thus marked as optional and only built when executing the `full` target
-within the `backends` directory.
+Every backend includes specific documentation, including the global and instance
+configuration options, channel specification syntax and any known problems or other
+special information. These documentation files are located in the `backends/` directory.
+
+* [`midi` backend documentation](backends/midi.md)
+* [`artnet` backend documentation](backends/artnet.md)
+* [`sacn` backend documentation](backends/sacn.md)
+* [`evdev` backend documentation](backends/evdev.md)
+* [`loopback` backend documentation](backends/loopback.md)
+* [`ola` backend documentation](backends/ola.md)
+* [`osc` backend documentation](backends/osc.md)
## Building
diff --git a/backends/artnet.md b/backends/artnet.md
new file mode 100644
index 0000000..90a7697
--- /dev/null
+++ b/backends/artnet.md
@@ -0,0 +1,41 @@
+### The `artnet` backend
+
+The ArtNet backend provides read-write access to the UDP-based ArtNet protocol for lighting
+fixture control.
+
+#### Global configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `bind` | `127.0.0.1 6454` | none | Binds a network address to listen for data. This option may be set multiple times, with each interface being assigned an index starting from 0 to be used with the `interface` instance configuration option. At least one interface is required for transmission. |
+| `net` | `0` | `0` | The default net to use |
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `net` | `0` | `0` | ArtNet `net` to use |
+| `universe` | `0` | `0` | Universe identifier |
+| `destination` | `10.2.2.2` | none | Destination address for sent ArtNet frames. Setting this enables the universe for output |
+| `interface` | `1` | `0` | The bound address to use for data input/output |
+
+#### Channel specification
+
+A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
+
+Example mapping:
+```
+net1.231 < net2.123
+```
+
+A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
+```
+net1.1+2 > net2.5+123
+```
+
+A normal channel that is part of a wide channel can not be mapped individually.
+
+#### Known bugs / problems
+
+The minimum inter-frame-time is disregarded, as the packet rate is determined by the rate of incoming
+channel events. \ No newline at end of file
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
diff --git a/backends/loopback.md b/backends/loopback.md
new file mode 100644
index 0000000..a06c768
--- /dev/null
+++ b/backends/loopback.md
@@ -0,0 +1,28 @@
+### The `loopback` backend
+
+This backend allows the user to create logical mapping channels, for example to exchange triggering
+channels easier later. All events that are input are immediately output again on the same channel.
+
+#### Global configuration
+
+All global configuration is ignored.
+
+#### Instance configuration
+
+All instance configuration is ignored
+
+#### Channel specification
+
+A channel may have any string for a name.
+
+Example mapping:
+```
+loop.foo < loop.bar123
+```
+
+#### Known bugs / problems
+
+It is possible (and very easy) to configure loops using this backend. Triggering a loop
+will create a deadlock, preventing any other backends from generating events.
+Be careful with bidirectional channel mappings, as any input will be immediately
+output to the same channel again. \ No newline at end of file
diff --git a/backends/midi.md b/backends/midi.md
new file mode 100644
index 0000000..7d3e847
--- /dev/null
+++ b/backends/midi.md
@@ -0,0 +1,54 @@
+### The `midi` backend
+
+The MIDI backend provides read-write access to the MIDI protocol via virtual ports.
+
+#### Global configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `name` | `MIDIMonster` | none | MIDI client name |
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `read` | `20:0` | none | MIDI device to connect for input |
+| `write` | `DeviceName` | none | MIDI device to connect for output |
+
+MIDI device names may either be `client:port` portnames or prefixes of MIDI device names.
+Run `aconnect -i` to list input ports and `aconnect -o` to list output ports.
+
+Each instance also provides a virtual port, so MIDI devices can also be connected with `aconnect <sender> <receiver>`.
+
+#### Channel specification
+
+The MIDI backend supports multiple channel types
+
+* `cc` - Control Changes
+* `note` - Note On/Off messages
+* `nrpn` - NRPNs (not yet implemented)
+
+A channel is specified using the syntax `channel<channel>.<type><index>`. The shorthand `ch` may be used instead
+of `channel`.
+The earlier syntax of `<type><channel>.<index>` is officially deprecated but still supported for compatability
+reasons. This support may be removed at some future time.
+
+Channels range from `0` to `15`. Each channel consists of 128 notes (numbered `0` through `127`) and 128 CC's
+(numbered likewise), a channel pressure control (also called 'channel aftertouch') and a pitch control.
+Each Note also has an additional pressure value associated with it.
+
+Example mappings:
+```
+midi1.ch0.note9 > midi2.channel1.cc4
+midi1.channel15.cc1 > midi1.channel0.note0
+```
+#### Known bugs / problems
+
+Currently, no Note Off messages are sent (instead, Note On messages with a velocity of 0 are
+generated, which amount to the same thing according to the spec). This may be implemented as
+a configuration option at a later time.
+
+NRPNs are not yet fully implemented, though rudimentary support is in the codebase.
+
+To see which events your MIDI devices output, ALSA provides the `aseqdump` utility. You can
+list all incoming events using `aseqdump -p <portname>`. \ No newline at end of file
diff --git a/backends/ola.md b/backends/ola.md
new file mode 100644
index 0000000..e3a1197
--- /dev/null
+++ b/backends/ola.md
@@ -0,0 +1,41 @@
+### The `ola` backend
+
+This backend connects the MIDIMonster to the Open Lighting Architecture daemon. This can be useful
+to take advantage of additional protocols implemented in OLA. This backend is currently marked as
+optional and is only built with `make full` in the `backends/` directory, as the OLA is a large
+dependency to require for all users.
+
+#### Global configuration
+
+This backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|---------------|-------------------------------------------------------|
+| `universe` | `7` | `0` | OLA universe to send/receive data on |
+
+#### Channel specification
+
+A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
+
+Example mapping:
+```
+ola1.231 < in2.123
+```
+
+A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
+```
+ola1.1+2 > net2.5+123
+```
+
+A normal channel that is part of a wide channel can not be mapped individually.
+
+#### Known bugs / problems
+
+The backend currently assumes that the OLA daemon is running on the same host as the MIDIMonster.
+This may be made configurable in the future.
+
+This backend requires `libola-dev` to be installed, which pulls in a rather large and aggressive (in terms of probing
+and taking over connected hardware) daemon. It is thus marked as optional and only built when executing the `full` target
+within the `backends` directory. \ No newline at end of file
diff --git a/backends/osc.md b/backends/osc.md
new file mode 100644
index 0000000..c784cda
--- /dev/null
+++ b/backends/osc.md
@@ -0,0 +1,81 @@
+### The `osc` backend
+
+This backend offers read and write access to the Open Sound Control protocol,
+spoken primarily by visual interface tools and hardware such as TouchOSC.
+
+#### Global configuration
+
+This backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `root` | `/my/osc/path` | none | An OSC path prefix to be prepended to all channels |
+| `bind` | `:: 8000` | none | The host and port to listen on |
+| `destination` | `10.11.12.13 8001` | none | Remote address to send OSC data to. Setting this enables the instance for output. The special value `learn` causes the MIDImonster to always reply to the address the last incoming packet came from. A different remote port for responses can be forced with the syntax `learn@<port>` |
+
+Note that specifying an instance root speeds up matching, as packets not matching
+it are ignored early in processing.
+
+Channels that are to be output or require a value range different from the default ranges (see below)
+require special configuration, as their types and limits have to be set.
+
+This is done in the instance configuration using an assignment of the syntax
+
+```
+/local/osc/path = <format> <min> <max> <min> <max> ...
+```
+
+The OSC path to be configured must only be the local part (omitting a configured instance root).
+
+**format** may be any sequence of valid OSC type characters. See below for a table of supported
+OSC types.
+
+For each component of the path, the minimum and maximum values must be given separated by spaces.
+Components may be accessed in the mapping section as detailed in the next section.
+
+An example configuration for transmission of an OSC message with 2 floating point components with
+a range between 0.0 and 2.0 (for example, an X-Y control), would look as follows:
+
+```
+/1/xy1 = ff 0.0 2.0 0.0 2.0
+```
+
+#### Channel specification
+
+A channel may be any valid OSC path, to which the instance root will be prepended if
+set. Multi-value controls (such as X-Y pads) are supported by appending `:n` to the path,
+where `n` is the parameter index, with the first (and default) one being `0`.
+
+Example mapping:
+```
+osc1./1/xy1:0 > osc2./1/fader1
+```
+
+Note that any channel that is to be output will need to be set up in the instance
+configuration.
+
+#### Supported types & value ranges
+
+OSC allows controls to have individual value ranges and supports different parameter types.
+The following types are currently supported by the MIDImonster:
+
+* **i**: 32-bit signed integer
+* **f**: 32-bit IEEE floating point
+* **h**: 64-bit signed integer
+* **d**: 64-bit double precision floating point
+
+For each type, there is a default value range which will be assumed if the channel is not otherwise
+configured using the instance configuration. Values out of a channels range will be clipped.
+
+The default ranges are:
+
+* **i**: `0` to `255`
+* **f**: `0.0` to `1.0`
+* **h**: `0` to `1024`
+* **d**: `0.0` to `1.0`
+
+#### Known bugs / problems
+
+Ping requests are not yet answered. There may be some problems using broadcast output and input. \ No newline at end of file
diff --git a/backends/sacn.md b/backends/sacn.md
new file mode 100644
index 0000000..3d245a4
--- /dev/null
+++ b/backends/sacn.md
@@ -0,0 +1,58 @@
+### The `sacn` backend
+
+The sACN backend provides read-write access to the Multicast-UDP based streaming ACN protocol (ANSI E1.31-2016),
+used for lighting fixture control. The backend sends universe discovery frames approximately every 10 seconds,
+containing all write-enabled universes.
+
+#### Global configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `name` | `sACN source` | `MIDIMonster` | sACN source name |
+| `cid` | `0xAA 0xBB 0xCC` ... | `MIDIMonster` | Source CID (16 bytes) |
+| `bind` | `0.0.0.0 5568` | none | Binds a network address to listen for data. This option may be set multiple times, with each descriptor being assigned an index starting from 0 to be used with the `interface` instance configuration option. At least one descriptor is required for transmission. |
+
+#### Instance configuration
+
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `universe` | `0` | none | Universe identifier |
+| `interface` | `1` | `0` | The bound address to use for data input/output |
+| `priority` | `100` | none | The data priority to transmit for this instance. Setting this option enables the instance for output and includes it in the universe discovery report. |
+| `destination` | `10.2.2.2` | Universe multicast | Destination address for unicast output. If unset, the multicast destination for the specified universe is used. |
+| `from` | `0xAA 0xBB` ... | none | 16-byte input source CID filter. Setting this option filters the input stream for this universe. |
+| `unicast` | `1` | `0` | Prevent this instance from joining its universe multicast group |
+
+Note that instances accepting multicast input also process unicast frames directed at them, while
+instances in `unicast` mode will not receive multicast frames.
+
+#### Channel specification
+
+A channel is specified by it's universe index. Channel indices start at 1 and end at 512.
+
+Example mapping:
+```
+sacn1.231 < sacn2.123
+```
+
+A 16-bit channel (spanning any two normal 8-bit channels in the same universe, also called a wide channel) may be mapped with the syntax
+```
+sacn.1+2 > sacn2.5+123
+```
+
+A normal channel that is part of a wide channel can not be mapped individually.
+
+#### Known bugs / problems
+
+The DMX start code of transmitted and received universes is fixed as `0`.
+
+The (upper) limit on packet transmission rate mandated by section 6.6.1 of the sACN specification is disregarded.
+The rate of packet transmission is influenced by the rate of incoming mapped events on the instance.
+
+Universe synchronization is currently not supported, though this feature may be implemented in the future.
+
+To use multicast input, all networking hardware in the path must support the IGMPv2 protocol.
+
+The Linux kernel limits the number of multicast groups an interface may join to 20. An instance configured
+for input automatically joins the multicast group for its universe, unless configured in `unicast` mode.
+This limit can be raised by changing the kernel option in `/proc/sys/net/ipv4/igmp_max_memberships`. \ No newline at end of file