midi2-dev/usbmidi2descriptorbuilder

A USB MIDI 2.0 Decriptor Builder

usbmidi2descriptorbuilder's Issues

Feature Request: TotalLength in desc_fs_configuration

Can the TotalLength be based on a #define variable like desc_fs_configuration_length.

Then desc_fs_configuration_length could be based on further defines like:

#define desc_cdc_length xx
#define desc_midi1_length yy
#define desc_midi2_length zz

#define desc_fs_configuration_length desc_cdc_length + desc_midi1_length + desc_midi2_length

Possible issue with bcdUSB value

Forgive me if I'm wrong, this isn't my area of expertise, but it appears the bcdUSBMSB value "0x02" is being put in the bcdUSBLSB field of the USB device descriptor.

Feature Request - Parameter Names

Currently code creates fixed parameters including desc_device, desc_device_qualifier, desc_fs_configuration, etc.

Would be nice if this could be based on an input so that you could easily create multiple sets of descriptors with different configurations, like:

Input: ProtoZOA

Parameters: ProtoZOA_device, ProtoZOA_device_qualifier, ProtoZOA_fs_configuration, etc.

USB 1.0 Descriptors Do Not Work

This is a follow-up to my previous issue, although it is different in nature.

The USB descriptors generated by the JSON below do not work. The intention is to create an asymmetric port configuration with three host outputs and one host input, and while the port names show up correctly in MacOS, no data flows. The descriptors generated have embedded IN jacks connected to the BULK IN endpoint, and embedded OUT jacks connected to the BULK OUT endpoint, which I believe is not correct.

I've found the USB MIDI spec can be confusing with it's mixing of IN and OUT references, embedded external, etc. After some experimentation and re-reading of the spec, here is my understanding of the correct USB signal flow, which I've confirmed is what we are using with our 8051 USB devices:

Host MIDI OUT Port
        |
        V
BULK OUT ENDPOINT (must list all embedded jacks it connects to, the jack order here determines how MacOS lists the ports)
        |
        V
Embedded MIDI IN Jack (MacOS uses the iJack string here to label the port)
        |
        V
