aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--README.md76
1 files changed, 72 insertions, 4 deletions
diff --git a/README.md b/README.md
index 83b6f52..1580b79 100644
--- a/README.md
+++ b/README.md
@@ -24,10 +24,22 @@ A section may either be a *backend configuration* section, started by `[backend
an *instance configuration* section, started by `[<backend-name> <instance-name>]` or a *mapping*
section started by `[map]`.
+The `[map]` section consists of lines of channel-to-channel assignments, reading like
+
+```
+instance.target-channel = instance.source-channel
+```
+
+Assignments are one-way only, so to create a bi-directional mapping two assignments are needed.
+An example configuration can be found in [monster.cfg](monster.cfg).
+
The options accepted by the implemented backends are documented in the next section.
### 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 |
@@ -37,17 +49,63 @@ The options accepted by the implemented backends are documented in the next sect
#### Instance configuration
+| Option | Example value | Default value | Description |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `net` | `0` | `0` | ArtNet net to use |
+| `uni` | `0` | `0` | ArtNet universe to use|
+| `output` | `true` | `false` | Controls whether ArtNet frames for this universe are output |
+| `dest` | `10.2.2.2` | `255.255.255.255` | Destination address for sent ArtNet frames |
+
+#### 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
+```
+
+#### Known bugs / problems
+
+Currently, no keep-alive frames are sent and the minimum inter-frame-time is disregarded.
+
### 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
-### The `osc` backend
+| 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 |
-#### Global configuration
+MIDI device names may either be `client:port` portnames or prefixes of MIDI device names.
-#### Instance configuration
+#### 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 `<type><channel>.<index>`.
+
+Example mapping:
+```
+midi1.cc0.9 = midi2.note1.4
+```
+
+### The `osc` backend
+
+TBD
## Building
@@ -61,7 +119,17 @@ support for the protocols to translate.
* libasound2-dev
* A C compiler
+* GNUmake
-### Building
+### Build
Just running `make` in the source directory should do the trick.
+
+## Development
+
+The architecture is split into the `midimonster` core, handling mapping
+and resource management, and the backends, which are shared objects loaded
+at start time, which provide a protocol mapping to instances / channels.
+
+The API and structures is more-or-less documented in (midimonster.h)[midimonster.h],
+more detailed documentation may follow.