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:

1. Standard MIDI 2.0 Messages
2. MIDI-CI Transactions
3. Property Exchange Resources
4. 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.

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).

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).

Also see these developer device design articles for building USB MIDI 2.0 devices:

BUILDING A USB MIDI 2.0 DEVICE – PART 1

BUILDING A USB MIDI 2.0 DEVICE – PART 2

BUILDING A USB MIDI 2.0 DEVICE – PART 3