stegosaurus-midi
stegosaurus
Stegoaurus is an open-source MIDI controller. The controller is built around the Arduino framework and uses the MIDI protocol to communicate with a computer. It is designed to be easily configurable, with the ability to change the behavior of the controller using SysEx messages.
TODO:
- Add hardware MIDI support to the Pico
- Add SysEx support to the Pico
- Web interface for programming
- Basic interaction
- Add SysEx messages
- EEPROM module
- Pinouts
Project Structure
THis project is organized as follows:
firmware/: main firmware codeinterface/: code for the web interface
Firmware
This project runs on the Raspberry Pi Pico. To set it up in the Arduino IDE, follow this guide. You will probably have to hold down the BOOTSEL button while plugging in the Pico to get it into bootloader mode for the first time. Pay attention to these upload settings:
.
Make sure the selected port matches the port that the Pico is connected to.
Required libraries:
- EasyButton (@v2.0.3)
- Adafruit TinyUSB (@v3.1.4)
Interface for Programming
See this page for a good reference on MIDI messages.
The Stegosaurus will use SysEx messages to change the behavior of the controller.
The manufacturer ID for the USB MIDI SysEx messages is 0x00 0x53 0x4D. The 0x00 indicates that the message has a vendor ID, and the 0x53 0x4D is the ASCII representation of “SM”. This is a unique identifier for the Stegosaurus MIDI controller (I think it is unique). So, if you see a message with this ID, it is likely from the Stegosaurus. The rest of the message is the actual data.
To program the controller behavior, the interface will send a SysEx message with the manufacturer ID, followed by the command byte, and then the data. Keep in mind that the SysEx message maximum length is 128 bytes. This is using this here, but I don’t think that any of the messages will be even close to that length.
MIDI Messages
The Stegosaurus will use the following MIDI messages. Keep in mind that the first 4 bytes of the message are specific to the SysEx MIDI protocol. The rest of the message is the actual data. In accordance with standard practice, every SysEx message is concluded with the SysEx end byte 0xF7.
Memory Layout
There are 128 presets, each with 17 slots, and 7 bytes per slot. The slots are numbered 1-16, with slot 0 reserved for metadata. The metadata for each preset is as follows:
| Byte | Description |
|---|---|
| 0 | Switch type |
| 1 | Switch values |
The switch type is a 1-byte value that indicates the type of switch that the preset uses. Each bit from right to left indicates a switch. 0 is a momentary switch, and 1 is a latching switch. For example, 0b10000000 would mean that SWA is LATCHING and the rest are momentary.
The switch values are a 1-byte value that indicates the current state of the switches. Each bit from right to left indicates a switch. 0 is off, and 1 is on. For example, 0b10000000 would mean that SWA is on and the rest are off. This only applies to latching switches. This value is tracked so that the user can set a switch to a specific state when they enter a preset. Note: There is not currently a way to set this data over the MIDI bus. It must be hard-coded. This will be fixed in the future.
The rest of the slots are the actual data for the preset. Each slot is 7 bytes long. The data is as follows:
| Byte | Description |
|---|---|
| 0 | Trigger |
| 1 | Action |
| 2 | Switch number |
| 3 | MIDI channel |
| 4 | Data 1 |
| 5 | Data 2 |
| 6 | Data 3 |
This can be visualized in the following diagram:
Message Structure
The message is broken up into 2 parts: the header and the data. The header is the first 8 bytes of the message, and the data is the rest of the message.
The Message ID is a 2-byte value that is unique to each message. This is used to ensure that the message is not a duplicate. The message ID is generated by the interface and is incremented for each message. The Stegosaurus will respond with the same message ID in the response message. The message ID is ONLY ever 0 if it’s unitialized. Once the maximum value is reached, it will reset to 1. The device itself will never initiate a message, so it will never have to generate a message ID. It will only respond to messages.
Header
| Byte | Description | Value |
|---|---|---|
| 0 | Status byte | 0xF0 (SysEx start) |
| 1 | Vendor ID | 0x00 (Three-byte Vendor ID) |
| 2 | Vendor ID | 0x53 (Vendor ID) |
| 3 | Vendor ID | 0x4D (Vendor ID) |
| 4 | Message ID byte 1 | Unique ID to ensure proper separation of messages |
| 5 | Message ID byte 2 | Unique ID to ensure proper separation of messages |
| 6 | Condition* | 0, 1, or 2 |
| 7 | Message type** | See table |
*Conditions:
| Type | Description | Details |
|---|---|---|
| 0 | Request | The interface is requesting an action from the Stegosaurus |
| 1 | ResponseOk | The device is responding to a request w/o error |
| 2 | ResponseError | The device is responding to a request with an error |
**Message types:
| Type | Description |
|---|---|
| 0 | Write to a slot |
| 1 | Read from a slot |
| 2 | System parameter set |
| 3 | System parameter get |
| 4 | Get preset |
Message Data
The data is the rest of the message. There are 3 types of messages: write to a slot, read from a slot, and system parameter set. Each message has a different format.
Write to a Slot
| Byte | Description |
|---|---|
| 5 | Preset to modify |
| 6 | Slot to modify |
| 7 | Trigger |
| 8 | Action |
| 9 | Switch number |
| 10 | MIDI channel |
| 11 | Data 1 |
| 12 | Data 2 |
| 13 | Data 3 |
The trigger, action, and switch number are all 1-byte values. The trigger is what will cause the action to occur. The action is the MIDI message that will be sent. The switch number is the switch that the action will be associated with, if the trigger is a type of press.
| Trigger | Value |
|---|---|
| EnterPreset | 1 |
| ExitPreset | 2 |
| ShortPress | 3 |
| LongPress | 4 |
| DoublePress | 5 |
| Action | Value |
|---|---|
| ControlChange | 1 |
| ProgramChange | 2 |
| PresetUp | 3 |
| PresetDown | 4 |
| Switch | Value |
|---|---|
| SWA | 0 |
| SWB | 1 |
| SWC | 2 |
| SWD | 3 |
This message will write the data to the specified preset and slot in memory.
Read from a Slot
| Byte | Description |
|---|---|
| 5 | Preset to read |
| 6 | Slot to read |
This returns the data from the specified slot in the specified preset in the same format as the write message. Note that the preset and slot are returned in the message.
System Parameter Set
| Byte | Description |
|---|---|
| 5 | Parameter to set |
| 6 | Value to set |
This sets a system parameter. The parameters are as follows:
| Parameter | Value |
|---|---|
| CurrentPreset | 0 |
This message will set the specified parameter to the specified value.
System Parameter Get
| Byte | Description |
|---|---|
| 5 | Parameter to get |
This gets a system parameter. The parameters are the same as the set message.
Get Preset
| Byte | Description |
|---|---|
| 5 | Preset to get |
This returns the data for the specified preset. Note: this will be a long array.
Example Messages
Write to a Slot
Read from a Slot
System Parameter Set
System Parameter Get
Get Preset
Interface
This will have to use WebMIDI to communicate with the Arduino.
A good first step for this is to get a list of MIDI devices. I want to do this in React.