Add first draft of docs/interactivecommands

diff --git a/docs/interactivecommands b/docs/interactivecommands
new file mode 100644 (file)
index 0000000..993113c
--- /dev/null
+++ b/docs/interactivecommands
@@ -0,0 +1,96 @@
+Speaking MIDI (because we can!):
+
+    MIDI uses a self-synchronizing protocol of seven bit data,
+    using the 8th bit of an octet to denote a status byte and
+    synchronization boundary.  Most messages are fixed width;
+    variable width SEM messages are terminated by the next
+    non-realtime status byte.
+
+    Note that MIDI has "running status" (avoids retransmitting the
+    status byte when it doesn't change between commands), so for the
+    special case of steering the system through one channel, only
+    data bytes need to be sent in some cases.
+
+Usage of channels:
+
+    Channels 0 to 4 correspond to the on-chip oscillators.
+
+    Despite that MIDI allows multiple notes to be playing on
+    a given channel at a time, we support only one note down at once,
+    which will be that given by the most recent Note On command.
+    That is, the device behaves something like a Mode 4 (omni off,
+    monophonic) device but perhaps without all the features.
+
+    Each oscillator can be in one of the following states:
+        "on-song"   -- following the selected song in real-time (default)
+        "on-track"  -- following a given track
+        "off-track" -- following a given instrument using given notes
+
+Commands understood at any time:
+
+8x  Note on chan x (note as is, velocity == 1/2 volume)
+    (That is, set oscillator active with tnote and volume as given)
+    Note that this is probably only useful when the song is off-track.
+
+Cx  Set instrument for channel.  See bank select below.
+
+XXX Bx control change parameters may be useful to map some of our
+XXX commands onto the standard vocabulary, hacks like NRPN
+XXX not withstanding.
+
+Bx 006. nn  Set NRPN coarse value to nn.
+Bx 032. 00  Set "bank" for instruments to be the song indirected table.
+Bx 032. 01  Set "bank" for instruments to be the first 127 instruments.
+Bx 032. 02  Set "bank" for instruments to be the next 127 instruments.
+Bx 038. nn  Set NRPN fine value to nn.
+Bx 098. nn  Set the NRPN fine index to nn.
+Bx 120. __  Go off-track.  Silences the channel immediately.
+Bx 122. off go on-track on next track transition.
+            target track specified by NRPN; see below.
+Bx 122. on  go on-song on next track transition.
+
+
+ {System common group}
+F0  Enter System Exclusive Mode (see below)
+F3  Song select (1 byte payload)
+        Specifies the song index for the next Start (see below)
+F7  Exit System Exclusive Mode
+
+ {Realtime group, no payloads}
+F8  System clock byte
+FA  Start
+        Takes all channels on-song immediately, resets track clock.
+FB  Continue
+FC  Pause
+FE  Active sense
+FF  System reset
+
+Commands understood when a channel is off-track:
+
+Non-Registered Parameter Numbers:
+
+    MIDI provides a 14-bit address space of 14-bit values called
+    "Non-Registered Parameters".  Since these bits are entirely
+    free-range, we use them to convey data outside the protocol down
+    to the device.
+
+    We so far use only the fine NRPN space (leaving the top 7 bits
+    as 0).
+
+    NRPN 0x00 : Assigning value of the form 0cccccpppppppp invokes
+                command c with parameter p on selected channel.
+
+    NRPN 0x10 : when set, specifies the target track for on-track
+                transitions.  This value is consulted at the track
+                transition for as long as the channel remains on-track,
+                providing ample opportunity to drive on-track channels
+                during playback.
+
+System Exclusive Mode:
+
+    SEM data are prefixed with a command and channel identifier.
+    XXX we will need to figure those out, perhaps.
+
+    The device stops playing and enters a primitive bootloader,
+    which reads IHEX lines off the MIDI bus.  IHEX has the convenient
+    property that all of its data is 7-bit clean.