USB: Descriptor

USB Descriptor in 'USB in a NutShell'

https://www.beyondlogic.org/usbnutshell/usb5.shtml

Descriptor Types

Descriptor	Types Value
DEVICE	1
CONFIGURATION	2
STRING	3
INTERFACE	4
ENDPOINT	5
DEVICE_QUALIFIER	6
OTHER_SPEED_CONFIGURATION	7
INTERFACE_POWER	8

USB 2.0 9.4

Class Codes

https://www.usb.org/defined-class-codes

Open

Base Class	Descriptor	Usage Description
00h	Device	Use class information in the Interface Descriptors
01h	Interface	Audio
02h	Both	Communications and CDC Control
03h	Interface	HID (Human Interface Device)
05h	Interface	Physical
06h	Interface	Image
07h	Interface	Printer
08h	Interface	Mass Storage
09h	Device	Hub
0Ah	Interface	CDC-Data
0Bh	Interface	Smart Card
0Dh	Interface	Content Security
0Eh	Interface	Video
0Fh	Interface	Personal Healthcare
10h	Interface	Audio/Video Devices
11h	Device	Billboard Device Class
12h	Interface	USB Type-C Bridge Class
DCh	Both	Diagnostic Device
E0h	Interface	Wireless Controller
EFh	Both	Miscellaneous
FEh	Interface	Application Specific
FFh	Both	Vendor Specific

Device Descriptor

uint8_t  bLength;           // Length of this descriptor.
uint8_t  bDescriptorType;   // DEVICE descriptor type (USB_DESCRIPTOR_DEVICE). 0x01
uint16_t bcdUSB;            // USB Spec Release Number (BCD).
uint8_t  bDeviceClass;      // Class code (assigned by the USB-IF). 0xFF-Vendor specific.
uint8_t  bDeviceSubClass;   // Subclass code (assigned by the USB-IF).
uint8_t  bDeviceProtocol;   // Protocol code (assigned by the USB-IF). 0xFF-Vendor specific.
uint8_t  bMaxPacketSize0;   // Maximum packet size for endpoint 0.
uint16_t idVendor;          // Vendor ID (assigned by the USB-IF).
uint16_t idProduct;         // Product ID (assigned by the manufacturer).
uint16_t bcdDevice;         // Device release number (BCD).
uint8_t  iManufacturer;     // Index of String Descriptor describing the manufacturer.
uint8_t  iProduct;          // Index of String Descriptor describing the product.
uint8_t  iSerialNumber;     // Index of String Descriptor with the device's serial number.
uint8_t  bNumConfigurations;// Number of possible configurations.

USB 2.0 Spec 9.6.5

bMaxPacketSize0

Speed	Value
Low Speed	8
Full Speed	8/16/32/64
High Speed	64

https://wiki.onakasuita.org/pukiwiki/?bMaxPacketSize0

bcdDevice

The bcdDevice value indicates the device-defined revision number. The USB driver stack uses bcdDevice, along with idVendor and idProduct, to generate hardware and compatible IDs for the device. You can view the those identifiers in Device Manager.

https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/standard-usb-descriptors

When the device is originally enumerated by the USB stack, the USBHUB driver extracts idVendor, idProduct, and bcdDevice from the device descriptor. These three fields are incorporated to generate a USB hardware ID. Note that the vendor, device, and revision numbers are always stored in hexadecimal format.

https://docs.microsoft.com/en-us/windows-hardware/drivers/hid/plug-and-play-support

Should be incremented for Windows when descriptors are updated?

Configuration Descriptor

When the host requests the configuration descriptor, all related interface and endpoint descriptors are returned (refer to Section 9.4.3).

An endpoint is not shared among interfaces within a single configuration unless the endpoint is used by alternate settings of the same interface. Endpoints may be shared among interfaces that are part of different configurations without this restriction.

uint8_t  bLength;               // Length of this descriptor.
uint8_t  bDescriptorType;       // CONFIGURATION descriptor type 0x02
uint16_t wTotalLength;          // Total length of all descriptors for this configuration.
uint8_t  bNumInterfaces;        // Number of interfaces in this configuration.
uint8_t  bConfigurationValue;   // Value of this configuration (1 based).
uint8_t  iConfiguration;        // Index of String Descriptor describing the configuration.
uint8_t  bmAttributes;          // Configuration characteristics.
uint8_t  bMaxPower;             // Maximum power consumed by this configuration.

USB 2.0 Spec 9.6.3

bmAttributes

bit7:    always 1
bit6:    Self powered
bit5:    Remote wakeup
bit4..0: reserved. 0

