X MIDI SysEx Protocol Specification
Author: Josh Kapp
Version: 2.2.4
Date Revised: 6/15/2006
1 Introduction
This document is a preliminary specification for a MIDI SysEx protocol for Lexicon MX, and USB-equipped DigiTech products. The information herein is intended for internal development purposes only, and is subject to change at any time.
2 Message Elements
2.1 SysEx Message Format
2.1.1 Message Structure
The general structure of a SysEx message is as follows:
<Header<Data<Checksum>F7
2.1.2 Header
SysEx data is intended to be exclusive to a specific system or device. To facilitate this each manufacturer of MIDI equipment is assigned a unique ID by the MMA. This ID must be in every SysEx message, following the F0h start of SysEx status byte. Following this byte, a manufacturer can place any data. However, a de facto standard exists that calls out a user-settable device ID for resolving between identical devices, and a Product ID for resolving a particular device model. Additionally, the RPx series uses a family ID to identify models who are similar in function or features. These fields collectively form the SysEx header as shown in table 2.1.2
Field / Bytes / Data / DetailsSysEx status byte / 1 / F0h / Start of SysEx message status byte
Manufacturer ID / 3 / 00h 00h 10h / DigiTech ID
Device ID / 1 / User defined / 0-16; 7E=All; 7F=All + merge
Family ID / 1 / Product specific / Product specific
Product ID / 1 / Product specific / Product specific
Table 2.1.2.1 DigiTech RPx SysEx header
2.1.3 Data
The MIDI specification requires that all MIDI bytes with MSB set are interpreted as special command bytes as in the case of the F0h and F7h SysEx start and end commands. Consequently, all non-command header and data bytes must have the MSB cleared. The header bytes do not present a problem because they are limited to 7Fh by design. However, data bytes may be arbitrary values, so a packing scheme must be used on them. Data fields in the message payloads are always transmitted in big-endian format (MSB first).
2.1.4 Super-7 Message Packing
The general packing method used on all newer DigiTech products is known as the 7 + 7 scheme (also referred to as “Super-7”). It treats data as blocks of seven bytes, where the MSBs of the bytes in a block are sent in one right-justified byte, followed by the lower bits 6-0 of each byte as right-justified bytes. Sending the MSBs first rather than last is more efficient because no padding bytes are required when fewer that seven data bytes are used.
For example, starting with the following array of 7 bytes:
0010 0110 / 1011 0001 / 1100 1010 / 0000 0010 / 0101 0000 / 1001 1011 / 0111 0111We would end up with this array of 8-bytes after Super-7-izing it.
00110010 / 0010 0110 / 0011 0001 / 0100 1010 / 0000 0010 / 0101 0000 / 0001 1011 / 0111 01112.1.5 Checksum
The checksum is a single-byte field containing the exclusive-OR of all bytes in the message from F0 through the last data byte. This technique provides both fast performance on an embedded microcontroller and reasonable reliability as an error checking method. In addition, the same exclusive-OR routine can be used to verify the checksum on the receiving end; the receiver can verify the message by exclusive-ORing the transmitted bytes as well as the checksum byte and expecting a result of zero.
2.1.6 Handshaking
Each SysEx procedure received by the hardware device that matches it’s Manufacturer and SysEx IDs will elicit some type of SysEx message in response from the unit. Usually this will be either a single Receive… message or an ACK (procedure 7Eh) or NACK (procedure 7Fh). In many cases the host MIDI device may ignore the acknowledgement if strict synchronization is not required.
However, some MIDI SysEx functions require multiple SysEx messages to complete. This allows smaller data packets to be used to accommodate slower microcontrollers and logically separates data into objects. When these messages are sent to the hardware unit the message flow must be arbitrated via handshaking using the ACK and NACK messages. The host should send out the first message in a series, and wait until an ACK or NACK is returned, then either continue with the next message or abort and handle the error.
2.1.7 Notification
When GUI mode is enabled, asynchronous notifications must be sent from a device whenever its state is changed without the explicit knowledge of a connected host. For instance, when a preset is stored via the unit’s front panel Store button, an editor/librarian should be notified in order to update its preset library items to reflect any changes. Most notifications are sent as some form of procedure 70h. Parameter changes, however, are small enough to be sent directly as parameter change messages (procedure 41h) when a notification is required.
In general, the rule is if the change originates from the device a notification must be sent; if it originates from a MIDI host that host should know about the change and requires no notification. This also makes host programming simpler because hosts don’t have to deal with message reflection that can cause circular updates. An exception to this rule arises when the hardware contains multiple virtual devices with unique device IDs. In this case some state variables may be shared between virtual devices but will be exposed to MIDI hosts as being per- virtual device. When a host changes the state on one virtual device, the state changes for all of them, so each virtual device not explicitly targeted by the command must send a notification for the change back to the host.
3 Parameters
3.1 Packing
3.1.1 Mag-7 Parameter Packing
Parameter values may vary greatly in their data sizes. To handle this efficiently the values are formatted using a scheme called Mag-7 (short for Magnificent 7 or Magnitude-7), which occurs prior to the standard Super-7 message formatting. Values can be sent within three size ranges using this technique.
1st Byte / 1st Byte Function(bits 0-7) / 2nd Byte / 3rd Byte / Subsequent bytes / Maximum Data Size
<80h / Data value / N/A / N/A / N/A / 7-bits
>80h / Data count / Data / (Data) / (Data) / 128 bytes
80h / none / Count MSB / Count LSB / Data / 65536 bytes
Table 3.1.1.1 Mag-7 parameter packing scheme
3.1.2 Parameter Types
Parameter values vary in content depending on the type of parameter being represented. All values are sent as integers, regardless of their visual representation. The following three types are used:
· Value
· ID
· Link
3.1.2.1 Value Parameters
Value parameters are the most commonly used parameter type. They are used to represent a continuous range of values, such as 0-99 to emulate an analog pot. Value parameters are also used where a collection of items in a table is displayed to the user. In this case, each integer value is an index into the collection. Regardless of the display range, Value parameters are always normalized to have a minimum of zero for SysEx transmission, with the max being the number of discrete positions minus one.
3.1.2.2 ID Parameters
ID parameters are virtually always used to represent effect types within an effect. In a sense, they are meta-parameters because each discrete value describes a set of parameters that become active when that value is selected. The parameter values are two-byte integer effect IDs which each correspond to a unique effect type.
3.1.2.3 Link Parameters
Link parameters are a special form of ID parameter. They are used to link a modifier (e.g., LFO, expression pedal, footswitch) to a parameter to be controlled. In version 0 of the protocol, each value is simply a 2-byte parameter ID. In version 1 and greater, the value is 3-bytes consisting of a Parameter position number in bits 16-23, and a parameter ID in the lower 16-bits.
4 Message Details
The RPx SysEx protocol is comprised of the following procedures. The data fields specified are preceded by the SysEx header and followed by the checksum and F7 command byte. The letter ‘n’ in a special column next to the message fields is used to indicate a loop over one or more fields where the ‘n’ is the loop counter. In the tables below, both the loop symbol and the count field the loop is based on appear in gray-filled cells.
4.1 Identification Messages
4.1.1 Request WhoAmI
Procedure ID: 1h
The payload fields indicated below specify how the header should be formatted by any responding device. This allows the requester to perform filtering by controlling the amount of specificity the response contains.
Field / Bytes / Details / SupportDesired Device ID / 1 / 0=Normal, 7E=All, 7F=All + merge
Desired Family ID / 1 / 0=Normal, 7F=Universal
Desired Product ID / 1 / 0=Normal, 7F=Universal
Device Implementation: Receive
Return Messages
· Success: Receive WhoAmI
· Failure: NACK
4.1.2 Receive WhoAmI
Procedure ID: 2h
In response to a Request WhoAmI the header for this message must be formatted as specified by the request message. However, the response message payload fields always represent the actual IDs of the device.
Field / Bytes / Details / SupportDevice ID / 1 / 0-15
Family ID / 1 / 1-7F
Product ID / 1 / 1-7E=Normal
OS Mode / 1 / 0=Normal, 1=Flash update / Version 1 and later
Protocol Version / 1 / Version 2 and later (Prior to version 2, the version can be inferred from message length)
Product Name / var / Null-terminated ASCII string / Version 2 and later
Physical Device Instance Name / var / Null-terminated ASCII string / Version 2 and later
GUID / 16 / Unique ID of unit / Version 2 and later
Virtual Device Instance Name / var / Null-terminated ASCII string / Version 2 and later
Device Implementation: Transmit
4.2 Configuration Messages
4.2.1 Request Device Configuration
Procedure ID: 8h
This message contains no data.
Device Implementation: Receive
Return Messages
· Success: Receive Device Configuration
· Failure: NACK
4.2.2 Receive Device Configuration
Procedure ID: 9h
Field / Bytes / Details / SupportOS version / 2 / BCD representation of a fixed-point version number where the radix lies between the bytes
Processor version / 2 / BCD representation of a fixed-point version number where the radix lies between the bytes
Protocol version / 1 / Zero-based SysEx protocol version implemented
Current preset bank / 1 / See table
Current Preset / 1 / 0 – (Max User Presets-1)
Media card present / 1 / 0=Not present; 1=Present / Version 1 and later
Device Implementation: Transmit
4.3 Global Parameter Messages
4.3.1 Request Global Parameters
Procedure ID: 10h
This message contains no data.
Device Implementation: Receive
Return Messages
· Success: Receive Global Parameters
· Failure: NACK
4.3.2 Receive Global Parameters
Procedure ID: 11h
Field / Bytes / Details / SupportParameter Count / 2 / Number of parameters to follow
n / Parameter n ID / 2 / Unique ID of a parameter type
Parameter position / 1 / Unique position of this parameter instance / Version 1 and later
Parameter n value / var / Mag7-packed parameter value
Device Implementation: Transmit/receive
4.4 System Bulk Messages
4.4.1 Request Bulk Dump
Procedure ID: 18h
Field / Bytes / Details / SupportFlow Control Flags / 1 / 0=Send continuously; >0= Wait for ACK following each transmitted message / Reserved in version 0—must be zero
Device Implementation: Receive
Return Messages
· Success
o Receive Bulk Dump Start
o Multiple preset messages (see section 4.6.3)
o Receive Global Parameters
o Receive Bulk Dump End
· Failure: NACK
4.4.2 Receive Bulk Dump Start
Procedure ID: 19h
Field / Bytes / Details / SupportMessage Count / 2 / Number of SysEx messages to follow
Approximate Data Count / 4 / Number of unpacked data bytes to follow
Preset Count / 1 / Number of user presets in the dump
Device Implementation: Transmit/receive
Return Messages
· Success: ACK
· Failure: NACK
4.4.3 Receive Bulk Dump End
Procedure ID: 1Bh
This message contains no data.
Device Implementation: Transmit/receive
Return Messages
· Success: ACK
· Failure: NACK
4.5 Preset Bank Messages
4.5.1 Receive User Preset Index Table
NOTE: This message has no corresponding request message because the index table is an abstraction of the physical layout of the preset bank in memory. The current table should always be assumed to be a contiguous range of indices in the range 0 to Preset Count-1.
Procedure ID: 20h
Field / Bytes / Details / SupportPreset Bank / 1 / See table / Version 1 and later
Preset Count / 1 / Number of indices n to follow
n
/ Preset n index / 1 / Zero-based index of a preset representing its position in the user preset list
Device Implementation: Receive
Return Messages
· Success: ACK
· Failure: NACK
4.5.1.1 Banks
Bank / Description / Details / Support0 / Factory / Factory (fixed) bank
1 / User / User bank
2 / Artist / Artist bank
3 / Media card / Media card (CF or other) / Version 1 and later
4 / Edit buffer / Current preset edit buffer. Preset index must be zero. / Version 1 and later
5 / Factory2 / Second factory bank / Version 1 and later
6 / External / External preset, such as a preset stored from a second virtual device (e.g., MX400 dual stereo mode). Notification only.
Preset index must be zero. / Version 2 and later
4.5.2 Request Preset Names
Procedure ID: 21h
Field / Bytes / Details / SupportPreset Bank / 1 / See table / Support
Device Implementation: Receive
Return Messages
· Success: Receive Preset Names
· Failure: NACK
4.5.3 Receive Preset Names
Procedure ID: 22h
Field / Bytes / Details / SupportPreset Bank / 1 / See table
Preset Count / 1 / Number of presets n to follow
n
/ Preset n name / var / Null-terminated ASCII string
Device Implementation: Transmit