STAGE PIANO SYS-EX IMPLEMENTATION Rev. 1.0 September, 1999 H. Chamberlin This document describes the MIDI System-Exclusive messages sent and recognized by version 1.0 and 1.2 of the Kurzweil Stage Piano controller board software. The level of detail is sufficient to implement a librarian program or even a complete editor. The reader is expected to be familiar with MIDI, bits, bytes, binary, and hexadecimal numbers and programming concepts like pointers and offsets. The Stage Piano's MIDI controller brain is a small 8-bit microprocessor (Mitsubishi M37451 which is a derivitive of the 6502) and the Stage Piano software is written entirely in assembly language. Consequently the data structures are not necessarily organized the way they might be had the software been written in a compiler language like C. In particular, hexadecimal values are represented in the following discussion as $XX where X is any hexadecimal digit (0-9, A-F). This is not only more compact than the "0Xxx" representation typically used by C, it is also far easier to read. Note that only the MIDI controller processor can be accessed via sys-ex. The processor on the sound board is only accessible via internal connection and sys-ex messages are not relayed to it. (See possible hack below.) Naturally, when playing around with the sys-ex commands to be described, one should be sure to have a secure backup copy of all user created setups in the unit. Kurzweil cannot be responsible for any loss of data that might occur while experimenting with these commands. We will start with an introduction which describes the general format of Stage Piano sys-ex messages. Then Part 1 will deal with the sys-ex messages that are used to save and reload setups and global parameters. This will provide the information necessary to implement a librarian type program. Part 2 will deal with the memory Peek and Poke commands which, along with the thorough descriptions of each parameter, will enable implementation of a full setup editor on an external computer. SYS-EX MESSAGE FORMAT SOX KID PID MTY BLN XXX XXX XXX ........ CKH CKL EOX where each 3-chracter field represents one MIDI byte. The fields are as follows: SOX - The standard MIDI Start of Esxclusive, $F0. KID - Kurzweil's coveted single byte manufacturer's ID, $07 PID - Stage Piano product ID, $63 ('S'+'P'-$40). MTY - Message type, 1 byte. Presently there are only three: $01 - Parameter Block $02 - Memory Peek $03 - Memory Poke BLN - Block number (present only for Message Type = 1) XXX .... XXX - variable length data block, see definitions below. CKH - High half of 14-bit checksum CKL - Low half of 14-bit checksum EOX - The standard MIDI End of Exclusive, $F7. Data Values in the XXX .... XXX bytes may be 7 bits, 8 bits, or 14 bits. A 7-bit data value is a single MIDI data byte. An 8-bit data value is a pair of MIDI data bytes, the first has the leftmost 4 bits of the data value and the second has the rightmost 4 bits. A 14-bit data value is a pair of MIDI data bytes. The first has the leftmost 7 bits of the data value and the second has the rightmost 7 bits. The checksum is the sum of 7, 8, and 14-bit data values following MTY through the data value immediately prior to the checksum data value accumulated in a 14-bit accumulator. This is very important, read it again carefully! Sys-ex message types 2 and 3 (memory Peek and Poke) may be received at any time. Message type 1, which is used to encode setup data, is only recognized when the unit is in Load mode (press Ld/Dump while in Edit mode). Note that sys-ex messages are buffered and must have a valid checksum before they are acted upon. Messages that don't match Kurzweil's ID ($07) and the Stage Piano's product ID ($63) and have a valid message type (1, 2, or 3) and have a correct checksum are thrown away with no visible indication. For initial debugging, it is recommended that Memory Peek be gotten to work first. You can find the major controller version number at $A033 and minor revision number at $A035 in ASCII. PART 1 - SETUP SAVE/LOAD MESSAGES --------------------------------------- When Setup EEPROM data are saved to a sequencer or reloaded from a sequencer, Parameter Block messages are used. The general format of Parameter Block messages is show below: MESSAGE TYPE $01 - Parameter Block ---------------------------------- SOX KID PID $01 BLN XX XX XX .... CKH CKL EOX $01 - Parameter Block message type BLN (7) - Block number of 16 data values that follow before the checksum. Caution! Must be 127 or less! XX (8) - Data values (remember, each is 2 MIDI data bytes) The numbers shown in () indicate the data type as described earlier in Sys-ExMessage Format. The block number, when multiplied by 16, gives the address in the EEPROM where that block came from or is going. The map below shows what is in each block. Only whole block transfers are supported. BLOCK # CONTENT ------- --------- 0 - 2 Internal Sounds mode setup 3 - 5 MIDI Setup #1 6 - 8 MIDI Setup #2 --- --- 96 - 98 MIDI Setup #32 99 Global Parameters 100 Effects parameters for Internal Sound #1 and #2 101 Effects parameters for Internal Sound #3 and #4 --- --- 115 Effects parameters for Internal Sound #31 and #32 116 - 126 -Not used, not sent by Dump routine- 127 Diagnostic Block (must be valid else user will receive an error message next power-up. See below.) Although a sys-ex dump from the Stage Piano will always be all used blocks in ascending order, the sys-ex loader will accept any number of blocks in any order. This permits considerable flexibility in a librarian program to mix and match parts of setups, effects specs, and globals. However the loader must receive block #127 (the diagnostic block) before it will exit Load mode. The 11 unused blocks may be freely used by a computer based editor for version 1.X Stage Piano controller software. However for version 2.X and higher, some of these blocks may be used for new features. The last block (#126) will remain reserved for external editor use. The Diagnostic Block is a set of 16 self-checking bytes. If the pattern is not valid, an error will be signalled at power-up indicating that the user setups may havbe been corrupted. Out of the 2^128 possible patterns, only 2^16 are valid. Thus without knowing the code, it is essentially impossible to formulate a valid diagnostic block. The pattern will change every time the non-volatile RAM diagnostic is run. The best way for a computer editor to handle the diagnostic block is to extract a valid one from a dump and always use it. When the Stage Piano receives a Parameter Block message, it is saved until the checksum is verified. After verification, the data is written into non-volatile memory where specified by the BLN field. If it is global data, the change will not take effect until the Diagnostic Block is received which must be the last block sent. If it is setup or effects spec data, it will not take effect until the setup containing that data is loaded into working storage, either by an operator front panel function or the unit receiving a MIDI Program Change that calls up that setup. (See Part 2 for a way to simulate button presses via sys-ex if one desires the just received setup parameters to become active automatically.) Note that EEPROM memory takes a finite amount of time to write data. At least 20 milliseconds should be allowed after a Parameter Block message before sending another one or any other MIDI messages for that matter. Note that in order to receive Parameter Block messages, the Stage Piano must be in Edit Mode and the Ld/Dmp button must have been pressed. As messages are received, the display is updated to show the type of data just received: [Int] = Internal Sounds setup [Uxx] = MIDI Setups 1-32 [Fxx] = Effects settings for sound xx [GbL] = Global parameters Load mode is exited and the display restored when the Diagnostic Block is received. Simulated button presses may be used to avoid the need for user interaction when loading setups. Following are location tables than can be used to extract and reload parts of the globals, setups, and effects specs. INTERNAL SOUNDS SETUP (SETUP 0) ------------------------------- NAME DISP SIZE PARMETER NAME NOTES ------- ---- ---- -------------- ---------------------------------- INTSND 0 1 Internal Sound 1-32, 0=NOC, -1=None MIDPROG 2 1 MIDI Program 0-127, -1=None MIDBANKL 4 1 MIDI Bank Sel Lo 0-127, -1=None MIDBANKH 6 1 MIDI Bank Sel Hi 0-127, -1=None MIDCHAN 8 1 MIDI Channel 1-16, 0=Don't send MIDXOPT 10 1 Destination 1=Int, 2=MId, 3=BOt LOKEY 12 1 Key Range Lo Actual key number HIKEY 14 1 Key Range Hi Actual key number XPOSE 16 1 Transpose -60 - +60 VELCURV 18 1 Velocity Curve 1 - 8 LRBND 20 1 A Ribbon Destination number 0-129, -1=Off URLRBND 22 1 B Ribbon Up Destination number 0-129, -1=Off LRRBND 24 1 B Ribbon Down Destination number 0-129, -1=Off SLDRD 26 1 Control SLider Destination number 0-129, -1=Off CCPDLD 28 1 Control Pedal Destination number 0-129, -1=Off RSWPDLD 30 1 Switch Pedal R Destination number 0-129, -1=Off LSWPDLD 32 1 Switch Pedal L Destination number 0-129, -1=Off KPD 34 1 (Key Pressure)* Destination number 0-129, -1=Off RBNMODES 36 1 Hold or Center A Ribbon, Bit 2, 1=Hold Hold or Zero B Ribbon Up, Bit 1, 1=Hold Hold or Zero B Ribbon Down, Bit 0, 1=Hold EFXINT 37 1 Internal Effects 0 - 9 RVBMIX 38 1 Reverb Wet/Dry 0-100, -1=No Change RVBMIX 39 1 Chorus Wet/Dry 0-100, -1=No Change * SP76 and SP88 lack the key pressure circuits. NOTE: MIDI Setups 1-32 are the same as above for the left zone. For parameters from MIDIPROG - KPD, the right zone is at the next higher displacement. GLOBAL PARAMETERS ----------------- NAME DISP SIZE PARMETER NAME NOTES ------- ---- ---- -------------- ---------------------------------- GPFLAGS 0 1 Local 0=Off, 1=On GPFLAGS 1 1 Stereo 0=Stereo, 1=Mono TOUCH 2 1 Touch 1 - 5 GPFLAGS 3 1 Effect 0=Off, 1=Snd, 2=Setup GPFLAGS 4 1 MIDI In 0=Normal, 1=Merge PCCHAN 5 1 Set Chg Chan 1-16, 0=Off TUNE 6 1 Tune -50 - +50 EFFECTS SETTINGS ---------------- NAME DISP SIZE PARMETER NAME NOTES ------- ---- ---- -------------- ---------------------------------- (Odd numbered sound) EFXINT 0 1 Internal Effects 0 - 9 RVBMIX 1 1 Reverb Wet/Dry 0-100, -1=No Change RVBMIX 2 1 Chorus Wet/Dry 0-100, -1=No Change (Even numbered sound) EFXINT 8 1 Internal Effects 0 - 9 RVBMIX 9 1 Reverb Wet/Dry 0-100, -1=No Change RVBMIX 10 1 Chorus Wet/Dry 0-100, -1=No Change PART 2 - MEMORY PEEK AND POKE MESSAGES -------------------------------------------- For advanced functions beyond what one would expect a librarian to do, the Stage Piano's sys-ex command set includes Memory Peek and Memory Poke commands. With these one can examine and alter the Stage Piano's working memory (actually any memory except the EEPROM) contents live and without user intervention or indeed knowledge. Of course with this power comes the responsibility to only make proper alterations of the proper locations. The information below is believed to be complete enough to implement any reasonable editing function. MESSAGE TYPE $02 - Memory Peek ------------------------------ SOX KID PID $02 ADRH ADRL CKH CKL EOX ADRH (8) - High byte of memory address to read ADRL (8) - Low byte of memory address to read Upon successful receipt of this message, a Memory Poke message with the content of ADRH,ADRL will be sent out the MIDI Out port (see below). A new Memory Peek message should not be sent until the reply from the previous message has been received completely. MESSAGE TYPE $03 - Memory Poke ------------------------------ SOX KID PID $03 ADRH ADRL DATA CKH CKL EOX ADRH (8) - High byte of memory address to write ADRL (8) - Low byte of memory address to write DATA (8) - Data value to write Upon successful receipt of this message, the data value will be written to ADRH,ADRL. Successive Memory Poke messages may be sent as quickly as desired. Although these messages are not very efficient for reading and writing large blocks of data, they are believed adequate for common editing applications. CHECKING THE VERSION All of the parameter size and location information given above and below is version dependent. Therefore it is prudent for a librarian or editor to check the software version number of the client Stage Piano. This is done with Memory Peeks to the following addresses: $A033 Version Number Single ASCII character giving the major Version $A035 Revision Numnber Single ASCII character giving the minor revision Global Parameter and Setup Parameter format, size, and location will not change within a version but might change from version to version. Addresses within working storage can change from revision to revision. For released software, these fields will always be ASCII digits, 0-9. For beta releases, the Revision Number may be greater than 9 (e.g., 1.17). The numbering sequence is 0-9, A-Z, [, \, ], ^, _, `, a-z. SIMULATING BUTTON PRESSES An editor may wish to trigger some action within the Stage Piano by simulating a button press. Other Kurzweil gear uses a special sys-ex message for this purpose but the Stage Piano uses a simpler method. Within working storage is a single byte called the Button Queue (BUTQ) at address $0021. Normally it is zero but when the scanner routine detects a button event, it places an event code there. A different part of the program periodically looks at the button queue and upon seeing a non-zero value, performs the appropriate action based on the event code and the current editing mode. When the action is complete, BUTQ is zeroed. There is no mechanism to prevent a collision between a user initiated button press and a simulated press via sys-ex. The possibility of collisions can be minimized however by using a Memory Peek to verify that BUTQ is zero before Poking a value into it. The meaning of most button codes is affected by the current operating mode. The best way to ascertain the current mode is to look at the front panel edit status LED image stored at LEDSON+8 ($0198). The bits are as follows: Bit 3 Internal Voices Mode Bit 2 MIDI Setups Mode Bit 1 Right Zone Bit 0 Left Zone The LED is on if the bit is a one. In Play Mode, both Zone LEDs are off, else the user interface is in Edit Mode. The user interface mode may be forced into Play Mode by generating Play/Edit button presses repeatedly until both zone LEDs turn off. Below is the full set of button codes. Please refer to the User Manual for the effect of each of these in each of the possible editing modes. ; BUTTON CODES 1 ROW SELECT 2 PLAY/EDIT 3 MODE/COL SEL 4 MIDI PC/STORE 5 ENTER (WHEN IN EDIT MODE) 6 DECREMENT (WHEN IN EDIT MODE) 7 INCREMENT (WHEN IN EDIT MODE) 9 DECREMENT REPEATED 10 INCREMENT REPEATED 11 PANIC DOWN 12 DEMO (ONLY RECOGNIZED IN PLAY MODE) 15 PANIC RELEASE 16 SOUND 1/2 SELECT (DIGIT 1 IN EDIT MODE) 17 SOUND 3/4 SELECT (DIGIT 2 IN EDIT MODE) 18 SOUND 5/6 SELECT (DIGIT 3 IN EDIT MODE) 19 SOUND 7/8 SELECT (DIGIT 4 IN EDIT MODE) 20 SOUND 9/10 SELECT (DIGIT 5 IN EDIT MODE) 21 SOUND 11/12 SELECT (LOAD/DUMP IN EDIT MODE) 22 SOUND 13/14 SELECT 23 SOUND 15/16 SELECT 24 SOUND 17/18 SELECT (DIGIT 6 IN EDIT MODE) 25 SOUND 19/20 SELECT (DIGIT 7 IN EDIT MODE) 26 SOUND 21/22 SELECT (DIGIT 8 IN EDIT MODE) 27 SOUND 23/24 SELECT (DIGIT 9 IN EDIT MODE) 28 SOUND 25/26 SELECT (DIGIT 0 IN EDIT MODE) 29 SOUND 27/28 SELECT (+/- IN EDIT MODE) 30 SOUND 29/30 SELECT (CANCEL IN EDIT MODE) 31 SOUND 31/32 SELECT (ENTER IN EDIT MODE) 128 Remote Setup Change received 129 Sys-ex Block message received OTHER USEFUL LOCATIONS IN WORKING STORAGE Below are the addresses of variables that may be useful to an external editor. Note that many of these may lead to a crash if manipulated inappropriately. NAME ADDRESS DESCRIPTION ------ ------- ------------------------ HFLAGS $0000 Bits 7:6 indicate keyboare length: 00=76, 01,11=88, 10=61 Bit 2 indicates presence of sound board GFLAGS $0001 Bit 7 is set if the current setup has been edited Bit 3 if forced to 1 will cause the state of all controls to be transmitted. Bit 0 0=Internal VOices mode, 1=MIDI Setups mode GPFLAGS $0002 Bit 7 0=Local Off, 1=Local Bit 6 0=Normal, 1=MIDI Merge Bits 1:0 00=Effects off, 01=sound specifies, 10=setup specifies TOUCH $0003 Active copy of Touch global parameter PCCHAN $0004 Receive program change channel TUNE $0005 Tune global parameter SXQIP $0007 SOund board transmit queue input pointer SXQOP $0008 SOund board transmit queue output pointer PDLSOFF $0014 Bits 7:6 are pedal states at power-on (7==right pedal) PDLSNOW $0015 Bits 7:6 are present pedal states SLDNOW $0018 Present control slider position CPNOW $0019 Present control pedal position PCHQ $0020 Remote setup change single element queue BUTQ $0021 Button code single element queue, 1-31=button code, 128= remote setup change received, 129=sysex data block received CURPARM $0037 Current parameter number for editors CURZONE $0038 Current zone for editors CURPARV $0039 Value of current parameter CUREDTD $003A State of "edited" flag on entry to editor SXQ $0170 Sound board transmit queue, 32 bytes (no running status) LEDSON $0190 Panel display and LEDs state , 9 bytes LEDSFSH $0199 Panel display and LEDs flashing, 9 bytes CURSMSND $01CD Current Internal Voices sound program number CURSETU $01CE Current MIDI Setups setup number RIBREADG $01D3 Last acted upon confirmed ribbon readings (4 bytes) RIBSTATE $0107 Touch state of the ribbons, 3=confirmed touch ACTIVE SETUP INFORMATION In the Stage Piano, user setups are stored in non-volatile memory. The currently active setup however is stored in Current Setup Memory. It is here that the built-in setup editing functions do their thing. A computer-based editor should do the same not only for simplicity but so that changes become effective immediately. The majority of parameters are in reality 2 parameters, one for each zone. These are called Zone Parameters and can be recognized as requiring 2 bytes of storage. Zone L would be at the lowest address and Zone R at the highest. Parameters requiring only a single byte are called Common Parameters and influence both zones. The Internal Voices mode only uses the Left Zone parameter values. The active setup is stored in locations $01F6 - 021D. The format is exactly the same as it is in non-volatile memory therefore the earlier given Internal Sounds Setup table can be used to identify the location of each parameter. Note that the run-time system and the built-in editors assume that parameters have legal values so a computer-based editor should assure that edited values remain legal. Illegal values may cause invalid MIDI messages to be sent to the MIDI Out port or sound board and could crash the controller or sound board software.