Skip to content

SysEx Configuration

paradajz edited this page Aug 24, 2018 · 165 revisions

This section will explain in depth OpenDeck System Exclusive protocol and how to configure the board using System Exclusive commands.

Note 1: numbers written like this represent hex notation

Note 2: this documentation uses official OpenDeck board for examples of values

Note 3: this documentation assumes the latest available firmware

Table of Contents

Message structure

System Exclusive (in further text: SysEx) is a special part of MIDI protocol. All MIDI messages except SysEx have defined length and each byte has specific meaning. In SysEx messages, the only defined bytes are START (F0) and END (F7). Any bytes in-between START and END are arbitrary and meaning of message depends purely on user which is implementing it. This is the reason most MIDI controllers which implement some kind of user-configuration use custom SysEx messages to configure the device in question. OpenDeck also implements custom protocol based on SysEx messages for its configuration. SysEx messages on OpenDeck differ from type to type, however, they all have several bytes in common. Those bytes are START, M_ID_1, M_ID_2, M_ID_3, MESSAGE_STATUS, MESSAGE_PART and END. This applies to both requests and response (except for few messages which don't return anything). Below is a list of all possible SysEx bytes used on OpenDeck:

  • START
  • M_ID_0
  • M_ID_1
  • M_ID_2
  • MESSAGE_STATUS
  • MESSAGE_PART
  • WISH
  • SPECIAL_REQUEST_ID
  • AMOUNT
  • BLOCK
  • SECTION
  • INDEX
  • NEW_VALUE
  • STOP

START byte

START byte always has value F0 and denotes start of SysEx message.

Manufacturer bytes

Although not strictly required, most MIDI manufacturers which implement its own SysEx protocol use up to three manufacturer bytes. Manufacturer bytes ensure that SysEx message doesn't end up on wrong MIDI controller. OpenDeck uses three bytes for manufacturer ID:

  1. M_ID_0 value: 00
  2. M_ID_1 value: 53
  3. M_ID_2 value: 43

If manufacturer bytes aren't specified (or they're wrong), OpenDeck won't respond. Each message must contain those bytes after START byte.

MESSAGE_STATUS byte

When requesting data, MESSAGE_STATUS always needs to be set to 0. When receiving response, that byte will change into 1 if request was valid, or specific error code if request was invalid. Exception is scenario when WISH byte is BACKUP. In that case, MESSAGE_STATUS byte is 0 in response if request was valid. See here.

MESSAGE_PART byte

SysEx buffer takes relatively large amount of space in firmware. In order to reduce buffer size, messages are limited to specified size. OpenDeck limits messages to 32 values. START, M_ID_1, M_ID_2, M_ID_3, MESSAGE_STATUS, MESSAGE_PART and END bytes do not count in. For instance, if a section has 64 parameters, and OpenDeck is configured to use 32 parameters per message, to access parameters 33-64, MESSAGE_PART byte needs to be set to 1 (parts start from 0). Special MESSAGE_PART value can be set to 7F when WISH byte is GET or BACKUP and AMOUNT byte is set to ALL. In those cases, board will return values for all message parts.

SPECIAL_REQUEST_ID

This byte is used on special messages to perform specific task. See here.

WISH byte

There are three options available:

  1. GET
  2. SET
  3. BACKUP

GET

WISH value: 0

Used to retrieve one or more parameters from the board.

SET

WISH value: 1

Used to set one or more parameters to new value.

BACKUP

WISH value: 2

This option is used when user wants to backup selected parameters. When this request is sent to board, board doesn't send usual response, but formats it to look like SET command instead. Using backup command it's easy to create a backup script.

AMOUNT byte

After GET or SET command, AMOUNT byte is needed. AMOUNT determines amount of parameters user wants to manipulate. There are two choices for AMOUNT byte:

  1. SINGLE
  2. ALL

SINGLE

AMOUNT value: 0

Used to get, set or backup single parameter within block section.

ALL

AMOUNT value: 1

Used to get, set or backup all parameters within block section.

Parameter configuration bytes

BLOCK, SECTION, INDEX and NEW_VALUE bytes are used to manipulate specific parameter (or parameters).

END byte

End byte denotes end of SysEx message and its value is always F7.

Message types

There are four types of SysEx messages on OpenDeck:

  1. Special requests
  2. Configuration messages
  3. Component info messages
  4. Status messages

Special requests

