Framing
- Manufacturer ID:
00 21 7E - Standard MIDI SysEx:
F0 … F7 - Multi-packet assembly for long responses (browser client)
Transports
Firmware 2.5 and newer accept configuration SysEx over USB MIDI and BLE MIDI and returns each response through the transport that sent the request. Only one fragmented configuration command is assembled at a time. Firmware-update commands 0x20–0x23 remain USB-only.
Starting in 2.6.0, BLE requires encryption. All BLE configuration commands except identification/info require a physical approval window; USB firmware update begin also requires it. Hold Button 1 for three seconds and release to open the 60-second window. A locked request returns status 4. Ordinary USB configuration is unaffected. USB updates abort after 15 seconds of inactivity or USB disconnect.
Commands
| Cmd | Hex | Name |
|---|---|---|
| PING | 0x01 | Identify |
| GET_INFO | 0x02 | Feature / I/O counts |
| GET_CONFIG | 0x03 | Read global config |
| SET_CONFIG | 0x04 | Write global config (RAM) |
| SAVE | 0x05 | Commit EEPROM |
| RESET | 0x06 | Factory defaults |
| GET_BANK_CONFIG | 0x07 | Read bank layer |
| SET_BANK_CONFIG | 0x08 | Write bank layer |
| GET_CONFIG_CHUNK | 0x16 | Read a TX-safe global-config slice |
| FW_BEGIN | 0x20 | Start firmware session |
| FW_DATA | 0x21 | Firmware chunk |
| FW_END | 0x22 | Finalize firmware |
| FW_CANCEL | 0x23 | Abort firmware |
Feature flags (GET_INFO)
| Bit | Mask | Feature |
|---|---|---|
| 0 | 0x01 | Bank switching |
| 1 | 0x02 | Harmony |
| 4 | 0x10 | USB firmware update |
| 5 | 0x20 | Deep sleep |
Current configuration extensions
Extended GET_INFO metadata reports the EC11 encoder and addressable LED counts. GET_CONFIG and SET_CONFIG append six bytes per encoder: enabled, action type, CC number, current/start value, reversed direction, and MIDI channel.
Encoder action types are CC, Program Change, Bank Select MSB (CC 0), and Bank Select LSB (CC 32). Button types also include Program Change and Bank Select MSB/LSB increment and decrement.
Devices with addressable LEDs can also store a pressed and released RGB color for each matching button/LED position. These settings are global per physical control and persist with Save Permanently.
Version 2.5 and newer support six additional harmony voices as literal MIDI notes, each with its own velocity. Each note button can inherit the global stack or define its own six-voice stack, including an empty stack. Version 2.6 also adds primary-note velocity and independent MIDI channels for harmony voices, defaulting to the primary channel.
Large product profiles use requested 32-byte GET_CONFIG_CHUNK and GET_BANK_CONFIG_CHUNK slices so live MIDI messages cannot overflow the ESP32 USB-MIDI transmit queue while configuration is loading. The legacy single-response commands remain available for compatibility.
A second extension feature byte advertises bounded control ranges. The global payload appends minimum/maximum pairs for buttons, analog knobs, and encoders; bank payloads append the per-bank button and analog-knob pairs. Analog travel maps across the bounded range, while stepped actions and encoders wrap within it.