Interface Descriptor

An interface descriptor is always returned as part of a configuration descriptor. Interface descriptors cannot be directly accessed with a GetDescriptor() or SetDescriptor() request.

uint8_t bLength;            // Size of this descriptor in bytes
uint8_t bDescriptorType;    // INTERFACE Descriptor Type 0x04
uint8_t bInterfaceNumber;   // Index of the interface in the current configuration
uint8_t bAlternateSetting;  // Value used to select this alternate setting for the interface
uint8_t bNumEndpoints;      // Number of endpoints used by this interface(excluding endpoint zero)   
uint8_t bInterfaceClass;    // Interface class code                         
uint8_t bInterfaceSubClass; // Interface subclass code                      
uint8_t bInterfaceProtocol; // Interface protocol code                      
uint8_t iInterface;         // Index of the string descriptor describing the interface

USB 2.0 Spec 9.6.5

Mass Storage Class 08h

https://usb.org/sites/default/files/Mass_Storage_Specification_Overview_v1.4_2-19-2010.pdf

HID Class 03h

https://www.usb.org/sites/default/files/hid1_11.pdf

The bDeviceClass and bDeviceSubClass fields in the Device Descriptor should not be used to identify a device as belonging to the HID class. Instead use the bInterfaceClass and bInterfaceSubClass fields in the Interface descriptor.(5.1)

A HID class device communicates with the HID class driver using either the Control (default) pipe or an Interrupt pipe. Bulk and Isochronous pipes are not used by HID class devices.(4.4)

Subclass Code	Description
0	No Subclass
1	Boot Interface Subclass
2 - 255	Reserved

HID Spec 4.2

Protocol Code	Description
0	None
1	Keyboard
2	Mouse
3 - 255	Reserved

HID Spec 4.3

Endpoint Descriptor

This descriptor contains the information required by the host to determine the bandwidth requirements of each endpoint. An endpoint descriptor is always returned as part of the configuration information returned by a GetDescriptor(Configuration) request.

uint8_t  bLength;           // Length of this descriptor.
uint8_t  bDescriptorType;   // ENDPOINT descriptor type 0x05
uint8_t  bEndpointAddress;  // Endpoint address. Bit 7 indicates direction (0=OUT, 1=IN).
uint8_t  bmAttributes;      // Endpoint transfer type.
uint16_t wMaxPacketSize;    // Maximum packet size.
uint8_t  bInterval;         // Interval for polling endpoint

Open

bEndpointAddress

The address of the endpoint on the USB device described by this descriptor. The address is encoded as follows:

Bit 3...0: The endpoint number
Bit 6...4: Reserved, reset to zero
Bit 7:     Direction, ignored forcontrol endpoints
           0 = OUT endpoint
           1 = IN endpoint

bmAttributes

This field describes the endpoint’s attributes when it isconfigured using the bConfigurationValue.

Bits 1..0: Transfer Type
           00 = Control
           01 = Isochronous
           10 = Bulk
           11 = Interrupt

If not an isochronous endpoint, bits 5..2 are reserved and must be set to zero. If isochronous, they are defined as follows:

Bits 3..2: Synchronization Type
           00 = No Synchronization
           01 = Asynchronous
           10 = Adaptive
           11 = Synchronous
Bits 5..4: Usage Type
           00 = Data endpoint
           01 = Feedback endpoint
           10 = Implicit feedback Data endpoint
           11 = Reserved

wMaxPacketSize

For all endpoints, bits 10..0 specify the maximumpacket size (in bytes).

For high-speed isochronous and interrupt endpoints:

Bits 12..11 specify the number of additional transaction opportunities per microframe:
            00 = None (1 transaction per microframe)
            01 = 1 additional (2 per microframe)
            10 = 2 additional (3 per microframe)
            11 = Reserved

Bits 15..13 are reserved and must be set to zero.

bInterval

For full-/low-speed interrupt endpoints, the value of this field may be from 1 to 255.

For full-/high-speed isochronous endpoints and high-speed interrupt endpoints, this value must be from 1 to 16 and is used as the exponent for a 2**(bInterval - 1). e.g., a bInterval of 4 means a period of 8 [2**(4-1)].

For high-speed bulk/control OUT endpoints, the bInterval must specify the maximum NAK rate of the endpoint. A value of 0 indicates the endpoint never NAKs. Other values indicate at most 1 NAK each bInterval number of microframes. This value must be in the range from 0 to 255.

HID Descriptor

https://www.usb.org/sites/default/files/hid1_11.pdf

