SysEx Configuration

Igor edited this page Feb 11, 2017 · 111 revisions

All OpenDeck configuration is done using custom protocol written using MIDI System Exclusive commands. This document will explain in depth OpenDeck System Exclusive protocol and how to configure the board using System Exclusive commands.

Note: numbers written like this represent hex notation

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_1
  • 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, after which will return entire request with the difference on changed status byte (will be set to 1). This way, user can know when the request is done processing.

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 01 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 : 1

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 01 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 : 2

  • Request: F0 00 53 43 00 00 02 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. Number of supported components
  4. Reboot
  5. Bootloader mode
  6. Factory reset

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 00 01 41 F7

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

Hardware version

SPECIAL_REQUEST_ID value : 42

This request will return current version of OpenDeck board in same format as firmware version (major.minor.revision).

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

Hardware version for current OpenDeck board reads as v1.0.1.

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 40 20 20 30 F7

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

  • Maximum number of buttons (64)
  • 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.

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

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

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. This setting can cause issues on older MIDI gear so it's best to leave it disabled.

DIN MIDI in to USB MIDI out

INDEX value: 2

When enabled, all data received via DIN MIDI in port will be translated to USB MIDI.

Channels

SECTION value: 1

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

There are several configurable MIDI channels (parameters):

  1. Note channel
  2. Program change channel
  3. Continuous change channel
  4. Input channel

All channels are set to 1 by default.

Note channel

INDEX value: 0

Used by buttons and analog inputs configured as FSR or buttons.

Program change channel

INDEX value: 1

Used by buttons or analog inputs configured as buttons which are configured to send program change MIDI event instead of notes.

Continuous change channel

INDEX value: 2

Used by analog inputs configured as potentiometers and buttons configured as encoders.

Input channel

INDEX value: 3

Listening channel on which board receives MIDI messages.

Button configuration block

BLOCK value: 1

INDEX value range: 0-5F (0-95) - represents button ID

This block has the following sections:

  1. Type
  2. MIDI message
  3. MIDI ID

In total, there are 64 inputs on board for buttons, although additional 32 analog inputs can be converted to digital inputs (buttons), so total amount of buttons is 96.

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-1 (notes/program change)

When set to 1, instead of notes, button will send program change event on successive presses (momentary/latching modes are ignored). When set to 0, button will send note MIDI events. All buttons are configured to send notes by default.

MIDI ID

SECTION value: 2

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

Denotes note/program change MIDI number. Default value is button number (button 0 has default note 0, button 1 has default note 1 etc.).

Encoder configuration block

BLOCK value: 2

INDEX value range: 0-1F (0-31) - represents encoder ID

This block has the following sections:

  1. Enabled/disabled
  2. Invert state
  3. Encoding mode

Board supports up to 32 encoders. 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.

Analog configuration block

BLOCK value: 3

INDEX value range: 0-1F (0-31) - represents analog ID

This block has the following sections:

  1. Enabled/disabled
  2. Invert state
  3. Type
  4. MIDI ID
  5. Lower CC limit
  6. Upper CC limit

Board has total of 32 analog inputs.

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-2 (potentiometer/FSR/button)

Analog inputs can behave differently based on selected type. There are several types:

  1. Potentiometer
  2. FSR
  3. Button

Default option is potentiometer for all analog inputs.

Potentiometer

NEW_VALUE value: 0

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

FSR

NEW_VALUE value: 1

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

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 board, 0-63). Analog inputs cannot be configured as encoders.

MIDI ID

SECTION value: 3

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

Denotes MIDI CC number. Default value is analog ID, ie. first analog input (index 0) has MIDI ID 0, second (index 1) has MIDI ID 1 etc. If type is set to FSR or potentiometer, MIDI note with same value will be used instead.

Lower CC limit

SECTION value ID: 4

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

Denotes minimum CC value. Default value is 0. If any other value is specified, CC range gets scaled.

Upper CC limit

SECTION value ID: 5

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

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

LED configuration block

BLOCK value: 4

This block has the following sections:

  1. Hardware parameters
  2. Activation note
  3. RGB enabled/disabled
  4. Local LED control
  5. LED color testing
  6. LED blink testing

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

