SysEx Documentation for External Applications
Work in progress
It is possible to interact with our MIDI controllers via SysEx messages, which allows you to update preset and bank parameters, or retrieve data from the controller like Preset Names etc.
- 1 Saving or Temporary Override
- 2 SysEx Message Structure
- 2.1 Message Payload
- 2.2 Transaction ID
- 2.3 CheckSum
- 3 Return Codes
- 4 Functions
- 4.1 [op2: 00h] Controller Functions
- 4.2 [op2: 01h] Update Preset Short Name
- 4.3 [op2: 02h] Update Preset Toggle Name
- 4.4 [op2: 03h] Update Preset Long Name
- 4.5 [op2: 04h] Update Preset Message
- 4.5.1 Message Types
- 4.5.1.1 [op5: 01h] Program Change
- 4.5.1.2 [op5: 02h] Control Change
- 4.5.1 Message Types
- 4.6 [op2: 05h] Other Data Preset
- 4.7 [op2: 10h] Update Current Bank Name
- 4.8 [op2: 11h] Display message on LCD
- 4.9 [op2: 21h] Get Preset Short Name
- 4.10 [op2: 22h] Get Preset Toggle Name
- 4.11 [op2: 23h] Get Preset Long Name
- 4.12 [op2: 30h] Get Current Bank Name
- 4.13 [op2: 31h] Get Toggle State of all Presets in current Bank
- 4.14 [op2: 32h] Get Controller Information
- 5 Glossary
Saving or Temporary Override
In most functions, there will be an option to save by sending 7F
for a specific Opcode. If override is chosen instead (by using any other value), the values will just be written temporarily, and will revert back to the original values when the bank is changed.
For example, if you update the Preset Short Name from Empty
to Preset 1
and do not save, when sending the SysEx string to update the Preset Short Name, the controller will display the Preset Name as Preset 1
. However, when you change banks and go back to the same bank again, the Preset Name will show Empty
.
SysEx Message Structure
For this API, Op1 is fixed at 0x70
.
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
04 -- Device Model ID
00 -- Ignore
70 -- Opcode 1
00 -- Opcode 2
00 -- Opcode 3
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload Start
pp
pp
pp
yy -- CheckSum
F7 -- SysEx End
Message Payload
The message payload, which always starts at Pointer 17
, contains the data for the intended function, and can be of any length. For example, if you want to update the Preset Name, the name will be in the Payload in ASCII code.
Transaction ID
The Transaction ID
is used as an identifier for you to know which SysEx command the controller is responding to when it returns a SysEx message. For example, if you sent a request for a Preset Short Name with a Txn ID of 45
, the controller will send a response with a Txn ID of 45
as well, so you know it is responding to that specific request.
If there is no intention to use it, just leave it as 00
CheckSum
The CheckSum is used to verify the message integrity. The calculation will be done on the sender’s end, and then when the SysEx message is received by the Controller, it will calculate the CheckSum of the message and then compare it to the sender’s CheckSum. If it does not match, the message is ignored.
The CheckSum can be calculated like this:
First, take the first value as F0
, which is the start of the SysEx message.
Next, XOR the value with the next value.
Continue this until you reach n-2
.
AND
the value with 0x7F
, which will give you a value of between 0 - 127.
Here is a sample code in C++:
int calculateChecksum(uint16_t len, uint8_t *ptr) {
uint8_t cSum = *(ptr);
for (int i = 1; i < len - 2; i++) {
cSum ^= *(ptr + i);
}
cSum &= 0x7F;
return cSum;
}
Return Codes
If there is any error in the received SysEx message, the Controller will return you a error message.
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1
7F -- Opcode 2
xx -- Ack Code
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
where Ack Code
is
SUCCESS 00
WRONG MODEL ID 01
WRONG CHECKSUM 02
WRONG PAYLOAD SIZE 03
Functions
This section describes the various functions as specified using Opcode 2.
[op2: 00h] Controller Functions
Using 00h
for Op2 lets you access the Controller functions. The specific functions are selected using Op3.
[op3: 00h]Controller Bank Up
F0 00 21 24 id 00 70 00 00 00 00 00 00 00 00 00 cs F7
[op3: 01h]Controller Bank Down
F0 00 21 24 id 00 70 00 01 00 00 00 00 00 00 00 cs F7
[op3: 02h]Controller Toggle Page
F0 00 21 24 id 00 70 00 02 00 00 00 00 00 00 00 cs F7
[op2: 01h] Update Preset Short Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1
01 -- Opcode 2 - Update Preset Short Name
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Whether to save to memory. 7F = Save.
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload. Preset name in ASCII code
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 02h] Update Preset Toggle Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1
02 -- Opcode 2 - Update Preset Toggle Name
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Whether to save to memory. 7F = Save.
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload. Preset name in ASCII code
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 03h] Update Preset Long Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1
03 -- Opcode 2 - Update Preset Long Name
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Whether to save to memory. 7F = Save.
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload. Preset name in ASCII code
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 04h] Update Preset Message
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
04 -- Opcode 2 - Update Preset Message
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Message Number (0-15, or 0x00 - 0x0F)
00 -- Opcode 5 - Message Type (See MESSAGE TYPES)
00 -- Opcode 6 - Whether to save to memory. 7F = Save.
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
Message Types
The required payload will depend on the type of message selected with Opcode 5
[op5: 01h] Program Change
Required Payload
pp -- Action Type (See ACTION TYPES)
pp -- Toggle Type
pp -- PC Number
pp -- MIDI Channel
[op5: 02h] Control Change
Required Payload
pp -- Action Type (See ACTION TYPES)
pp -- Toggle Type
pp -- CC Number
pp -- CC Value
pp -- MIDI Channel
[op2: 05h] Other Data Preset
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
05 -- Opcode 2 - Update Preset Other Data
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Message Number (0-15, or 0x00 - 0x0F)
00 -- Opcode 5 - Message Type (See MESSAGE TYPES)
00 -- Opcode 6 - Whether to save to memory. 7F = Save.
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Preset Toggle: 7F = ON, 00 = OFF, Other = IGNORE
pp -- Preset Blink: 7F = ON, 00 = OFF, Other = IGNORE
pp -- Preset Message Scroll Mode: 7F = ON, 00 = OFF, Other = IGNORE
pp -- Preset Global Toggle Group: 00 = Independent, 01-10 = Groups 1 to 16, Other = IGNORE
[Ignore this if not using the PRO model]
pp -- Pos 1 LED Color (PRO only) F7 = IGNORE
pp -- Pos 2 LED Color (PRO only) F7 = IGNORE
pp -- Shift LED Color (PRO only) F7 = IGNORE
pp -- Pos 1 Text Color (PRO only) F7 = IGNORE
pp -- Pos 2 Text Color (PRO only) F7 = IGNORE
pp -- Shift Text Color (PRO only) F7 = IGNORE
pp -- Pos 1 Background Color (PRO only) F7 = IGNORE
pp -- Pos 2 Background Color (PRO only) F7 = IGNORE
pp -- Shift Background Color (PRO only) F7 = IGNORE
yy -- CheckSum
F7 -- SysEx End
[op2: 10h] Update Current Bank Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
10 -- Opcode 2 - Update Current Bank Name
00 -- Opcode 3
00 -- Opcode 4 - Whether to save to memory. 7F = Save.
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload. Bank name in ASCII code
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 11h] Display message on LCD
Displays a custom message of up to 20 characters in the controller’s LCD.
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
11 -- Opcode 2 - Display message on LCD
00 -- Opcode 3
00 -- Opcode 4 - Duration to display message. Increments of 100ms. Value of 10 = 1000ms.
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
00 -- Ignore
00 -- Ignore
00 -- Ignore
pp -- Payload. Message in ASCII code up to 20 characters
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
Â
[op2: 21h] Get Preset Short Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
21 -- Opcode 2 - Get Preset Short Name
00 -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
21 -- Opcode 2
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Preset Name Length / Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 22h] Get Preset Toggle Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
22 -- Opcode 2 - Get Preset Toggle Name
00 -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
22 -- Opcode 2
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Preset Name Length / Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 23h] Get Preset Long Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
23 -- Opcode 2 - Get Preset Long Name
00 -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
23 -- Opcode 2
xx -- Opcode 3 - Preset Number (A = 0, B = 1 ...)
xx -- Opcode 4 - Preset Name Length / Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 30h] Get Current Bank Name
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
30 -- Opcode 2 - Get Current Bank Name
00 -- Opcode 3
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
21 -- Opcode 2
00 -- Opcode 3
xx -- Opcode 4 - Bank Name Length / Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
[op2: 31h] Get Toggle State of all Presets in current Bank
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
31 -- Opcode 2 - Get toggle states
00 -- Opcode 3
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
31 -- Opcode 2
00 -- Opcode 3
xx -- Opcode 4 - Total number of presets / Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Payload
pp
....
pp
yy -- CheckSum
F7 -- SysEx End
where each Payload value contains the toggle state of each preset. 7f
= Toggled
Payload
00 -- Preset A, not toggled
00 -- Preset B, not toggled
7F -- Preset C, toggled
...
00 -- Preset n, not toggled
[op2: 32h] Get Controller Information
Retrieve information like Model ID, firmware version etc.
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 -- Ignore
70 -- Opcode 1 - 0x70
32 -- Opcode 2 - Get Controller Information
00 -- Opcode 3
00 -- Opcode 4
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
yy -- CheckSum
F7 -- SysEx End
Return SysEx
F0 -- SysEx Start
00 -- Manufacturer ID 1
21 -- Manufacturer ID 2
24 -- Manufacturer ID 3
xx -- Device Model ID
00 --
70 -- Opcode 1
32 -- Opcode 2
00 -- Opcode 3
09 -- Opcode 4 - Payload Size
00 -- Opcode 5
00 -- Opcode 6
00 -- Opcode 7
xx -- Transaction ID
00 -- Ignore
00 -- Ignore
pp -- Model ID
pp -- Firmware Version 1
pp -- Firmware Version 2
pp -- Firmware Version 3
pp -- Firmware Version 4
pp -- Total Messages per Preset
pp -- Preset Name Size
pp -- Preset Long Name Size
pp -- Bank Name Size
yy -- CheckSum
F7 -- SysEx End
Glossary
Device Model ID
MC6 0x03
MC8 0x04
MC3 0x05
MC6PRO 0x06
Action Types
This section specifies the Action IDs required when programming Preset Messages
NOTHING 0x00
PRESS 0x01
RELEASE 0x02
LONG PRESS 0x03
LONG PRESS RELEASE 0x04
DOUBLE TAP 0x05
DOUBLE TAP RELEASE 0x06
DOUBLE TAP LONG 0x07
DOUBLE TAP LONG RELEASE 0x08
RELEASE ALL 0x09
LONG PRESS SCROLL 0x0A
ON DISENGAGE 0x0B
ON FIRST ENGAGE 0x0C
Message Types
This section specifies the Message Type IDs required when programming Preset Messages
NOTHING 0x00
PC MESSAGE 0x01
CC MESSAGE 0x02
Preset Message Toggle Types
This section specifies the Message Type IDs required when programming Preset Messages
POS 1 0x00
POS 2 0x01
POS BOTH 0x02
SHIFT 0x03