1 files changed, 101 insertions, 0 deletions
diff --git a/docs/physical-control.rst b/docs/physical-control.rst
new file mode 100644
index 0000000..743ed89
--- /dev/null
+++ b/docs/physical-control.rst
@@ -0,0 +1,101 @@
+=================================
+Using physical controls (via OSC)
+=================================
+
+Starlet's OSC implementation uses liblo via Guile-OSC.  You can use Guile-OSC
+procedures directly for many things.  Starlet provides utilities for
+higher-level control primitives.
+
+Start OSC by creating a server thread.  This will receive OSC method calls from
+other programs.  You can customise the port number and protocol (UDP vs TCP) as
+you need::
+
+  (define osc-server (make-osc-server-thread "osc.udp://:7770"))
+
+You'll also need to create an OSC address object for each external program that
+will receive OSC calls from Starlet::
+
+  (define controller (make-osc-address "osc.udp://localhost:7771"))
+
+Now, you can call external OSC methods like this::
+
+  (osc-send controller "/my/controller/led/4/set-colour" 'red)
+
+You can also create methods of your own, like this example which reloads a cue
+list on a button press::
+
+  (add-osc-method
+    osc-server
+    "/controller/buttons/30/press"
+    ""
+    (lambda ()
+      (reload-cue-list! pb)
+      (reassert-current-cue! pb)))
+
+See the manual for `Guile-OSC <https://github.com/taw10/guile-osc>`_ for more
+information about this part.
+
+
+High-level controls
+===================
+
+The functions described below expect the high-level OSC interface as
+implemented in `x1k2-midi-osc-alsa <https://github.com/taw10/x1k2-midi-osc-alsa>`_.
+See the manual for more information about the protocol.  The sections below
+describe how to use them in Starlet.  Since they need bi-directional
+communication, you have to provide an OSC server and the OSC address for the
+controller.
+
+
+Selection buttons
+-----------------
+
+This gives you a button that adds a fixture or group to the selection when
+pressed.  If the button has LEDs, they will be lit orange when selected, and
+red otherwise::
+
+  (osc-select-button front-wash osc-server controller-addr "/controller/buttons/18")
+
+
+Playback controls
+-----------------
+
+This lets you control a playback object with buttons, which will light up to
+show when a cue is running.  The buttons are (respectively, in argument order)
+go, stop and back::
+
+  (osc-playback-controls pb osc-server controller "/controller/buttons/102" "/controller/buttons/32" "/controller/buttons/28")
+
+
+States on fader (submasters)
+----------------------------
+
+You can put an entire state on a fader.  Non-intensity parameters will be
+asserted only when the fader is up (non-zero).  If it's not already there, the
+fader will need to be picked up at the bottom of its run::
+
+  (osc-state-fader osc-server controller "/controller/faders/4"
+                   (lighting-state
+                     (at mhL mhR colour (rgb 40 20 70))
+                     (at mhL mhR 100)
+                     (at front-wash 100)
+                     (at domeL domeR 100)))
+
+
+Parameter encoders and potentiometers
+-------------------------------------
+
+These give you physical control of an individual parameter in the programmer
+state.  LEDs will be used to indicate whether any of the currently selected
+fixtures have the named parameter.
+
+The simplest form is an encoder.  This increases or decreases the parameter
+value when turned.  Push and turn to make finer adjustments::
+
+  (osc-parameter-encoder intensity osc-server controller "/controller/encoders/102")
+
+
+Potentiometers are the same, but include a soft pickup mechanism because the
+physical position might not match Starlet's view of the position::
+
+  (osc-smart-potentiometer color-temperature osc-server controller "/controller/potentiometers/4")