Windows Enumeration with MS OS 2.0 descriptors

[nullpitr]

Hi,
recently I've been trying to get my device to identify as a WinUSB device under Windows 10. I've read the MS OS 2.0 descriptor documentation and looked through the examples here in the repo.

I tried adapting the code in the WebUSB example to my needs. The device shows up under Other Devices category and reports a missing driver.
This feels like it should be a rather easy task, but I feel like I'm missing something.
Is there any documentation/code I could refer to to get this done?

Edit: in the project my team is using STM32G4s, if that changes anything

[chegewara]

When ive been doing arduino library for esp32S2 i found that windows 10 requires CDC descriptor in addition to WebUSB.

[dhalbert]

There is an example of VENDOR descriptors for WebUSB serial in CircuitPython. Look at the 6.2.x branch for details; main has
been completely reworked for dynamic USB descriptors and WebUSB serial is currently broken in that branch.

See in particular https://github.com/adafruit/circuitpython/blob/9d8545e5e276c5309ed704e73e53d643364790db/tools/gen_usb_descriptor.py#L968 and following. However, the code was taken from TinyUSB, so you may not learn anything new. This code was supplied by a customer; I don't understand it in detail.

In CircuitPython, CDC is normally enabled.

[gionatha]

lowprio
could you kindly attach the source code of the solution you found? It would be of great help.
Once the CDC has been added, is it possible to connect to the device from Windows using the LibUsb?
Thanks
Gionatha

[nullpitr]

I remember rolling back to the code from the example, and going through it removing code related specifically to WebUSB. It works with CDC left in as is.
I'll have to take a closer look to give you a more specific answer, but for now you can try going the route we took;

[nullpitr]

Would you mind opening an issue for this with detail info

I forgor 💀
When I look into this again, i'll try to figure out what was wrong and i'll open an issue once I figure out what question I meant to ask back in May.

[shilga]

Hi,
I stumbled exactly on the same issue as described here. MS OS 2.0 descriptor seems to only work if CDC is added as in the webusb-serial example. Did you guys ever figure out what is causing this?

[HiFiPhile]

For anyone how has issue with MSOS 2.0 descriptor, here are examples for both simple device and composite device.

Simple device

tusb_desc_device_t desc_device =
{
    .bLength            = sizeof(tusb_desc_device_t),
    .bDescriptorType    = TUSB_DESC_DEVICE,
    .bcdUSB             = 0x0201,
    
    .bDeviceClass       = 0,
    .bDeviceSubClass    = 0,
    .bDeviceProtocol    = 0,
    .bMaxPacketSize0    = CFG_TUD_ENDPOINT0_SIZE,
    
    .idVendor           = 0xcafe,
    .idProduct          = 0x0201,
    .bcdDevice          = 0x0001,
    
    .iManufacturer      = 0x01,
    .iProduct           = 0x02,
    .iSerialNumber      = 0x03,
    
    .bNumConfigurations = 0x01
};

enum
{
  ITF_NUM_DFU,
  ITF_NUM_TOTAL
};

#define CONFIG_TOTAL_LEN        (TUD_CONFIG_DESC_LEN + TUD_DFU_DESC_LEN(1))

uint8_t const desc_configuration[] =
{
    // Config number, interface count, string index, total length, attribute, power in mA
    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, TUSB_DESC_CONFIG_ATT_REMOTE_WAKEUP, 500),
    // Interface number, Alternate count, starting string index, attributes, detach timeout, transfer size
    TUD_DFU_DESCRIPTOR(ITF_NUM_DFU, 1, 4, DFU_ATTR_CAN_UPLOAD | DFU_ATTR_CAN_DOWNLOAD | DFU_ATTR_MANIFESTATION_TOLERANT, 100, CFG_TUD_DFU_XFER_BUFSIZE),
};