uint8_t  bLength;
uint8_t  bDescriptorType;       // HID descriptor type 0x21
uint16_t bcdHID;                // Major(8), Minor(4), Revision(4)
uint8_t  bCountryCode;
uint8_t  bNumDescriptors;       // Total number of HID report descriptors for the interface.
uint8_t  bDescriptorType2[0];   // Type of HID class descriptor
uint16_t wDescriptorLength[0];  // Length of HID class descriptor
    :               :
uint8_t  bDescriptorType2[n];   // There can be multiple HID class descriptors
uint16_t wDescriptorLength[n];

HID Spec 6.2.1

Open

HID Class Descriptor Types

Value	HID Class Descriptor Types
0x21	HID
0x22	Report
0x23	Physical descriptor
0x24-0x2F	Reserved

HID Spec 7.1

Country Codes

Code (decimal)	Country
00	Not Supported
01	Arabic
02	Belgian
03	Canadian-Bilingual
04	Canadian-French
05	Czech Republic
06	Danish
07	Finnish
08	French
09	German
10	Greek
11	Hebrew
12	Hungary
13	International (ISO)
14	Italian
15	Japan (Katakana)
16	Korean
17	Latin American
18	Netherlands/Dutch
19	Norwegian
20	Persian (Farsi)
21	Poland
22	Portuguese
23	Russia
24	Slovakia
25	Spanish
26	Swedish
27	Swiss/French
28	Swiss/German
29	Switzerland
30	Taiwan
31	Turkish-Q
32	UK
33	US
34	Yugoslavia
35	Turkish-F
36-255	Reserved

HID Report Descriptor

https://github.com/tmk/tmk_keyboard/wiki/USB:-HID-Report-Descriptor

String Descriptor

Index:0

uint8_t bLength             // Size of this descriptor in bytes
uint8_t bDescriptorType     // Constant STRING Descriptor Type 0x03
uint16_t wLANGID[0]         // Number LANGID code              
    :               :                                              
uint16_t wLANGID[n]         // Number LANGID code

Index:1-

uint8_t bLength             // Size of this descriptor in bytes    
uint8_t bDescriptorType     // Constant STRING Descriptor Type 0x03         
uint16_t bString[x]         // UNICODE encoded string x = (bLength - 2) / 2

Language IDs

Identifire	Language
0x0409	English (United States)
0x0411	Japanese

Device_Qualifier Descriptor

The device_qualifier descriptor describes information about a high-speed capable device that would change if the device were operating at the other speed.

uint8_t  bLength              // Number Size of descriptor
uint8_t  bDescriptorType      // Constant Device Qualifier Type
uint16_t bcdUSB               // BCD USB specification version number
uint8_t  bDeviceClass         // Class Class Code
uint8_t  bDeviceSubClass      // SubClass SubClass Code
uint8_t  bDeviceProtocol      // Protocol Protocol Code
uint8_t  bMaxPacketSize0      // Number Maximum packet size for other speed
uint8_t  bNumConfigurations   // Number Number of Other-speed Configurations
uint8_t  bReserved            // Zero Reserved for future use, must be zero

USB 2.0 Spec 9.6.2

Other_Speed_Configuration Descriptor

The other_speed_configuration descriptor describes a configuration of a high-speed capable device if it were operating at its other possible speed. The structure of the other_speed_configuration is identical to a configuration descriptor. The host accesses this descriptor using the GetDescriptor() request. The descriptor type in the GetDescriptor() request is set to ther_speed_configuration.

uint8_t  bLength;               // Length of this descriptor.
uint8_t  bDescriptorType;       // Other_speed_Configuration descriptor type 0x07
uint16_t wTotalLength;          // Total length of data returned
uint8_t  bNumInterfaces;        // Number of interfaces supported by this speedconfiguration
uint8_t  bConfigurationValue;   // Value to use to select configuration
uint8_t  iConfiguration;        // Index of String Descriptor
uint8_t  bmAttributes;          // Configuration characteristics.
uint8_t  bMaxPower;             // Maximum power consumed by this configuration.

USB 2.0 Spec 9.6.4

How to get Descriptor

USB Descriptor Dumper

If you have TMK USB-USB converter try this first. It displays USB descriptors including HID Report descriptor in HEX format. https://github.com/tmk/tmk_keyboard/tree/master/converter/usb_desc_dump

How to use

Open

Download prebuilt firmware of USB Descriptor Dumper.
Flash it onto USB-USB converter.
Use hid_listen to see USB Descriptor data.

You will see outputs like below in hid_listen.