Special requests are split into two groups:

  1. Predefined requests
  2. Custom requests

Predefined requests are part of the core protocol, while custom requests are used-defined and can differ depending on implementation. Both groups have the same message structure:

  • START
  • M_ID_1
  • M_ID_2
  • M_ID_3
  • MESSAGE_STATUS
  • MESSAGE_PART
  • SPECIAL_REQUEST_ID
  • END

Values returned as a result of special requests are hardcoded and cannot be changed during runtime (no SET or BACKUP is available).

Predefined requests

There are three predefined requests:

  1. Handshake request
  2. Value size request
  3. Values per message request

Handshake request

SPECIAL_REQUEST_ID value : 1

Before attempting to use SysEx messages to configure OpenDeck board, this message must be sent to board. Handshake request enables SysEx configuration.

  • Request: F0 00 53 43 00 00 01 F7
  • Response: F0 00 53 43 01 00 F7

Like request, every response always has three manufacturer ID bytes after START byte. Fifth byte (01) is MESSAGE_STATUS byte. Since the request was valid, this byte is set to 1. Sixth byte (00) refers to MESSAGE_PART and is always 0 on special requests. Last byte is always SysEx STOP byte.

After the board responds to handshake request, user can continue with board configuration. While in SysEx configuration mode, board sends additional component IDs (see here) which aren't necessary during the normal operation, but are needed to identify component sending MIDI input. To reduce amount of data that is being sent, it is recommended to disable SysEx configuration after configuration is finished. To close SysEx connection, following message should be used:

  • Request: F0 00 53 43 00 00 00 F7
  • Response: F0 00 53 43 01 00 F7

Value size request

SPECIAL_REQUEST_ID value : 2

Depending on how the protocol is configured, requested and new values can have either one or two bytes. Two-byte values are necessary when there are parameters with index larger than 127, or when certain value can be larger than 127. OpenDeck board is configured for single-byte values, so this request will return 1. 2 is returned if board is configured to use two-byte protocol.

  • Request: F0 00 53 43 00 00 02 F7
  • Response: F0 00 53 43 01 00 01 F7

Returned data for each request starts after MESSAGE_PART byte. In this case, there is only one value to be returned (1).

Values per message request

SPECIAL_REQUEST_ID value : 3

  • Request: F0 00 53 43 00 00 03 F7
  • Response: F0 00 53 43 01 00 20 F7

Response returns 32 (20 in hex notation).

Custom requests

Custom requests on OpenDeck board are:

  1. Firmware version
  2. Hardware version
  3. Firmware and hardware version
  4. Number of supported components
  5. Reboot
  6. Bootloader mode
  7. Factory reset
  8. Enable processing
  9. Disable processing

Firmware version

SPECIAL_REQUEST_ID value : 56

This request will return firmware version currently running on board using three bytes. First byte is major version, second byte is minor version and third byte is revision.

  • Request: F0 00 53 43 00 00 56 F7
  • Response: F0 00 53 43 01 00 01 05 00 F7

When converted to decimal system, firmware version (as of date of this writing) reads as v1.5.0.

Hardware version

SPECIAL_REQUEST_ID value : 42

This request will return current version of OpenDeck board. First byte is board ID which specifies board variant. Current board variants are:

  • 0 - Official OpenDeck board
  • 1 - Arduino Leonardo
  • 2 - Arduino Mega
  • 3 - Arduino Pro Micro
  • 4 - Arduino Uno

Following three bytes are in same format as firmware version (major.minor.revision), although revision is unused in software. Because of this, value returned will always be 0.

  • Request: F0 00 53 43 00 00 42 F7
  • Response: F0 00 53 43 01 00 00 01 02 00 F7

Response indicates that current board variant is OpenDeck and its hardware revision is v1.2.0. For Arduino boards, hardware revision always reads as v1.0.0.

Firmware and hardware version

SPECIAL_REQUEST_ID value : 43

This request will return firmware and hardware version in one response.

  • Request: F0 00 53 43 00 00 43 F7
  • Response: F0 00 53 43 01 00 01 05 00 00 01 02 00 F7

Response indicates firmware version v1.5.0, official OpenDeck board variant and hardware revision v1.2.0. See dedicated firmware and hardware version message description for more details.

Number of supported components

SPECIAL_REQUEST_ID value : 4D

