Interface Manual: Command Descriptions
The computer that is connected to the Chroma or Chroma Polaris via the interface cable communicates with the it by sending and receiving commands. A command consists of:
- A byte that specifies the command. If the command applies to one of the eight logical instruments, the instrument number is encoded in this byte, too.
- Zero or more bytes that specify parameters of the command. Although most commands require specific numbers of parameters, a few commands are variable in length.
Certain conventions are adhered to in the command language:
- Undefined commands are considered to be No Operation commands; that is, undefined commands are ignored. All No Operation command have no parameters.
- Command code zero and command code FF (hex) will always be No Operation commands, even for future instruments that utilize this interface.
- Command code 1 will always be an Identification command, for these and any other instruments utilizing this interface.
- If a two-byte quantity (such as a memory address) is to be transferred, it is sent most significant byte first, just the way you would write it on paper.
- If a command is variable in length, one of the operands specifies the variable number of data bytes. This is not the same as the length of the command, as the count does not include the command code, the length byte, or any other fixed parameters for the command. The Peek command is a good example of this.
- If a command is variable in length, the length byte of the command specifies the length as follows: values 1 to 255 represent byte counts of 1 to 255, and a value of zero represents a byte count of 256.
The commands fall roughly into three categories, according to protocol:
- There are those commands that are issued by the computer and require a specific response from the instrument.
- There are those commands that are issued by the computer and require a specific response from the Chroma. The response is always a command starting with the same code that was received from the controlling device.
- There are those commands that establish modes within the instrument that allow the Chroma to subsequently transmit unsolicited commands when certain events occur. The unsolicited commands will generally look like commands from the first group above.
The command set can also be split into two categories, according to destination:
- There are those commands that are addressed to the Chroma or Polaris as a whole. The lower command codes are assigned to these commands.
- There are those commands that are addressed to individual instruments. The higher command codes are assigned to these commands. The three least significant bits of these command codes hold the instrument number.
What follows is a complete description of each command, along with the numerical code (in hexadecimal) for each command byte.
No Operation 00
The only significance of this particular No Operation (as opposed to any of the undefined command codes) is that the Chroma sends this code upon power-up or reset. The Polaris doesn't.
Identification 01
The Chroma (or any future instrument) will respond with three bytes, an Identification command, a device code (1 for a Chroma, 2 for a Chroma Expander, 3 for a Polaris), and a software revision level code (see Appendix A).
Read Program 02 pp
The Chroma responds by transmitting program number pp. The information is transmitted as a Read Program command and 59 data bytes. (If pp is not between 0 and 50. the data bytes will be undefined.)
The Polaris supports this for compatibility, although the Open Object and Peek commands are more versatile. The differences are:
- If pp is zero, the contents of the Main Instrument is returned.
- If pp is not between 1 and 132, or if the program does not exist, a complete scratch program is returned.
- The 44-byte program that is returned is padded with 15 zero bytes.
Write Program 03 pp dd ... dd
The 59 data bytes dd ... dd are written into program number pp In the Chroma. (If pp is not between 0 and 50, the data will be accepted and ignored.)
The Polaris supports this for compatibility, although the Open Object, Create Object and Poke commands are more versatile. The differences are:
- If pp is zero, the Main Instrument is defined according to the new program.
- If pp is not between 1 and 132, the data is accepted and ignored.
- If program pp does not exist, it is created.
Load Packet 04
In the Chroma, one packet of information is read from the cassette interface, its error detection codes are checked, and the result will be returned via the interface in the form: 04 nn dd ... dd. nn specifies the number of data bytes in the packet, and the dd bytes are the contents or the packet. The first byte of the packet (the first dd byte) is always the packet ID, which identifies the type of packet. The packet ID for valid data is always non-zero. If an error occurs in the reading of the cassette, a special error packet with an ID of 0 is returned.
This command starts reading from the cassette immediately. This can cause a problem if the cassette was previously idle. See the Tape Space command below.
The types of packets that are currently defined, and the forms the Chroma return them in, include:
- Error Packet 04 02 00 nn
- The length is 2, the ID is 0, and nn will be 0 if a read error is detected or FF hex if the cassette was not running (or was shut off in Mid-operation).
- Program Packet 04 3C 01 dd ... dd
- The length is 60 (3C hex), the ID is 1, and the 59 bytes of data represent a Chroma program.
- Program Number Packet 04 02 02 nn
- The length is 2, the ID is 2, and the single byte of data consists of a valid program number (0 to 50). This type of packet appears, with a program number of 1, at the beginning of a tape recorded with SAVE ALL.
- Stop Packet 04 01 03
- The length is 1, the ID is 3, and there is no data in the packet. This type of packet appears at the end or a tape recorded with SAVE ALL.
- The Polaris does not support this command.
- Save Packet 05 nn dd ... dd
- In the Chroma, the packet dd ... dd containing nn bytes is written to the cassette. The first dd byte, which is the packet ID must be non-zero. The Chroma responds when the operation is complete with 05 00 if the operation completes normally or 05 FF if the cassette isn't running.
- This command must not be sent to the Polaris, as it does not support it.
- Read Parameter 06 pp nn
- Parameter number nn in program number pp is read and returned in the form 06 vv, where vv is the parameter value. If pp is not between 0 and 50, or if nn is not between 0 and 100, the vv value will be undefined. In the Polaris, a pp value of zero refers to the Main Instrument.
- Write Parameter 07 pp nn vv
- Parameter number nn in program number pp is set to value vv. If pp is not between 0 and 50, or if nn is not between 0 and 100, the vv value will be ignored. If the vv value is not within the range defined for the parameter, the result is undefined, except that the parameter will never be set to an illegal value.
- Panel Switch Off 08
- The "pane switch" referred to is the software switch which "connects" the Chroma panel to the interface. When the Chroma receives this, it will echo it and disconnect the panel from the interface.
- Panel Switch 0n 09
- When the instrument receives this, it will echo it and connects the panel to the interface. While this mode is in effect, the instrument transmits certain commands when the following events occur:
- Whenever a program is selected, a Define command will be transmitted for instrument 0 and either a Define or an Undefine command will be transmitted for instrument 1, depending upon the existence of a link.
- Whenever a parameter is changed, a Set Parameter command will be transmitted for instrument 0 in the Chroma. In the Polaris, the panel may be connected to the Main, Link or Sequencer Instrument, so a Set Parameter command may be transmitted for instrument 0, 1 or 2.
- Whenever the link balance is varied in the Chroma, Volume commands are transmitted for instruments 0 and 1.
- Whenever the Polaris sequencer plays a sequence, a Define is transmitted for instrument 2 (the Sequencer Instrument) at the start of the sequence, and an Undefine is transmitted at the end of the sequence. If the sequence contains parameter changes, Set Parameter commands are also transmitted.
- Note — In the Polaris, the Performance Switch (described below) must also be on if panel information is to be transmitted.
- Performance Switch Off 0A
- The "performance switch" referred to is the software switch that "connects" the various performance controls to the interface. When the Chroma receives this command, it echoes it and disconnects the performance controls from the interface.
- In the Polaris, the performance switch is really just a composite of the three Chroma Output switches accessible as Lower Function B 4, 5 and 6. The Performance Switch Off command simply turns off all three of these. This means that in the Polaris, the Performance switch gates everything, including panel information.
- Performance Switch On 0B
- When the instrument receives this, it echoes it and connects the performance controls to the interface. While this mode is in effect, the instrument transmits certain commands when the following events occur:
- Whenever a key is pressed on the keyboard, an Attack command is transmitted for instrument 0, 1 or both, depending upon the link mode and keyboard split.
- Whenever a key is released on the keyboard, a Release command is transmitted for instrument 0, 1 or both, depending upon the link mode and whether or not an attack had already been sent for the note.
- Whenever a lever, pedal or footswitch moves, the appropriate command is transmitted for instrument 0, and for instrument 1 if a link is in effect.
- When the Polaris sequencer is used, commands are transmitted for instrument 2.
- Peek 0C aa aa nn
- The Chroma responds by transmitting nn bytes from its internal memory starting at location aaaa. The response is in the form: OC nn dd ... dd - where the dd bytes are data bytes from ascending addresses.
- The Polaris responds by transmitting nn bytes from whatever object is currently open. If the object does not exist, or if bytes are requested from beyond the end of the object, zeros are returned.
- Peek Two Bytes 0D aa aa
- The Chroma responds by transmitting two bytes from its internal memory at locations aaaa and aaaa+1. The response is in the form: OD dd dd. This command is guaranteed to extract the two bytes concurrently, with no chance that the memory locations could be altered between the transmittal of each byte.
- The Polaris responds by transmitting two bytes from the currently open object at locations aaaa+1 and aaaa. The reversed order is due to the fact that the Polaris' computer stores LSBs before MSBs. If the open object does not exist, or if bytes are requested from beyond the end of the object, zeros are returned.
- Poke 0E aa aa nn dd ... dd
- In the Chroma, the nn data bytes dd ... dd are poked into the computer's address space starting at location aaaa. If an Unlock command has not been issued since the Chroma was powered up (or reset), the entire command will be read in and ignored.
- In the Polaris, the data bytes are poked into the currently open object if it is write enabled. If the object was not opened with writing enabled, or if the object does not exist, the entire command is read in and ignored. Bytes written beyond the end of the object are also ignored.
- Poke Two Bytes 0F aa aa dd dd
- In the Chroma, the two data bytes dd dd are poked into the computer's address space in locations aaaa and aaaa+1, respectively. If an unlock command has not been issued since the Chroma was powered up (or reset), the entire command will be read in and ignored. This command is guaranteed to poke the two bytes concurrently, without danger of the computer utilizing half of the old contents and half of the new contents.
- In the Polaris, the two data bytes are poked into the currently open object in locations aaaa+1 and aaaa, respectively. If the object was not opened with writing enabled, or if the object does not exist, the entire command is read in and ignored. Bytes written beyond the end of the object are also ignored.
- Tap Panel 10
- The Chroma's panel tapper is triggered, unless it has been disabled. The Polaris ignores this.
- Unlock 11 00 FF
- This sequence must be transmitted in order to enable the Poke and Poke Two Bytes commands in the Chroma. If the operand bytes are anything except 00 and FF, the Poke and Poke Two Bytes commands are subsequently disabled.
- Tape Space 12
- The cassette motor will be run for two seconds. Upon completion, the Chroma responds with 12 00 if the cassette was running, or 12 FF it was shut off.
- The purpose of this command is to allow startup time before other cassette operations. If a sequence of Save Packet commands are to be issued, they should be preceded by two Tape Space commands. In addition, if the packets are to be individually readable, they should be separated by two Tape Space commands. A single Tape Space command should be issued prior to a sequence of Load Packet commands.
- The Polaris ignores this, and does not return any response.
- Restore 13
- The Chroma or Polaris is restored to the state reflected by its panel settings. All instruments are undefined except instrument 0 and possibly 1, which are set up according to the currently selected program. The panel switch, performance switch and pressure switch are turned oft, and a Panel Switch Off, Performance Switch Off and Pressure Switch Off command are echoed, in that order. (See Appendix A for information on early revisions.)
- Pressure Switch Off 14
- The "pressure switch" referred to is the software switch that "connects" the keyboard pressure sensors to the interface. When the Chroma receives this command, it echoes it and disconnects the pressure sensors from the interface. This command is not implemented in early Chromas. See Appendix A.
- The Polaris does not implement a pressure switch, but does echo this.
- Pressure Switch On 15
- When the Chroma receives this, it will echo it and connect the pressure sensors to the interface. While this mode is in effect, the Chroma will send Pressure commands for instrument 0 and/or 1 whenever the pressure on a key is varied. See Appendix A.
- The Polaris does not implement a pressure switch, but does echo this.
- Tune Get 16
- The Polaris responds with 16 tt, where tt is the setting of the Master Tune control. The value is a signed byte scaled in 128ths of a semitone.
- The Chroma ignores this and does not return a response.
- Tune Set 17 tt
- The Polaris's Master Tune control is set to tt. The value is a signed byte scaled in 128ths of a semitone.
- This must not be sent to a Chroma, as it does not support it.
- Open Object 18 oo oo mm
- The Polaris selects object oooo as the open object, and returns a response in the form: 18 nn nn where nnnn is the number of bytes in the object, The mmm operand is the open mode. If this is odd, the object is write enabled. If this is even, the object is write protected.
- Object oooo need not exist when this is called. If it does not exist, the returned length is zero. If it is subsequently created, it will still be open.
- This must not be sent to the Chroma, as it does not support it.
- Create Object 19 oooo nnnn mm
- The Polaris creates object oooo with a length nnnn and a mode of mm. The object is not opened. In fact, this may be issued while a different object is open. The mm parameter should be zero.
- If the object already exists, or if there isn't enough memory, this is ignored. The result of this can be found by using Open Object.
- This must not be sent to the Chroma, as it does not support it.
- Delete Object 1A
- The Polaris deletes the open object if it exists and is write-enabled.
- The Chroma ignores this.
- Add Extension 1B
- The currently open object is added to the list of software extensions in the Polaris. This will crash the Polaris.
- The Chroma ignores this.
- Send Message 1C ss nn mm oo
- The Polaris inserts message mm and operand oo into internal data stream ss. If the message requires an instrument number, it is provided by nn.
- This must not be sent to the Chroma, as it does not support it.
- Get LED 1D nn
- The Polaris returns the state of LED nn in the form 1D ss where ss is 01 if the LED is on or 00 if it is off. If the LED is blinking, this has a 50/50 chance of returning either.
- Pressure 68+i kk pp
- Instrument i is told to set the key value pp. The pressure is an unsigned pressure input for note kk to number from 0 to 63.
- This command will be transmitted for instrument 0 and/or 1 by the Chroma if the pressure switch is on and the measured pressure on a depressed key changes. Pressure commands only occur between the corresponding Attack and Release commands for the same note.
- This command is not implemented in early Chromas. and must not be sent to them. Current Chromas will respond correctly to this command even if the Pressure Sensor option is not installed. See Appendix A.
- The Polaris applies pressure values to the pedal input on each voice. The Polaris only generates Pressure commands if its sequencer was used to record incoming Pressure commands. Since the Polaris has no pressure switch, such sequencer-generated commands are gated only by the Performance Switch.
- Information 70+i
- The Chroma responds by echoing the command and sending four information bytes. Currently, only the first byte is utilized, and contains the number of channel boards assigned to instrument i. The other three bytes are zero. The Polaris always returns a voice count of 6 in the first operand byte, even if fewer voices are allocated to the instrument, as this is the maximum number of notes that can be played on any logical instrument.
- Volume 78+i vv
- The volume of instrument i is set to vv. The value vv is a linear control from 0 to 255, and is nominally 255. Thus, to reduce the volume of an instrument 6db, the correct vv value would be 128.
- This command will be transmitted (for instruments 0 and 1) by the Chroma it the panel switch is on and the Link Balance parameter is varied. This is never sent by the Polaris unless its sequencer recorded incoming volume commands.
- Lever 1 80+1 vv
- Lever 2 88+1 vv
- The lever input on instrument i is set to vv, where vv is a signed 2's complement byte in the range -128 to +127. This range corresponds to the mechanical range from "pull" to "push", with 0 corresponding to "at rest".
- These commands will be transmitted (for instruments 0 and possibly 1) if the performance switch is on and the performer moves a lever. They may also be transmitted by the Polaris sequencer for instrument 2.
- Pedal 1 90+i vv
- Pedal 2 98+1 vv
- The pedal input on instrument i is set to vv, where vv is a number in the range 0 to 255. This range corresponds to the mechanical range from "heel" to "toe".
- These commands are transmitted (for instruments 0 and possibly 1) by the Chroma if the performance switch is on and the performer moves a pedal. The Pedal 1 command may also be transmitted by the Polaris sequencer for instrument 2.
- Footswitch 1 Down A0+i
- Footswitch 1 Up A8+i
- Footswitch 2 Down B0+i
- Footswitch 2 Up B8+i
- These commands activate or deactivate the footswitch functions on instrument i. Footswitch 1 is the right, or sustain, footswitch. Footswitch 2 is the left, or effects, footswitch.
- These commands are transmitted (for instruments 0 and possibly 1) if the performance switch is on and the performer presses or releases either footswitch. The Footswitch 1 commands may also be transmitted by the Polaris sequencer for instrument 2.
- The Polaris has no Footswitch 2.
- Define C0+i pp aa bb cc dd ee ff
-
Instrument i is defined according to program pp (which must be in the range 0 to 50). The remaining bytes specify initial values for the performance inputs:
- aa: lever 1
- bb: lever 2
- cc: pedal 1
- dd: pedal 2
- ee: volume
- ff: footswitches
- The footswitch byte uses the most significant bit to represent footswitch 1 and the next most significant bit to represent footswitch 2. A 0 means up, 1 means down.
- In the Chroma, if pp is not between 0 and 50, the instrument is defined according to program 0. Boards are reallocated as fairly as possible among defined instruments. If this command requires that one or more channel boards be robbed from another instrument, the computer will be kind enough to try and pick boards that aren't currently sounding.
- In the Polaris, if pp is not between 0 and 132, or if the program does not exist, a scratch sound results. Program 0 refers to the program in the Main Instrument. Also voices are not allocated to the instrument until notes are played.
- The Polaris ignores the pedal 2 operand and the second footswitch bit. In addition, if the pedal 1 operand is zero, the pedal input is initialized according to the Pedal Initial program.
- This command is transmitted for instrument 0 (and possibly 1) if the panel switch is on and the performer selects a program or a link. This command is transmitted for instrument 2 by the Polaris at the beginning of a sequence, or whenever the program is changed within a sequence.
- Undefine C8+i
- Instrument i is removed from operation. In the Chroma, any channel boards assigned to it are redistributed among any other instruments. In the Polaris, any voices assigned to instrument i are deallocated, and are allocated to other instruments when further notes are played.
- This command will be transmitted for instrument 1 if the panel switch is on and an unlinked program is selected while a link is in effect, or a link is cleared. This command is transmitted for instrument 2 by the Polaris at the end of a sequence.
- Attack D0+1 kk vv pp
- Instrument 1 is told to attack note kk with a velocity vv and an initial pressure pp. The key number is a signed, 2's complement byte that must be in the range -64 to +63. The Chroma's keyboard has a range from -32 to +32, with 0 being middle C, and can be transposed up or down an octave for a total range of -44 to +44. The Polaris' keyboard has a range from -36 to +24 and can be transposed up an octave for a total range of -32 to +36.
- In the Chroma, the velocity must be a number from 0 (softest strike) to 31 (hardest strike), and the pressure must be a number from 0 (no pressure) to 63 (full pressure). The excess high bits are ignored. The result of this command depends upon the keyboard algorithm parameter in the program that the instrument is defined by.
- In the Polaris, the velocity must also be a number from 0 to 31, but bit 5 of the vv byte has a special meaning. When set (that is, when 32 is added to the velocity), the attack is monophonic, meaning that it is directed to the most recently used voice for the instrument and not the least recently used voice.
- This command will be transmitted for instrument 0 and/or 1 by the Chroma if the performance switch is on and the performer presses a key. It may also be transmitted by the Polaris sequencer for instrument 2.
- Early Chromas transmit a pressure byte that is always zero, and ignore the received pressure byte. Current Chromas respond to pressure information received even if the Pressure Sensor option is not installed.
- Release D8+i kk vv
- Instrument i is told to release note kk with a velocity vv. In the Chroma, the result of this command depends upon the keyboard algorithm parameter in the program that the instrument is defined by. In the Polaris, all voices assigned to the note are released.
- This command is transmitted for instrument 0 and/or 1 if the performance switch is on and the performer releases a key. It may also be transmitted by the Polaris sequencer for instrument 2.
- Set Parameter E0+i nn vv
- Instrument 1 sets parameter nn to value vv. This does not affect the setting stored in the program originally used to define the instrument, which means that it won't affect other instruments defined according to the same program and it won't affect this instrument if it is redefined according to the same program.
- In the Chroma, this may not be used to set panel parameters, In the Polaris, this may be used to set panel parameters, although certain panel parameters (the Link Mode and Link Program Number) have no effect when set in this manner.
- If nn is out of range for the instrument, the command is accepted and ignored. If vv is not within the valid range for the selected parameter, the only guarantee is that the parameter will not be set to an illegal value.
- This command is transmitted for instrument 0 if the panel switch is on and the performer varies one of the parameters. It may also be transmitted by the Polaris sequencer for instrument 2.
- Status E8+i
- This command causes the Chroma to respond with: E8+i pp aa bb cc dd ee ff where the seven parameters represent the same quantities as the parameters of the Define command. If the instrument is undefined, the program number returned is FF and the remaining bytes are undefined. If the program number is 0, the Chroma returns the program number in the display, and the Polaris returns the program number that the Main Instrument was originally defined by.
- Squelch F0+i kk
- Any channels in instrument 1 that are assigned to key k are squelched by setting their envelopes to 0. This doesn't affect the channel assignment tables. Even latched channels may be squelched. If kk is -128 (80 hex) all channels are squelched.
- In the Polaris, the kk value is ignored, and all voices are squelched. The Polaris also transmits this at the end of a sequence for instrument 2 in place of an Undefine if the performance switch is on but the panel switch is off.