External MIDI OUT Jack (with source jack id matching embedded MIDI IN, MacOS doesn't use iJack string referenced here)
        |
        V
---------------------------------------------
[Device firmware / USB peripheral lives here]
---------------------------------------------
        |
        V
External MIDI IN Jack (MacOS doesn't use iJack string referenced here)
        |
        V
Embedded MIDI OUT Jack (with source jack id matching external MIDI IN, MacOS uses the iJack string here to label the port)
        |
        V
BULK IN ENDPOINT (must list all embedded jacks it connects to)
        |
        V
Host MIDI IN Port 

Questions for @AmeNote-MikeKent:

• Does the above look correct to you?
• Are the external jacks necessary if they aren't actually associated with physical ports on the device? In other words, do we need to define an external jack for the keys on a keyboard controller, or will an embedded jack alone suffice? MacOS doesn't seem to care if I omit the External Output jacks from the HOST OUT -> DEVICE IN ports or the External Input jacks from the DEVICE OUT -> HOST IN ports, however this breaks things on Windows and the device won't enumerate.
• It seems that the endpoint descriptors have to come after the jacks are defined, moving them before the jacks breaks them on MacOS. Can you confirm this is correct per the spec?
• Assuming my understanding above is correct, I'm having trouble getting a (host ports perspective) 3 out, 1 in device to enumerate properly. It's working on windows, but on MacOS all messages sent to ports 1 and 2 are using cable code 0, and messages sent to port 3 use cable code 1. I'll send you an email with details as this might be outside the scope of this issue.

JSON to generate the descriptors:

{
    "idVendor": "0xCAFE",
    "idProduct": "0x1d6b",
    "manufacturer": "ACME Enterprises",
    "manufacturerId": "0x7E0000",
    "version": "0x00010000",
    "product": "ACME Synth",
    "serialNumber": "abcd1234",
    "power": 250,
    "CDC": false,
    "CDCName": "ACME CDC",
    "processUmpManually": true,
    "endpoints": [
        {
            "name": "ACME Synth",
            "productId": "abcd1234",
            "familyId": "0xDEAD",
            "modelId": "0xBEEF",
            "MIDI1Itf": [
                {
                    "in": true,
                    "out": true,
                    "name": "Control Surface"
                },
                {
                    "in": false,
                    "out": true,
                    "name": "TRS MIDI Out"
                },
                {
                    "in": false,
                    "out": true,
                    "name": "CV In"
                }
            ],
            "defaultGTBProtocol": 1
        }
    ]
}

Bug: Generated string_desc_arr_length is incorrect

The generated string_desc_arr_length is short by one. Following is example generated output:

char const* string_desc_arr [] = { "", "ACME Enterprises", "ACME Synth", "abcd1234", "MonoSynth" }; uint8_t const string_desc_arr_length = 4;

In this example, string_desc_arr_length should be equal to 5.

USB 1.0 Descriptor Comments incorrect

When generating descriptors for a USB MIDI 1.0 device, some of the comments being generated are incorrect. For example, the "bJackType" entries below are both commented as Embedded, but the second one is external.

// Audio MS Descriptor - CS Interface - MIDI IN Jack (EXT) (Embedded)
	0x06,	// bLength
	0x24,	// bDescriptorType = CS_INTERFACE
	0x02,	// bDescriptorSubtype = MIDI_IN_JACK
	0x01,	// bJackType = EMBEDDED.
	0x01,	// bJackID
	0x04,	// iJack
	
  // Audio MS Descriptor - CS Interface - MIDI OUT Jack (EXT) (Main Out)
	0x09,	// bLength
	0x24,	// bDescriptorType = CS_INTERFACE
	0x03,	// bDescriptorSubtype = MIDI_OUT_JACK
	0x02,	// bJackType = EMBEDDED.
	0x11,	// bJackID
	0x01,	// bNrInputPins
	0x01,	// baSourceID
	0x01,	// baSourcePin
	0x04,	// iJack

In the below generated output, the main comment says both are MIDI IN, but the second is a MIDI OUT.

  // Audio MS Descriptor - CS Interface - MIDI IN Jack (EXT) (Main In)
	0x06,	// bLength
	0x24,	// bDescriptorType = CS_INTERFACE
	0x02,	// bDescriptorSubtype = MIDI_IN_JACK
	0x02,	// bJackType = EXTERNAL
	0x02,	// bJackID
	0x04,	// iJack
	
  // Audio MS Descriptor - CS Interface - MIDI IN Jack (EMB) (Main Out)
	0x09,	// bLength
	0x24,	// bDescriptorType
	0x03,	// bDescriptorSubtype
	0x01,	// bJackType
	0x12,	// bJackID
	0x01,	// Number of Input Pins of this Jack
	0x02,	// baSourceID
	0x01,	// baSourcePin
	0x04,	// iJack

Also a minor typo "Jach" in this output:

  // Audio MS Descriptor - CS Endpoint - EP General
	0x07,	// bLength
	0x25,	// bDescriptorType = CS_ENDPOINT
	0x01,	// bDescriptorSubtype = MS_GENERAL
	0x03,	// bNumEmbMIDJack
	0x12,	// Jach Id
	0x16,	// Jach Id
	0x1A,	// Jach Id

Use the following JSON to generate the form in my example:

{
    "idVendor": "0xCAFE",
    "idProduct": "0x1d6b",
    "manufacturer": "ACME Enterprises",
    "manufacturerId": "0x7E0000",
    "version": "0x00010000",
    "product": "ACME Synth",
    "serialNumber": "abcd1234",
    "power": 250,
    "CDC": false,
    "CDCName": "ACME CDC",
    "processUmpManually": true,
    "endpoints": [
        {
            "name": "ACME Synth",
            "productId": "abcd1234",
            "familyId": "0xDEAD",
            "modelId": "0xBEEF",
            "MIDI1Itf": [
                {
                    "in": true,
                    "out": true,
                    "name": "Control Surface"
                },
                {
                    "in": false,
                    "out": true,
                    "name": "TRS MIDI Out"
                },
                {
                    "in": false,
                    "out": true,
                    "name": "CV In"
                }
            ],
            "defaultGTBProtocol": 1
        }
    ]
}