This request is used to find out maximum number of supported components on OpenDeck board.

  • Request: F0 00 53 43 00 00 4D F7
  • Response: F0 00 53 43 01 00 60 20 20 30 F7

Returned values start after 6th byte, in following order:

  • Maximum number of buttons (96) - This represents maximum number of digital inputs and analog inputs combined since analog inputs can be converted to digital inputs (see here).
  • Maximum number of encoders (32)
  • Maximum number of analog inputs (32)
  • Maximum number of LEDs (48)

Reboot

SPECIAL_REQUEST_ID value : 7F

This request will simply reboot the board.

  • Request: F0 00 53 43 00 00 7F F7
  • Response: No response

Bootloader mode

SPECIAL_REQUEST_ID value : 55

This request will first reset the board, and then boot the board into bootloader mode.

  • Request: F0 00 53 43 00 00 55 F7
  • Response: No response

More info about bootloader mode and updating firmware on board can be found here.

Factory reset

SPECIAL_REQUEST_ID value : 44

When this message is sent to board, the board will restore all configurable parameters back to default value and reboot cycle will be performed.

  • Request: F0 00 53 43 00 00 44 F7
  • Response: No response

Enable processing

SPECIAL_REQUEST_ID value : 65

When this message is sent to board, the data processing of digital inputs and outputs is enabled.

  • Request: F0 00 53 43 00 00 65 F7
  • Response: F0 00 53 43 01 00 F7

Disable processing

SPECIAL_REQUEST_ID value : 64

When this message is sent to board, the data processing of digital inputs and outputs is disabled.

  • Request: F0 00 53 43 00 00 64 F7
  • Response: F0 00 53 43 01 00 F7

Configuration messages

OpenDeck board hosts large amount of configurable persistent parameters. Configuration messages are used to configure those parameters and they have the following structure:

  • START
  • M_ID_0
  • M_ID_1
  • M_ID_1
  • MESSAGE_STATUS
  • MESSAGE_PART
  • WISH
  • AMOUNT
  • BLOCK
  • SECTION
  • INDEX*
  • NEW_VALUE*
  • STOP

Note: Bytes marked with asterisk aren't needed in certain scenarios.

BLOCK byte determines which part of the board user wants to configure. This byte comes after AMOUNT byte. There are five options available:

  1. MIDI
  2. Button
  3. Encoder
  4. Analog
  5. LED

Each block has its own sections for precise determination of parameter user wants to configure. Section is determined with SECTION byte. Inside section, INDEX byte must be specified to determine parameter user wants to manipulate, unless AMOUNT byte is ALL. If WISH byte is SET, NEW_VALUE must be specified to set new value to selected parameter.

MIDI block

BLOCK value: 0

MIDI block has the following sections:

  1. Features
  2. Merge

Features

SECTION value: 0

NEW_VALUE value range: 0-1 (disabled/enabled)

By default, all MIDI features are disabled. These are configurable MIDI features (parameters):

Standard note off

INDEX value: 0

When disabled, note on with velocity 0 will be sent as note off. If enabled, note off event will be sent instead.

Running status

INDEX value: 1

This setting applies only to DIN MIDI out and it's used to reduce MIDI traffic. Read more about this feature here. This setting can cause issues on older MIDI gear so it's best to leave it disabled. DIN MIDI state must be enabled in order to use this option.

MIDI merge state

INDEX value: 2

When enabled, incoming data from DIN MIDI in port can be merged with the data the board normally produces. DIN MIDI state must be enabled in order to use this option.

DIN MIDI state

INDEX value: 3

When enabled, all MIDI traffic is sent to DIN MIDI out port, and DIN MIDI In port is checked for incoming messages. When disabled, both ports are unused.

MIDI merge

SECTION value: 1

This section currently has only one parameter.

  1. Merge interface
Merge interface

INDEX value: 0

NEW_VALUE value range: 0-1

Specifies interface on which incoming data from DIN MIDI in port is forwarded to. Following options are available:

  • 0 - USB
  • 1 - DIN MIDI out

Button configuration block

BLOCK value: 1

INDEX value range: 0-n - represents button ID. Range depends on supported number of buttons and analog components combined since analog inputs can be converted to digital inputs. On official OpenDeck board, this number is 95. (total 96 components, 64 buttons and 32 analog components).

This block has the following sections:

  1. Type
  2. MIDI message
  3. MIDI ID
  4. On velocity
  5. MIDI channel

Type

SECTION value: 0

