From c037a339659fcc6030b3706f4119ebd5beee618e Mon Sep 17 00:00:00 2001 From: Nathaniel Wesley Filardo Date: Mon, 22 Mar 2010 00:45:36 -0400 Subject: [PATCH] Add first draft of docs/interactivecommands --- docs/interactivecommands | 96 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/interactivecommands diff --git a/docs/interactivecommands b/docs/interactivecommands new file mode 100644 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. -- 2.50.1