uint8_t const desc_ms_os_20[] =
{
  // Set header: length, type, windows version, total length
  U16_TO_U8S_LE(0x000A), U16_TO_U8S_LE(MS_OS_20_SET_HEADER_DESCRIPTOR), U32_TO_U8S_LE(0x06030000), U16_TO_U8S_LE(MS_OS_20_DESC_LEN),

  // MS OS 2.0 Compatible ID descriptor: length, type, compatible ID, sub compatible ID
  U16_TO_U8S_LE(0x0014), U16_TO_U8S_LE(MS_OS_20_FEATURE_COMPATBLE_ID), 'W', 'I', 'N', 'U', 'S', 'B', 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // sub-compatible

  // MS OS 2.0 Registry property descriptor: length, type
  U16_TO_U8S_LE(MS_OS_20_DESC_LEN-0x0A-0x14), U16_TO_U8S_LE(MS_OS_20_FEATURE_REG_PROPERTY),
  U16_TO_U8S_LE(0x0007), U16_TO_U8S_LE(0x002A), // wPropertyDataType, wPropertyNameLength and PropertyName "DeviceInterfaceGUIDs\0" in UTF-16
  'D', 0x00, 'e', 0x00, 'v', 0x00, 'i', 0x00, 'c', 0x00, 'e', 0x00, 'I', 0x00, 'n', 0x00, 't', 0x00, 'e', 0x00,
  'r', 0x00, 'f', 0x00, 'a', 0x00, 'c', 0x00, 'e', 0x00, 'G', 0x00, 'U', 0x00, 'I', 0x00, 'D', 0x00, 's', 0x00, 0x00, 0x00,
  U16_TO_U8S_LE(0x0050), // wPropertyDataLength
  //bPropertyData: {70394F16-EDAF-47D5-92C8-7CB51107A235}.
  '{', 0x00, '7', 0x00, '0', 0x00, '3', 0x00, '9', 0x00, '4', 0x00, 'F', 0x00, '1', 0x00, '6', 0x00, '-', 0x00,
  'E', 0x00, 'D', 0x00, 'A', 0x00, 'F', 0x00, '-', 0x00, '4', 0x00, '7', 0x00, 'D', 0x00, '5', 0x00, '-', 0x00,
  '9', 0x00, '2', 0x00, 'C', 0x00, '8', 0x00, '-', 0x00, '7', 0x00, 'C', 0x00, 'B', 0x00, '5', 0x00, '1', 0x00,
  '1', 0x00, '0', 0x00, '7', 0x00, 'A', 0x00, '2', 0x00, '3', 0x00, '5', 0x00, '}', 0x00, 0x00, 0x00, 0x00, 0x00
};

Composite device

Two interfaces, named ITF_NUM_DFU and ITF_NUM_DBG are included in MSOS 2.0 descriptor.

tusb_desc_device_t desc_device =
{
    .bLength = sizeof(tusb_desc_device_t),
    .bDescriptorType = TUSB_DESC_DEVICE,
    .bcdUSB = 0x0201,

    .bDeviceClass = TUSB_CLASS_MISC,
    .bDeviceSubClass = MISC_SUBCLASS_COMMON,
    .bDeviceProtocol = MISC_PROTOCOL_IAD,
    .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE,

    .idVendor = 0xcafe,
    .idProduct = 0x0203,
    .bcdDevice = 0x0001,

    .iManufacturer = 0x01,
    .iProduct = 0x02,
    .iSerialNumber = 0x03,

    .bNumConfigurations = 0x01
};

enum
{
  ITF_NUM_AUDIO_CONTROL_IIS = 0,
  ITF_NUM_AUDIO_STREAMING_IIS,
  ITF_NUM_DFU,
  ITF_NUM_AUDIO_CONTROL_MIC,
  ITF_NUM_AUDIO_STREAMING_MIC,
  ITF_NUM_DBG,
  ITF_NUM_TOTAL
};

uint8_t const desc_configuration[] =
{
    // Config number, interface count, string index, total length, attribute, power in mA
    TUD_CONFIG_DESCRIPTOR(1, ITF_NUM_TOTAL, 0, CONFIG_TOTAL_LEN, 0, 500),
    // String index, EP Out & EP In address, EP size
    TUD_AUDIO_USB2IIS_DESCRIPTOR(4, EPNUM_AUDIO_OUT, EPNUM_AUDIO_FB | 0x80),
    // Interface number, string index, attributes, detach timeout, transfer size
    TUD_DFU_RT_DESCRIPTOR(ITF_NUM_DFU, 6, DFU_ATTR_CAN_DOWNLOAD | DFU_ATTR_WILL_DETACH, 100, CFG_TUD_DFU_XFER_BUFSIZE),
    // Interface number, string index, bytes per sample, resolution, In address, EP size
    TUD_AUDIO_MIC_DESCRIPTOR(ITF_NUM_AUDIO_CONTROL_MIC, 5, CFG_TUD_AUDIO_FUNC_2_N_BYTES_PER_SAMPLE_TX, CFG_TUD_AUDIO_FUNC_2_FORMAT_1_RESOLUTION_RX, 0x80 | EPNUM_AUDIO_IN, CFG_TUD_AUDIO_FUNC_2_EP_IN_SZ_MAX),
    // Interface number, string index, EP Out & IN address, EP size
    TUD_VENDOR_DESCRIPTOR(ITF_NUM_DBG, 7, EPNUM_DBG_OUT, EPNUM_DBG_IN | 0x80, 512)
};