NEW_VALUE value range: 0-1 (momentary/latching)

Denotes button type. Type can be momentary, which means that note off is sent as soon as button is released, or latching, which means that note off is sent on second button press. All buttons are configured as momentary by default.

MIDI message

SECTION value: 1

NEW_VALUE value range: 0-D

The following message types are supported:

  • 0 - Notes
  • 1 - Program change
  • 2 - Control change
  • 3 - Control change with reset to 0 on button release
  • 4 - MMC Stop
  • 5 - MMC Play
  • 6 - MMC Record
  • 7 - MMC Pause
  • 8 - Realtime Clock
  • 9 - Realtime Start
  • 10 - Realtime Continue
  • 11 - Realtime Stop
  • 12 - Realtime Active Sensing
  • 13 - Realtime System Reset
  • 14 - Program Change, increment
  • 15 - Program Change, decrement
  • 16 - No MIDI message

All buttons are configured to send notes by default.

MIDI ID

SECTION value: 2

NEW_VALUE value range: 0-7F (0-127)

Denotes MIDI ID number. Default value is button number (button 0 has default ID 0, button 1 has default ID 1 etc.). ID meaning depends on message type. For notes, it specifies note. For control change, it specifies controller number. For program change, it specifies program. For MMC messages, it specifies channel. For Realtime messages this parameter is ignored.

On velocity

SECTION value: 3

NEW_VALUE value range: 1-7F (1-127)

Specifies velocity which will be sent when button is pressed. Default value is 127 for all buttons.

MIDI channel

SECTION value: 4

NEW_VALUE value range: 1-10 (1-16)

Specifies MIDI channel for specific button index. MIDI channel 1 is set as default for all buttons.

Encoder configuration block

BLOCK value: 2

INDEX value range: 0-n - represents encoder ID. Range depends on supported number of encoders. On official OpenDeck board, this number is 31 (total of 32 supported encoders).

This block has the following sections:

  1. Enabled/disabled
  2. Invert state
  3. Encoding mode
  4. MIDI ID
  5. MIDI channel

Two digital inputs are required to connect single encoder.

Enable or disable

SECTION value: 0

NEW_VALUE value range: 0-1 (disabled/enabled)

Enables or disables encoder. All encoders are disabled by default. Enabling encoder disables two buttons. To calculate encoder ID from a button ID see getEncoderPair function.

Invert state

SECTION value: 1

NEW_VALUE value range: 0-1 (not inverted/inverted)

When enabled, encoder will send inverted MIDI CC messages in different directions. Default option is disabled for all encoders.

Encoding mode

SECTION value: 2

NEW_VALUE value range: 0-1 (7Fh01h/3Fh41h)

Denotes encoder encoding mode. There two options:

  1. 7Fh01h encoding
  2. 3Fh41h encoding

Default option is 7Fh01h for all encoders.

7Fh01h encoding

When this mode is active, encoder will send CC message with value 127 in one direction, and value 1 in other direction.

3Fh41h encoding

When this mode is active, encoder will send CC message with value 63 in one direction, and value 65 in other direction.

MIDI ID

SECTION value: 3

NEW_VALUE value range: 0-7F (0-127)

Denotes the MIDI CC number for each encoder. Default value is same as encoder ID.

MIDI channel

SECTION value: 4

NEW_VALUE value range: 1-10 (1-16)

Specifies MIDI channel for specific encoder index. MIDI channel 1 is set as default for all encoders.

Pulses per step

SECTION value: 5

NEW_VALUE value range: 2-4 (2-4)

Specifies amount of steps encoder generates per step. Default value is 4 for all encoders.

Analog configuration block

BLOCK value: 3

INDEX value range: 0-n - represents analog ID. Range depends on supported number of analog components. On official OpenDeck board, this number is 31 (total of 32 supported analog components).

This block has the following sections:

  1. Enabled/disabled
  2. Invert state
  3. Type
  4. MIDI ID, LSB
  5. MIDI ID, MSB
  6. Lower CC limit, LSB
  7. Lower CC limit, MSB
  8. Upper CC limit, LSB
  9. Upper CC limit, MSB
  10. MIDI channel

Enable or disable

SECTION value: 0

NEW_VALUE value range: 0-1 (disabled/enabled)

Enables or disables analog input. By default, all analog inputs are disabled.

Invert

SECTION value: 1

NEW_VALUE value range: 0-1 (not inverted/inverted)

