Update interactivecommands notes

diff --git a/docs/interactivecommands b/docs/interactivecommands
index 993113cba927f771f5ceae5e48908c5c80dfbb5c..4974feac3258b05be9b475172c990e17ff64edf5 100644 (file)
--- a/docs/interactivecommands
+++ b/docs/interactivecommands
@@ -1,6 +1,10 @@
-Speaking MIDI (because we can!):
+Speaking something like MIDI (TM):
 
-    MIDI uses a self-synchronizing protocol of seven bit data,
+    Disclaimer!  The protocol used here is a subset of the MIDI (TM)
+    standard but we probably can't label the device as MIDI (TM)
+    compliant, since it's their standard and we didn't pay them a dime.
+
+    MIDI (TM) 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
@@ -11,6 +15,15 @@ Speaking MIDI (because we can!):
     special case of steering the system through one channel, only
     data bytes need to be sent in some cases.
 
+    Pervasively, we use the "manufacturer ID" of 0x6F which is part of
+    the "other" range.  Yeah yeah, not standard, but it's $200/yr. for
+    a real identifier, which is absurd.  We don't answer 0x7F all-calls
+    except in response to identify.
+
+    We bake into the firmware an intial device ID.  End users' software
+    should make some effort to move device IDs on the local network to
+    a nonoverlapping namespace (see NRPNs below).
+
 Usage of channels:
 
     Channels 0 to 4 correspond to the on-chip oscillators.
@@ -78,7 +91,11 @@ Non-Registered Parameter Numbers:
     as 0).
 
     NRPN 0x00 : Assigning value of the form 0cccccpppppppp invokes
-                command c with parameter p on selected channel.
+                command c with parameter p on selected channel.  Note
+                that we require the trasmission order of fine and then
+                coarse.  If fine is ommitted, the parameter's bottom
+                seven bits are considered to be 0; the interpretation
+                happens on the setting of the coarse half.
 
     NRPN 0x10 : when set, specifies the target track for on-track
                 transitions.  This value is consulted at the track
@@ -86,11 +103,33 @@ Non-Registered Parameter Numbers:
                 providing ample opportunity to drive on-track channels
                 during playback.
 
-System Exclusive Mode:
+    NRPN 0x70 : Set the device ID (fine value only).  This number is
+                stored in EEPROM or FLASH and so this command should
+                be used only rarely!
+
+    NRPN 0x71 : Set the base channel to use, rather than 0.  Note that
+                for parsing simplicity, we only allow this to be 0, 4,
+                8, or 12.  Still, that should be enough to get out of
+                the way of other devices.
 
-    SEM data are prefixed with a command and channel identifier.
-    XXX we will need to figure those out, perhaps.
+System Exclusive Mode:
 
-    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.
+    SEM data are prefixed with the following header:
+        0xF0 (enter SYSEX), SYSEX ID, Device ID, Sub-id 1, Sub-id 2
+    As mentioned above, we use a non-standard manufacturer ID (SYSEX ID);
+    our device ID is as set by NRPN above.  SYSEX ID 7E and 7F are
+    reserved for standardized command vocabularies.
+
+    We define our own SYSEX command, namely PUSH IHEX, with command
+    sub-id1 and sub-id2 both 0x00.  Upon receipt of this command, the
+    device stops playing and enters a primitive bootloader, which reads
+    IHEX lines off the MIDI bus (ignoring all realtime messages received
+    and bailing on receipt of a non-RT status byte).  IHEX has the
+    convenient property that all of its data is 7-bit clean.
+
+    XXX Do we also want to support the more standard file transfer?
+
+    Identify appears to be defined already in 7E/06 01 and 7E/06 02.
+    We return with "device family code" and "device family number code"
+    of all zeros for the moment; our software revision may eventually
+    become meaningful.