//////////////////////////////////////////////////////////////////////
// USB_desc_dump
// Address: 01
// Lowspeed: 01

// Devicer dump:
12 01 00 02 00 00 00 08 6A 04 11 00 00 01 00 00
00 01

// Device:
bLength:                12
bDescriptorType:        01
bcdUSB:                 0200
bDeviceClass:           00
bDeviceSubClass:        00
bDeviceProtocol:        00
bMaxPacketSize0:        08
idVendor:               046A
idProduct:              0011
bcdDevice:              0100
iManufacturer:          00
iProduct:               00
iSerialNumber:          00
bNumConfigurations:     01
...

HID Report Descriptor parser

USB Descriptor Dumper doesn't parse Report Descriptor, just dump its data in HEX format. To look into contents of Report descriptor closely you can use tools below.

Open

Online USB descriptor parser

Paste Report Descriptor HEX dump data into Input text box and press parse button.

https://eleccelerator.com/usbdescreqparser/

hidrd

Give HEX dump data to the parser like below.

$ cat <HEX_dump_data> | xxd -r -p  |  hidrd-convert -o spec

https://github.com/DIGImend/hidrd

Wireshark - USB Capture

https://wiki.wireshark.org/CaptureSetup/USB

This works on Linux, MacOS and Windows. You need to check GET_DESCRIPTOR responses from captured data.

Linux

lsusb

You can use lsusb -v to get descriptor on Linux. To designate your device give vendor and product ID to -d option.

lsusb -v -d feed:cafe

Open

You will see output like below.

Bus 001 Device 035: ID feed:caaa  
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               1.10
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0         8
  idVendor           0xfeed 
  idProduct          0xcaaa 
  bcdDevice            1.04
  iManufacturer           1 t.m.k.
  iProduct                2 HHKB mod
  iSerial                 0 
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength          109
    bNumInterfaces          4
    bConfigurationValue     1
    iConfiguration          0 
    bmAttributes         0xa0
      (Bus Powered)
      Remote Wakeup
    MaxPower              100mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass         3 Human Interface Device
      bInterfaceSubClass      1 Boot Interface Subclass
      bInterfaceProtocol      1 Keyboard
...

Also check this to get HID Report Descriptor.

https://github.com/tmk/tmk_keyboard/wiki/USB:-HID-Report-Descriptor#lsusb-on-linux

Windows

USB Tree Viewer

Use USB Tree Viewer on Windows.

Open

You may have to run it as administrator to get HID Report descriptor.

Just select your USB device in tree view, the tool shows USB descriptor in right pane.

USB Tree Viewer shows Report Descriptor successfully with some devices but error like below with other devices. This seems to depend on device implementation.

Error reading descriptor : ERROR_INVALID_PARAMETER (due to a obscure limitation of the Win32 USB API, see UsbTreeView.txt)

Alternative tools for Windows

Tools below may be useful on Windows. Not confirmed.

https://www.thesycon.de/eng/usb_descriptordumper.shtml (doesn't dump Report Descriptor)
win-hid-dump
USBlyzer (Fully functional 33-day trial)
https://www.eltima.com/products/usb-port-monitor/ (14-day free tiral)

MacOS

Good method to get USB descriptor on MacOS is not known yet.

These commands may give useuful info, perhaps?

system_profiler SPUSBDataType

ioreg -p IOUSB -w0 -l

Both commands don't seem to give useful informaions so much unfortuantely. Use Windows or Linux for the purpose if possible.

Alternative tools for MacOS

Descriptor Example

HHKB Professional PD-KB300

https://gist.github.com/tmk/e9d5b0b514e9d0c353344d7d4424e653

HHKB Professional 2 PD-KB400

https://gist.github.com/tmk/62ba55c7a26078552084bccbaf70a19d

HHKB Professional JP PD-KB420

https://gist.github.com/tmk/267254db25f0039f2e51aa7918666164

HHKB Professional Classic PD-KB401

https://gist.github.com/tmk/5f22878a7ddca01e9174e5d6224395d2

https://gist.github.com/tmk/5e29450724fc30d06681212b0e9b5056

Realforce RGB AEAX01

https://gist.github.com/tmk/7d41f0ca49a21a6c0b2f910d43e9660d

Soarer's Converter

https://gist.github.com/tmk/40a0cc79072a0e5afcd36a599de42bbd

Apple Magic Keyboard model A1644 - 05ac:0267

https://gist.github.com/tmk/0626b78f73575d5c1efa86470c4cdb18

https://github.com/tmk/tmk_keyboard/issues/606