When enabled, analog input will send inverted MIDI CC messages in each direction. By default, this option is disabled for all analog inputs.

Type

SECTION value: 2

NEW_VALUE value range: 0-5

Analog inputs can behave differently based on selected type. Following types are available:

  • 1 - Potentiometer with CC message
  • 2 - Potentiometer with note message
  • 3 - FSR
  • 4 - Button
  • 5 - NRPN, 7-bit
  • 6 - NRPN, 14-bit
  • 7 - Pitch Bend

Default option is potentiometer with CC message for all analog inputs.

Potentiometer/CC

NEW_VALUE value: 0

Most common analog input. Sends CC values with 0-127 value range based on position.

Potentiometer/Note

NEW_VALUE value: 1

Same as potentiometer with CC message, except that it sends MIDI note with changing velocity instead of CC messages.

FSR

NEW_VALUE value: 2

Force-sensitive resistor. Sends MIDI note with velocity. Velocity depends on initially applied pressure. CC number for analog ID used as FSR is used as MIDI note. Note MIDI channel is used.

Button

NEW_VALUE value: 3

Standard button. Once analog input is configured as button, all settings that can be applied to button become valid. Button ID is calculated as sum of analog input and total number of buttons. For instance, if first analog input is configured as button (index 0), its button index is 64 (there are 64 button inputs on official OpenDeck board, 0-63). Analog inputs cannot be configured as encoders.

NRPN, 7-bit

NEW_VALUE value: 4

Sends 7-bit NRPN messages. 7-bit NPRN allows sending of CC messages with MIDI ID being 0-16383. CC value has standard range of 0-127.

NRPN, 14-bit

NEW_VALUE value: 5

Sends 14-bit NRPN messages. 14-bit NPRN allows sending of CC messages with MIDI ID being 0-16383. CC value has also range of 0-16383.

Pitch Bend

NEW_VALUE value: 6

Sends 14-bit Pitch Bend messages. Similar to CC message, just with larger range (0-16383).

MIDI ID, LSB

SECTION value: 3

NEW_VALUE value range: 0-7F (0-127)

Denotes lower 7 bits of MIDI ID. Default value is analog ID, ie. first analog input (index 0) has MIDI ID 0, second (index 1) has MIDI ID 1 etc. Meaning of MIDI ID varies depending on specified analog type. For Poteniometer/CC type, it specifies controller number for CC messages. For Potentiometer/Note and FSR types, it specifies note number. For 7-bit and 14-bit NPRN messages, it specifies lower 7-bits of controller number.

MIDI ID, MSB

SECTION value: 4

NEW_VALUE value range: 0-7F (0-127)

Denotes upper 7 bits of MIDI ID. Used only for 7-bit and 14-bit NPRN messages where it specifies upper 7-bits of controller number.

Lower CC limit, LSB

SECTION value ID: 5

NEW_VALUE value range: 0-7F (0-127)

Denotes lower 7-bits of minimum CC value. Default value is 0. If any other value is specified, CC range gets scaled.

Lower CC limit, MSB

SECTION value ID: 6

NEW_VALUE value range: 0-7F (0-127)

Denotes upper 7 bits of minimum CC value. Default value is 0. If any other value is specified, CC range gets scaled. Used only for 14-bit NRPN messages.

Upper CC limit, LSB

SECTION value ID: 7

NEW_VALUE value range: 0-7F (0-127)

Denotes lower 7 bits of maximum CC value. Default value is 127. If any other value is specified, CC range gets scaled.

Upper CC limit, MSB

SECTION value ID: 8

NEW_VALUE value range: 0-7F (0-127)

Denotes upper 7 bits of maximum CC value. Default value is 127. If any other value is specified, CC range gets scaled. Used only for 14-bit NRPN messages. Together with LSB byte of upper CC limit, default value is 16383 for those messages.

MIDI channel

SECTION value: 9

NEW_VALUE value range: 1-10 (1-16)

Specifies MIDI channel for specific analog index. MIDI channel 1 is set as default for all analog inputs.

LED configuration block

BLOCK value: 4

This block has the following sections:

  1. LED color testing
  2. LED blink testing
  3. Hardware parameters
  4. Activation note
  5. RGB enabled/disabled
  6. Control type
  7. MIDI channel

LED color testing

SECTION value: 0

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 47 (total of 48 supported LEDs).

NEW_VALUE value range: 0-7 (0-7)

