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.
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, Other = OFF pp -- Preset Blink: 7F = ON, Other = OFF pp -- Preset Message Scroll Mode: 7F = ON, Other = OFF pp -- Preset Global Toggle Group: 00 = Independent, 01-10 = Groups 1 to 16 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
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