RPX MIDI Sysex Spec

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

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:

We would end up with this array of 8-bytes after Super-7-izing it.

2.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.

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.

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.

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

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

Device Implementation: Transmit/receive

4.4  System Bulk Messages

4.4.1  Request Bulk Dump

Procedure ID: 18h

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

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

Device Implementation: Receive

Return Messages

·  Success: ACK

·  Failure: NACK

4.5.1.1  Banks

4.5.2  Request Preset Names

Procedure ID: 21h

Device Implementation: Receive

Return Messages

·  Success: Receive Preset Names

·  Failure: NACK

4.5.3  Receive Preset Names

Procedure ID: 22h

Device Implementation: Transmit