This setting isn't persistent, that is, when board is rebooted all LEDs are off. NEW_VALUE byte represents LED color. Table below shows correct values for specific colors.

NEW_VALUE LED color
0 Off (no color)
1 Red
2 Green
3 Yellow
4 Blue
5 Magenta
6 Cyan
7 White

When testing single color LED, color setting is ignored. When using GET message in this section for single color LED, Red color is returned (value 1).

LED blink testing

SECTION value: 1

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 47 (total of 48 supported LEDs).

NEW_VALUE value range: 0-1 (0-1)

This setting isn't persistent, that is, when board is rebooted all LEDs are off. LED must be turned on for this setting to take any effect.

Board supports up to 48 single color LEDs, or 16 RGB LEDs.

Hardware parameters

SECTION value: 2

INDEX value range: 0-2

LED block has several hardware parameters which can be configured.

  1. Fade time
  2. Start-up animation
Fade time

INDEX value: 1

NEW_VALUE value range: 0-A (0-10)

Speed at which LEDs reach on or off state. Default value is 0, which means fading is disabled by default.

Start-up animation

INDEX value: 2

NEW_VALUE value range: 0-1 (enabled/disabled)

Start-up animation. When enabled, all connected LEDs will slowly turn on and then turn off. Default value is 0 (disabled).

Activation ID

SECTION value: 3

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 47 (total of 48 supported LEDs).

NEW_VALUE value range: 0-7F (0-127)

Sets the MIDI note/CC number which controls the LED. By default, activation note is same as LED ID, so, activation note for LED with index 0 is 0, note for LED with index 1 is 1 etc. For more info about controlling LEDs, see here.

RGB enable or disable

SECTION value: 4

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 48. Even though number of supported RGB LEDs is total number of LEDs divided by 3, this command takes as an argument total number of LEDs. Reason for this is to enable copying of MIDI channel, local control and activation ID parameters from current calculated RGB LED index/color to other two LEDs (RGB LED is three normal LEDs handled as one LED in firmware). For instance, RGB LED 1 is actually single LED 1, 9 and 17. As an example, LED 1 has assigned MIDI channel 1, LED 9 has MIDI channel 2 and LED 17 has MIDI channel 3. If RGB LED enable command is requested for LED 17, LEDs 1, 9 and 17 will all have MIDI channel 3. Same is valid for local control and activation ID parameters.

NEW_VALUE value range: 0-1 (disabled/enabled)

Enables or disables RGB LED. All RGB LEDs are disabled by default. Enabling RGB LED disables three single LEDs. To find RGB ID from single LED ID, see getRGBID function.

Control type

SECTION value: 5

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 47 (total of 48 supported LEDs).

NEW_VALUE value range: 0-5

Specifies LED control type. The following LED control types are available:

  • MIDI in, Note+CC (NEW_VALUE: 0)
  • Local - Note (NEW_VALUE: 1)
  • MIDI in, CC+Note (NEW_VALUE: 2)
  • Local - CC (NEW_VALUE: 3)
  • MIDI in, Program change (NEW_VALUE: 4)
  • Local - Program change (NEW_VALUE: 5)

See LED control section for more details.

Activation velocity

SECTION value: 6

INDEX value range: 0-n - represents LED ID. Range depends on supported number of LEDs. On official OpenDeck board, this number is 47 (total of 48 supported LEDs).

NEW_VALUE value range: 1-127

Specifies velocity which will turn on single-color LED. Default value is 127. Any other velocity other than configured one will turn the LED off. For RGB LEDs, velocity-table is used.

MIDI channel

SECTION value: 7

NEW_VALUE value range: 1-10 (1-16)

Specifies incoming MIDI channel which will control specific LED index. MIDI channel 1 is set as default for all LEDs.

Component info messages

Component info messages have similar structure to special requests:

  • START
  • M_ID_0
  • M_ID_1
  • M_ID_2
  • MESSAGE_STATUS
  • MESSAGE_PART
  • SPECIAL_MESSAGE_ID
  • BLOCK
  • INDEX
  • END

MESSAGE_STATUS is always 01(ACK). SPECIAL_MESSAGE_ID value: 49.

BLOCK is the block ID of component that is sending MIDI data - button (1), encoder (2) or analog (3).

INDEX is the component ID.

Unlike all other special messages, this message isn't sent to board - it's received from the board. This message is sent when SysEx configuration is enabled. It's used primarily for identifying component sending MIDI data.

