Add documentation about physical controls

1 files changed, 124 insertions, 0 deletions

diff --git a/docs/physical-control.rst b/docs/physical-control.rst
index 1305673..9f5b162 100644
--- a/docs/physical-control.rst
+++ b/docs/physical-control.rst
@@ -2,3 +2,127 @@
 Using physical controls (MIDI etc)
 ==================================
 
+Start MIDI control by creating a controller object.  You need to give the
+device node for the controller, and the MIDI channel to use::
+
+  (define controller
+    (make-midi-controller "/dev/snd/midiC1D0" 14)
+
+To send a MIDI "note on" command, e.g. to light an LED, use ``send-note-on``.
+There is also ``send-note-off``::
+
+  (send-note-on controller 25)
+  (send-note-off controller 25)
+
+Buttons
+=======
+
+You can assign a procedure to be called when a MIDI button is pressed::
+
+  (register-midi-note-callback!
+    controller
+    #:note-number 25
+    #:func (lambda ()
+             (reload-cue-list! pb)
+             (reassert-current-cue! pb)))
+
+Let's say you want to use a MIDI button to quickly select all the fixtures in
+your front wash.  You could assign a procedure with a call to ``sel`` inside
+(see `<basic-control.rst>`_ for more about ``sel``).  However, there is a
+helper procedure in module ``(starlet midi-control button-utils)``::
+
+  (select-on-button controller 32
+                    (list washL washM washR)
+                    #:ready-note 68)
+
+The ``#:ready-note`` is just a note to send, e.g. to light up an LED to
+indicate that the button is active - leave it out if you don't need it.  Use
+``#f`` as the fixture name to make a "deselect" button.
+
+There are similar utilities for creating *go*, *stop* and *back* buttons
+(see `<cue-list.rst>`_)::
+
+  (make-go-button controller pb 12
+                  #:ready-note 20
+                  #:pause-note 16)
+
+  (make-stop-button controller pb 24
+                    #:ready-note 24)
+
+  (make-back-button controller pb 28
+                    #:ready-note 28)
+
+With ``make-go-button``, the ``pause-note`` will be lit when the playback has
+been paused with ``stop!`` (see `<cue-list.rst>`_), otherwise the
+``ready-note`` will be lit.  On my controller (Allen and Heath XONE:K2), these
+notes light the same button in different colours.
+
+The ``ready-note`` for ``make-stop-button`` will be lit when a cue is running,
+i.e. when the playback can usefully be stopped.
+
+With ``make-go-button``, you can additionally use
+``#:min-time-between-presses`` to set a minimum waiting time (in seconds)
+between activations.  This sometimes helps with jittery fingers.  The default
+is 0.2 seconds.
+
+
+Putting a state on a fader
+==========================
+
+To simply assign a state to a fader::
+
+  (state-on-fader controller 19
+                  (lighting-state
+                    (at front-wash 100)
+                    (at domeL domeR 100)))
+
+The fader's control of the state will be completely separate to other states,
+i.e. it will not affect the contents of the programmer.  The programmer state
+will have priority over states on faders.
+
+
+Control map
+===========
+
+You can associate MIDI controls with fixture parameters, such that when a
+fixture is selected, those controls can be used to change the parameters in the
+programmer state.  Here's an example::
+
+  (set-midi-control-map!
+    controller
+    (fader    16 'intensity                      #:congruent 108  #:incongruent 72)
+    (jogwheel  0 'pan                            #:active 124)
+    (jogwheel  1 'tilt                           #:active 125)
+    (fader     4 (colour-component-id 'cyan)     #:congruent 120  #:incongruent 84)
+    (fader     5 (colour-component-id 'magenta)  #:congruent 121  #:incongruent 85)
+    (fader     6 (colour-component-id 'yellow)   #:congruent 122  #:incongruent 86)
+    (fader     7 'colour-temperature             #:congruent 123  #:incongruent 87))
+
+Use ``fader`` for MIDI *continuous control* parameters (CCs), which might
+physically correspond to faders or rotary potentiometers with a minimum and
+maximum value (distinct from *jogwheels* - see below).  You need to give the
+MIDI CC number, then the parameter which should be controlled.  To control a
+single component of the colour, use ``colour-component-id`` as shown in the
+example.
+
+Faders (and potentiometers) are somewhat awkward, because there's no guarantee
+that the fader will be in the position corresponding to the current value of
+the parameter it controls.  To avoid jumps, Starlet will only start changing
+the parameter value once the fader passes through the correct value.  This
+means that you might have to move the fader to "pick up" the value along its
+way.  The ``congruent`` and ``incongruent`` values are optional, but highly
+recommended.  They give the note numbers corresponding to two LEDs, one of
+which will be lit when the fader position is "congruent" with the underlying
+parameter value and moving the fader will change the value.  At other times,
+the ``incongruent`` LED will be lit to show that the fader needs to "pick up"
+the value.  Starlet will take care of getting this right even when you select
+multiple fixtures at once with different values, or when the underlying value
+is changed by some other means.
+
+This is somewhat awkward, but on the other hand potentiometers are cheap and
+your controller is likely to have a lot of them.  The alternative is to use
+``jogwheel``, which is for CCs which don't give a continuous value but rather
+either 0 or 127 to increase or decrease the value respectively.  This avoids
+the whole "congruence" issue.  For ``jogwheel``, you only need to give the CC
+number, the attribute to control, and an optional note to use for lighting an
+LED to indicate when the parameter is active.