uint8_t const desc_ms_os_20[] =
{
    // Set header: length, type, windows version, total length
    U16_TO_U8S_LE(0x000A), U16_TO_U8S_LE(MS_OS_20_SET_HEADER_DESCRIPTOR), U32_TO_U8S_LE(0x06030000), U16_TO_U8S_LE(MS_OS_20_DESC_LEN),

    // Configuration subset header: length, type, configuration index, reserved, configuration total length
    U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_CONFIGURATION), 0, 0, U16_TO_U8S_LE(MS_OS_20_DESC_LEN - 0x0A),

    // Function Subset header: length, type, first interface, reserved, subset length
    U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_FUNCTION), ITF_NUM_DFU, 0, U16_TO_U8S_LE(0x08 + 0x14 + 0x84),

    // MS OS 2.0 Compatible ID descriptor: length, type, compatible ID, sub compatible ID
    U16_TO_U8S_LE(0x0014), U16_TO_U8S_LE(MS_OS_20_FEATURE_COMPATBLE_ID), 'W', 'I', 'N', 'U', 'S', 'B', 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // sub-compatible
    
    // MS OS 2.0 Registry property descriptor: length, type
    U16_TO_U8S_LE(0x0084), U16_TO_U8S_LE(MS_OS_20_FEATURE_REG_PROPERTY),
    U16_TO_U8S_LE(0x0007), U16_TO_U8S_LE(0x002A), // wPropertyDataType, wPropertyNameLength and PropertyName "DeviceInterfaceGUIDs\0" in UTF-16
    'D', 0x00, 'e', 0x00, 'v', 0x00, 'i', 0x00, 'c', 0x00, 'e', 0x00, 'I', 0x00, 'n', 0x00, 't', 0x00, 'e', 0x00,
    'r', 0x00, 'f', 0x00, 'a', 0x00, 'c', 0x00, 'e', 0x00, 'G', 0x00, 'U', 0x00, 'I', 0x00, 'D', 0x00, 's', 0x00, 0x00, 0x00,
    U16_TO_U8S_LE(0x0050), // wPropertyDataLength
    //bPropertyData: {70394F16-EDAF-47D5-92C8-7CB511020303}.
    '{', 0x00, '7', 0x00, '0', 0x00, '3', 0x00, '9', 0x00, '4', 0x00, 'F', 0x00, '1', 0x00, '6', 0x00, '-', 0x00,
    'E', 0x00, 'D', 0x00, 'A', 0x00, 'F', 0x00, '-', 0x00, '4', 0x00, '7', 0x00, 'D', 0x00, '5', 0x00, '-', 0x00,
    '9', 0x00, '2', 0x00, 'C', 0x00, '8', 0x00, '-', 0x00, '7', 0x00, 'C', 0x00, 'B', 0x00, '5', 0x00, '1', 0x00,
    '1', 0x00, '0', 0x00, '2', 0x00, '0', 0x00, '3', 0x00, '0', 0x00, '3', 0x00, '}', 0x00, 0x00, 0x00, 0x00, 0x00,
    
    // Function Subset header: length, type, first interface, reserved, subset length
    U16_TO_U8S_LE(0x0008), U16_TO_U8S_LE(MS_OS_20_SUBSET_HEADER_FUNCTION), ITF_NUM_DBG, 0, U16_TO_U8S_LE(0x08 + 0x14 + 0x84),

    // MS OS 2.0 Compatible ID descriptor: length, type, compatible ID, sub compatible ID
    U16_TO_U8S_LE(0x0014), U16_TO_U8S_LE(MS_OS_20_FEATURE_COMPATBLE_ID), 'W', 'I', 'N', 'U', 'S', 'B', 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // sub-compatible
    
    // MS OS 2.0 Registry property descriptor: length, type
    U16_TO_U8S_LE(0x0084), U16_TO_U8S_LE(MS_OS_20_FEATURE_REG_PROPERTY),
    U16_TO_U8S_LE(0x0007), U16_TO_U8S_LE(0x002A), // wPropertyDataType, wPropertyNameLength and PropertyName "DeviceInterfaceGUIDs\0" in UTF-16
    'D', 0x00, 'e', 0x00, 'v', 0x00, 'i', 0x00, 'c', 0x00, 'e', 0x00, 'I', 0x00, 'n', 0x00, 't', 0x00, 'e', 0x00,
    'r', 0x00, 'f', 0x00, 'a', 0x00, 'c', 0x00, 'e', 0x00, 'G', 0x00, 'U', 0x00, 'I', 0x00, 'D', 0x00, 's', 0x00, 0x00, 0x00,
    U16_TO_U8S_LE(0x0050), // wPropertyDataLength
    //bPropertyData: {70394F16-EDAF-47D5-92C8-7CB511020304}.
    '{', 0x00, '7', 0x00, '0', 0x00, '3', 0x00, '9', 0x00, '4', 0x00, 'F', 0x00, '1', 0x00, '6', 0x00, '-', 0x00,
    'E', 0x00, 'D', 0x00, 'A', 0x00, 'F', 0x00, '-', 0x00, '4', 0x00, '7', 0x00, 'D', 0x00, '5', 0x00, '-', 0x00,
    '9', 0x00, '2', 0x00, 'C', 0x00, '8', 0x00, '-', 0x00, '7', 0x00, 'C', 0x00, 'B', 0x00, '5', 0x00, '1', 0x00,
    '1', 0x00, '0', 0x00, '2', 0x00, '0', 0x00, '3', 0x00, '0', 0x00, '4', 0x00, '}', 0x00, 0x00, 0x00, 0x00, 0x00,
};

[shilga]

Thank you a lot. That solves it.