Wacom Intuos S Pen(056a:0374)

https://gist.github.com/tmk/5f2c2fb14fcef03689a21a66f2607ccc

Cherry GmbH G83 (RS 6000) Keyboard - G80-3600LYCEU

https://gist.github.com/tmk/61232069866950aee280623f4901ff84

NuType F1

https://pastebin.com/fTWMypTS https://geekhack.org/index.php?topic=69169.msg2893824#msg2893824

Rosewill RK-9200BR

https://geekhack.org/index.php?topic=69169.msg2897536#msg2897536 https://gist.github.com/tmk/8ee0644a352d8eea3e0f0d584867ddaf

EzKEY Corp. USB to PS2 Adaptor v1.09

https://gist.github.com/tmk/54342906216b07097582965fa653324f

These two adapters are identical electrically.

Arvel AU02-PS
PS2USB2BK

Ducky DK2108

https://gist.github.com/tmk/78dd3ff4507025bcd8b3d574095fe93f

Arduino Uno

CDC interface: https://gist.github.com/tmk/c2cd88429e08e6b9f8e381c04be80d3b

Arduino Leonardo

Bootloader CDC interface: https://gist.github.com/tmk/57898ca51b6f61df9bdb8c2908a3de53

Adafruit Feather

UF2 Bootloader: https://gist.github.com/tmk/ab44c726b06bda1fcdb617b9144161c0

Arduino Sketch: https://gist.github.com/tmk/e7d294052ac864b47c3f0cf1962b24c8

Varmilo MA109C - EC Switch Keyboard

https://gist.github.com/tmk/3e7af2b10b162b9eea853871918a0a2d

Varmilo VA87

https://geekhack.org/index.php?topic=110250.0

Nintendo SWITCH Pro Controller

https://gist.github.com/tmk/9725596c6726b561ad2bf1f1e07e1523

Connectpro UD-12+ KVM - with pluging Hexgears Nova B2 TKL keyboard and a Logitech USB receiver

https://gist.github.com/tmk/2a4026e322a561687485c2537ad4421b

Logitech Receiver

https://gist.github.com/tmk/2a4026e322a561687485c2537ad4421b#file-usbtreeview_report_connectproud-12-kvm-txt-L637-L803

RealForce R2

https://gist.github.com/tmk/7c089602ce7eb70b9be64c7e822be3b9

Adafruit nRF52 Arduino hid_keyboard example

https://gist.github.com/tmk/8e8e6185af93e4e3ccd2660684f9cf7c

Griffin PowerMate

https://forum.pjrc.com/threads/52752-USBHost-for-Griffin-Powermate?p=181527&viewfull=1#post181527

Ducky One 2 Mini

This keyboad doesn't have Boot Keyboard support.

Interface0
    wMaxPacketSize=8
    bInterval=1
    6KRO keyboard(not-boot)
Interface1
    wMaxPacketSize=4
    bInterval=1
Interface2
    wMaxPacketSize=64
    bInterval=1
    **62KRO** keyboard(not-boot)
Interface3
    wMaxPacketSize=4
    bInterval=1
    Consumer keys

https://gist.github.com/tmk/6c9b88c117725446dd768a4270847019

Followings were extracted by USB Device Tree Viewer. No HID Report Descriptor. 1.0.9: https://gist.github.com/tmk/79068a4fcc922e8877691d5518513914

1.0.8?: https://gist.github.com/tmk/2f3a680cfe4cba78b678611032ac20e4

Logitech MX518 Legendary

https://gist.github.com/tmk/2407fdaa73deb35082154c3ba81c84ef

Logitech MX510

https://gist.github.com/tmk/344c185fd2834d2142ae50dccb0916f8

Wacom Intuos S CTL-4100

https://gist.github.com/tmk/2541aa5966fdaa3640f141e3a9d2f4bc

Dygma Raise Keyboard

https://dygma.com/

https://gist.github.com/tmk/5a8dcd84801a33f286c6677f1fa7e914

IK Multimedia iRig Keys - MIDI

https://gist.github.com/tmk/f6ad630003a3052500384188c536a439

Apple Aluminium Keyboard A1243 - 05ac:0250

Keyboard report is compatible to Boot protocol except for the last byte. The last byte is used for Apple vendor specific use, probably related to 'Fn' key.

https://gist.github.com/tmk/34ba298598aa376346ded28144f99a9c

https://gist.github.com/tmk/db28c9b5cb417780fd24077a729c7f2a

Hub in Aluminum Keyboard: https://gist.github.com/tmk/88dd53305e788937fc78fecc7870c470