Let's take a look at following scenario:

User has enabled analog input 1 (index 0).

  • Request: F0 00 53 43 00 00 01 00 03 00 00 01 F7

When user moves potentiometer (default option for analog input), BLOCK byte in Component info message will be 3, since that is analog block ID, and INDEX byte will be 0, since user has enabled analog input 1 (index 0).

  • Component info message: F0 00 53 43 01 00 49 03 00 F7

This doesn't seem useful at first, but let's take a look at another example:

User wants to set CC number for potentiometer 1 (index 0) to 5.

  • Request: F0 00 53 43 00 00 01 00 03 03 00 05 F7

Now, potentiometer sends CC 5. If the board was already enclosed (easy access isn't possible) and user wants to change CC for that potentiometer again, cable from potentiometer would had to be tracked to board. When SysEx is turned on, component info message sends the component ID.

The process is the same for buttons and encoders.

Status messages

Each request sent to board receives response (except for factory reset and reboot requests). When board sends response, it sets MESSAGE_STATUS byte to value 1 if request was valid (or 0 if WISH byte is BACKUP), or other value if request was invalid. MESSAGE_STATUS has 13 possible states:

  • 0 - Request
  • 1 - Response/ACK (request is valid)
  • 2 - Status error
  • 3 - Handshake error
  • 4 - Wish error
  • 5 - Amount error
  • 6 - Block error
  • 7 - Section error
  • 8 - Part error
  • 9 - Index error
  • A - New value error
  • B - Message length error
  • C - Write error

Request

Code: 0

Each request to the board must contain REQUEST (0) value in MESSAGE_STATUS byte.

Response (ACK)

Code: 1

Request was valid if response sets MESSAGE_STATUS to ACK (1).

Status error

Code: 2

This error happens when MESSAGE_STATUS isn't REQUEST (0) in request.

  • Response: F0 00 53 43 02 MESSAGE_PART F7

Handshake error

Code: 3

This error is returned when request is correct, but handshake request hasn't been sent to board (or SysEx connection has been closed).

  • Response: F0 00 53 43 03 00 F7

Wish error

Code: 4

This error is returned when WISH is anything other than GET, SET or BACKUP.

  • Response: F0 00 53 43 04 MESSAGE_PART F7

Amount error

Error code: 5

This error is returned when AMOUNT is anything other than SINGLE or ALL.

  • Response: F0 00 53 43 05 MESSAGE_PART F7

Block error

Error code: 6

This error is returned when BLOCK byte is incorrect.

  • Response: F0 00 53 43 06 MESSAGE_PART F7

Section error

Error code: 7

This error is returned when SECTION byte is incorrect.

  • Response: F0 00 53 43 07 MESSAGE_PART F7

Part error

Code: 8

This error is returned when message part is incorrect.

  • Response: F0 00 53 43 08 MESSAGE_PART F7

Index error

Error code: 9

This error is returned when wanted parameter is incorrect.

  • Response: F0 00 53 43 09 MESSAGE_PART F7

New value error

Error code: A

This error is returned when NEW_VALUE is incorrect.

  • Response: F0 00 53 43 0A MESSAGE_PART F7

Message length error

Error code: B

This error is returned when request is too short.

  • Response: F0 00 53 43 0B MESSAGE_PART F7

Write error

  • Response: C

This error is returned when writing new value to board has failed. This can happen if EEPROM on board is damaged (less likely) or if new value is incorrect (more likely).

Message: F0 00 53 43 0C MESSAGE_PART F7

Configuration examples

GET command

Note: All GET examples assume default board configuration.

Example #1: MIDI ID for analog component 5

User wants to find out MIDI ID for analog component 5.

  • MESSAGE_STATUS: 0 (Request)

  • MESSAGE_PART: 0

  • WISH: GET (0)

  • AMOUNT: SINGLE (0)

  • BLOCK: Analog (3)

  • SECTION: MIDI ID (3)

  • INDEX: 5

  • Request: F0 00 53 43 00 00 00 00 03 03 05 F7

  • Response: F0 00 53 43 01 00 05 F7

When WISH is GET, wanted parameters are listed after MESSAGE_PART byte. In this case, MIDI ID for analog component 5 is 5, therefore, last byte is 5.

Example #2: Encoding mode for all encoders

User wants to find out encoding mode for all encoders. OpenDeck supports total of 32 encoders, and number of parameters per SysEx message is 32, so in this case, we can set MESSAGE_PART byte to 0.

INDEX byte doesn't need to be specified since AMOUNT is ALL.

  • Request: F0 00 53 43 00 00 00 01 02 02 F7
  • Response: F0 00 53 43 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F7

Response returned 32 values for 32 encoders. Since all encoders have default encoding mode set to 7Fh01h (0), all 32 values are 0.

Example #3: Notes for all buttons

User wants to get notes for all buttons. Official OpenDeck board supports 96 buttons (64 on digital inputs and 32 on analog). Since there can only be 32 parameters per message, user has two options. First one is to simply send two GET ALL requests, one with MESSAGE_PART set to 0, second with same byte set to 1 and third with MESSAGE_PART being 2. Second option is to set MESSAGE_PART byte to special value, 7F. In that case, board will keep returning messages for selected section until all parameters are sent.

  • MESSAGE_STATUS: 0 (Request)

  • MESSAGE_PART: 7F

  • WISH: GET (0)

  • AMOUNT: ALL (1)

  • BLOCK: Buttons (1)

  • SECTION: MIDI ID (2)

  • Request: F0 00 53 43 00 7F 00 01 01 02 F7

  • Response 1: F0 00 53 43 01 00 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F F7

  • Response 2: F0 00 53 43 01 01 20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F F7

  • Response 3: F0 00 53 43 01 02 40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F F7

SET command

Example #1: Turn LED 1 on

User wants to turn LED 1 (index 0) on.

  • MESSAGE_STATUS: 0 (Request)
  • MESSAGE_PART: 1
  • WISH: SET (1)
  • AMOUNT: SINGLE (0)
  • BLOCK: LEDs (4)
  • SECTION: LED color testing (5)
  • INDEX: 0 (LED 1)
  • NEW_VALUE: 1

NEW_VALUE represents LED color. This example assumes that we're trying to turn single-color LED on so any value between 1 and 7 will turn the LED on (see LED color testing). To turn LED off, value 0 needs to be specified.

  • Request: F0 00 53 43 00 00 01 00 04 05 00 71 F7
  • Response: F0 00 53 43 01 00 F7

Example #2: Send program change on button 36

User wants to configure button 36 to send program change event instead of note event.

  • MESSAGE_STATUS: 0 (Request)

  • MESSAGE_PART: 1

  • WISH: SET (1)

  • AMOUNT: SINGLE (0)

  • BLOCK: Button (1)

  • SECTION: MIDI message (1)

  • INDEX: 4 (index 0 in second message part is button index 32, 4 is 36)

  • NEW_VALUE: Program change (1)

  • Request: F0 00 53 43 00 01 01 00 01 01 04 01 F7

  • Response: F0 00 53 43 01 01 F7

When WISH is SET, response contains only manufacturer ID bytes, message status and message part.

Example #3: MIDI channel 5 for all available channels

User wants to set all MIDI channels to channel 5.

  • MESSAGE_STATUS: 0 (Request)

  • MESSAGE_PART: 0

  • WISH: SET (1)

  • AMOUNT: ALL (1)

  • BLOCK: MIDI (0)

  • SECTION: Channels (1)

  • INDEX byte isn't needed since WISH is SET and AMOUNT is ALL.

  • NEW_VALUE: 05 05 05 05

  • Request: F0 00 53 43 00 00 01 01 00 01 05 05 05 05 F7

  • Response: F0 00 53 43 41 F7

When WISH byte is SET, and AMOUNT is ALL, all parameters within section must be specified. MIDI channel section has four channels, therefore four channels are listed after SECTION byte.

BACKUP command

Example #1: All hardware parameters for LED block

User wants to backup all parameter values for LED block, Hardware parameters section.

  • MESSAGE_STATUS: 0 (Request)

  • MESSAGE_PART: 7F (All parts)

  • WISH: BACKUP (2)

  • AMOUNT: ALL (1)

  • BLOCK: LEDs (4)

  • SECTION: Hardware parameters (0)

  • INDEX: No index necessary

  • NEW_VALUE No new value necessary

  • Request: F0 00 53 43 00 7F 02 01 04 00 F7

  • Response: F0 00 53 43 00 00 01 01 04 00 02 00 00 F7

Response can be sent back to board since it's converted to request.

You can’t perform that action at this time.