MIDI 2.0 Device Design: Property Names and Mapping
MIDI Association OS API Working Group
MIDI 2.0 defines a number of device properties which are declared across 4 layers:
- Standard MIDI 2.0 Messages
- MIDI-CI Transactions
- Property Exchange Resources
- USB MIDI 2.0
A single device might declare values for any of these device properties in all 4 layers. This article and its tables show where there are properties in each layer which should have the same value as properties in other layers. Keeping these values the same across the 4 layers will help other devices, operating systems, and applications to recognize and display the device to the user in a predictable and consistent manner.
The properties are shown in 3 tables below. The tables are also available as 3 tabs in a Google Sheets spreadsheet document accessible and downloadable here: https://docs.google.com/spreadsheets/d/1tVJN835Gk_9CVlF6nRLe5uu962vvl82GCzGtzsZbuwI/
Table 1: Basic Device Properties
The properties in this table are generally used for product identification.
Property Name |
UMP Message |
UMP Message Field |
MIDI-CI Message |
MIDI-CI Message Field |
PE Resource |
Property |
USB MIDI 2.0 Descriptor |
USB MIDI 2.0 Descriptor Field |
Vendor ID | Device Descriptor | idVendor | ||||||
Product ID | idProduct | |||||||
Interface Name | Standard MIDI Streaming Interface Descriptor | iInterface + Separate String Descriptor1 | ||||||
UMP Endpoint Name2 | Endpoint Name Notification | UMP Endpoint Name | Standard MIDI Streaming Interface Descriptor | iInterface + Separate String Descriptor | ||||
Manufacturer Name | DeviceInfo | manufacturer | Device Descriptor | iManufacturer + Separate String Descriptor | ||||
Product Name | family + model | iProduct + Separate String Descriptor | ||||||
Unique Identifier3 | Product Instance Id Notification | Product Instance Id | Reply to Endpoint Message | Product Instance Id | serial | iSerialNumber + Separate String Descriptor | ||
Manufacturer SysEx Id | Device Identity Notification | Manufacturer | Discovery and Reply to Discovery | Manufacturer | DeviceInfo | manufacturerId | ||
Model Family Value | Model Family | Model Family | familyId | |||||
Model Number Value | Model Number | Model Number | modelId | |||||
Version Value | Version | Version | versionId |
Note 1: The text string for iInterface should be very similar to or the same as UMP Endpoint Name if possible. But iInterface Name might need to include “MIDI” for identification purposes.
Note 2: If the device does not declare its UMP Endpoint name, then use the text string for iInterface from USB as a substitute. If the text string for iInterface has a “MIDI” suffix, the suffix should be removed when being presented as a UMP Endpoint.
If a USB MIDI 1.0 device is represented as a Virtual UMP device, then the text string for iInterface can be used as the virtual UMP Endpoint Name.
Note 3: MIDI 2.0 Product Instance Id Notification and USB iSerialNumber:
This property has high value for Operating Systems to track a device between power cycles or when connected to a different USB port. This also differentiates between multiple units of the same make/model device. It is sometimes difficult to add the actual serial number found on the product or box. This property is not required to match that serial number. For example, the value could be a random number generated at first powerup then written to memory. max 255 characters ASCII (recommend < 36 characters)
See this excellent article about using iSerial on Windows. The fundamental ideas presented are also generally good practice for other operating systems: https://devblogs.microsoft.com/windows-music-dev/the-importance-of-including-a-unique-iserialnumber-in-your-usb-midi-devices/
Table 2: Further Properties for Devices which have Dynamic Function Blocks
The properties in this table are generally used to describe device topology for devices which implement Dynamic Function Blocks.
See the M2-104-UM specification for 2 ways to design a device in the relationship between USB MIDI 2.0 Group Terminal Blocks and MIDI 2.0 Function Blocks (Dynamic Function Blocks or Static Function Blocks).
Property Name |
UMP Message |
UMP Message Field |
MIDI-CI Message |
MIDI-CI Message Field |
PE Resource |
Property |
USB MIDI 2.0 Descriptor |
USB MIDI 2.0 Descriptor Field |
UMP Endpoint Block Configuration | ||||||||
Number of Group Terminal Blocks | Class-specific MS Data Endpoint Descriptor | bNumGrpTrmBlock1 | ||||||
Number of Function Blocks | Endpoint Info Notification | Number of Function Blocks | ||||||
Protocols Supported | M2 and M1 bits | |||||||
Group Terminal Block Protocol | Group Terminal Block Descriptor | bMIDIProtocol2 | ||||||
Current UMP Endpoint Protocol | Stream Configuration Notification | Protocol | ||||||
Group Terminal Block Name | String Descriptor | iBlockItem + Separate String Descriptor3 | ||||||
For Each of One or More Function Blocks | ||||||||
Block Name | Function Block Name Notification | Function Block Name | ||||||
Block ID | Function Blocks Info Notification | Function Block Number | Reply to Discovery | Function Block Number | ||||
Streaming Direction | Direction | |||||||
Block Active | Function Block Active | |||||||
Block Is MIDI 1.0 | MIDI 1.0 | |||||||
First Group | First Group | |||||||
Number of Groups Spanned | Number of Groups Spanned |
Note 1: bNumGrpTrmBlock must be set to a single, bidirectional (bGrpTrmBlkType=0x00) Group Terminal Block starting at Group 1 (nGroupTrm=0x00) and containing 16 Groups (nNumGroupTRM=0x10)
Note 2: bMIDIProtocol should be set to 0x00 (unknown). Protocol is set by UMP Endpoint and Function Blocks.
Note 3: String for iBlockItem should be set to the same as UMP Endpoint Name and the string for iInterface.
Table 3: Further Properties for Devices which have Static Function Blocks
The properties in this table are generally used to describe device topology for devices which implement Static Function Blocks.
See the M2-104-UM specification for 2 ways to design a device in the relationship between USB MIDI 2.0 Group Terminal Blocks and MIDI 2.0 Function Blocks (Dynamic Function Blocks or Static Function Blocks).
Property Name |
UMP Message |
UMP Message Field |
MIDI-CI Message |
MIDI-CI Message Field |
PE Resource |
Property |
USB MIDI 2.0 Descriptor |
USB MIDI 2.0 Descriptor Field |
UMP Endpoint Block Configuration | ||||||||
Number of Blocks | Endpoint Info Notification | Number of Function Blocks | Class-specific MS Data Endpoint Descriptor | bNumGrpTrmBlock | ||||
Protocols Supported | M2 and M1 bits | |||||||
Current UMP Endpoint Protocol | Stream Configuration Notification | Protocol | Group Terminal Block Descriptor | bMIDIProtocol | ||||
For Each of One or More Blocks | ||||||||
Block Name | Function Block Name Notification | Function Block Name | Group Terminal Block Descriptor | iBlockItem + Separate String Descriptor | ||||
Block ID | Function Blocks Info Notification | Function Block Number | Reply to Discovery | Function Block Number | Group Terminal Block Descriptor | bGrpTrmBlkID | ||
Streaming Direction | Direction | Group Terminal Block Descriptor | bGrpTrmBlkType | |||||
Block Active | Function Block Active | |||||||
Block Is MIDI 1.0 | MIDI 1.0 | Group Terminal Block Descriptor | bMIDIProtocol | |||||
First Group | First Group | Group Terminal Block Descriptor | nGroupTrm | |||||
Number of Groups Spanned | Number of Groups Spanned | Group Terminal Block Descriptor | nNumGroupTrm |
Also see these developer device design articles for building USB MIDI 2.0 devices:
BUILDING A USB MIDI 2.0 DEVICE – PART 1