From c7964771d85e27685a21a3aafbd6331834868021 Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Tue, 4 Jul 2017 01:33:28 +0200
Subject: Document current OSC state

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 48f7659..a12f9e3 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,64 @@ output to the same channel again.
 
 ### The `osc` backend
 
-TBD
+This backend will allow 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 |
+| `dest`	| `10.11.12.13 8001`	| none			| Remote address to send OSC data to. Setting this enables the instance for output |
+
+Note that specifying an instance root speeds up matching, as packets not matching
+it are ignored early in processing.
+
+#### 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 multi-value channel that is to be output will need to be set up in the instance
+configuration (not yet implemented).
+
+#### 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
+
+Output is not yet implemented for this backend.
+
+Channels which are to be output require individual configuration to set their types and limits,
+as do input channels presenting a custom value range.
 
 ## Building
 
-- 
cgit v1.2.3