Hardware parameters

SECTION value: 0

INDEX value range: 0-2

LED block has several hardware parameters which can be configured.

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

INDEX value: 0

NEW_VALUE value range: 2-F (2-15)

Sets amount of time LED is on/off when LED is blinking. Specified value gets multiplied by 100, ie. if user sets blink time to 1, actual blink time is 100 ms. Default value is 2, that is, 200ms.

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 note and CC number

SECTION value: 1

INDEX value range: 0-2F (0-47)

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

INDEX value range: 0-2F (0-47)

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 getRGBaddress function.

Local LED control

SECTION value: 3

INDEX value range: 0-2F (0-47)

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

Enables or disables local LED control. When enabled, LEDs are controlled by buttons or FSR sensors connected to board. Activation note assigned to specific LED is converted to MIDI Note sent by button. For instance, if LED 1 (index 0) has activation note 10, and local LED control is enabled, button which sends MIDI note 10 will control the LED. LED state depends on received velocity. Buttons send velocity 127 when pressed, and 0 when released if they're configured as momentary, or 127 when pressed and 0 on second press if configured as latching. FSR velocity depends on initially applied pressure.

LED color testing

SECTION value: 4

INDEX value range: 0-2F (0-47)

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: 5

INDEX value range: 0-2F (0-47)

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.

Component info messages

Component info messages have similar structure to special requests:

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

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 00 00 53 43 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 your controller was already enclosed so that you don't have easy access to board, and you wanted to change CC for that potentiometer again, you wouldn't know its ID without tracking cable from potentiometer 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 CC number for analog component 5

User wants to find out MIDI CC number 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 CC number 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. OpenDeck supports 64 buttons. 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, and second with same byte set to 1. 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

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 state testing (4)
  • 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 04 00 71 F7
  • Response: F0 00 53 43 01 01 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: Enabled (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 1: F0 00 53 43 00 00 01 01 04 00 02 00 00 F7
  • Response 2: F0 00 53 43 01 7F 00 01 04 00 F7

Response 1 can be sent back to board since it's converted to request. Response 2 marks the end of message processing since MESSAGE_PART byte was set to value 7F

Example #2: Full backup

In this example, user wants to backup entire board configuration. To achieve this, a backup command must be requested for each block and section. Messages below can be used as an script to perform full backup:

  • //handshake
  • F0 00 53 43 00 00 01 F7
  • //backup midi features
  • F0 00 53 43 00 00 02 01 00 00 F7
  • //backup midi channels
  • F0 00 53 43 00 00 02 01 00 01 F7
  • //backup button types
  • F0 00 53 43 00 7F 02 01 01 00 F7
  • //backup button midi message types
  • F0 00 53 43 00 7F 02 01 01 01 F7
  • //backup button midi ids
  • F0 00 53 43 00 7F 02 01 01 02 F7
  • //backup encoder enabled
  • F0 00 53 43 00 7F 02 01 02 00 F7
  • //backup encoder invert state
  • F0 00 53 43 00 7F 02 01 02 01 F7
  • //backup encoder encoding
  • F0 00 53 43 00 7F 02 01 02 02 F7
  • //backup analog enabled
  • F0 00 53 43 00 7F 02 01 03 00 F7
  • //backup analog invert state
  • F0 00 53 43 00 7F 02 01 03 01 F7
  • //backup analog type
  • F0 00 53 43 00 7F 02 01 03 02 F7
  • //backup analog midi id
  • F0 00 53 43 00 7F 02 01 03 03 F7
  • //backup analog lower cc limit
  • F0 00 53 43 00 7F 02 01 03 04 F7
  • //backup analog upper cc limit
  • F0 00 53 43 00 7F 02 01 03 05 F7
  • //backup led hardware parameters
  • F0 00 53 43 00 7F 02 01 04 00 F7
  • //backup led activation note
  • F0 00 53 43 00 7F 02 01 04 01 F7
  • //backup led rgb enabled
  • F0 00 53 43 00 7F 02 01 04 02 F7
  • //backup led local led control
  • F0 00 53 43 00 7F 02 01 04 03 F7

Response (default board configuration):

TO-DO