From 4cd685b0eed80c0256cda3592cbb55bd512dde69 Mon Sep 17 00:00:00 2001 From: Nathaniel Wesley Filardo Date: Thu, 17 Jun 2010 01:09:25 -0400 Subject: [PATCH] Move interactivecommands to midimode It's unclear that we'll ever act on this, but it should be kept around --- docs/midimode | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/midimode diff --git a/docs/midimode b/docs/midimode new file mode 100644 index 0000000..4974fea --- /dev/null +++ b/docs/midimode @@ -0,0 +1,135 @@ +Speaking something like MIDI (TM): + + 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 + 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. + + 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. + + 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. 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 + transition for as long as the channel remains on-track, + providing ample opportunity to drive on-track channels + during playback. + + 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. + +System Exclusive Mode: + + 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. -- 2.50.1