From: Nathaniel Wesley Filardo Date: Thu, 25 Mar 2010 06:16:44 +0000 (-0400) Subject: Update interactivecommands notes X-Git-Url: https://hydra-www.ietfng.org/gitweb/?a=commitdiff_plain;h=b5cbc6679c24aaa13472ec7e6cdad54957ae616d;p=acmetensortoys-chiptunes Update interactivecommands notes --- diff --git a/docs/interactivecommands b/docs/interactivecommands index 993113c..4974fea 100644 --- 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.