HID report descriptors of USB device with multiple HID interfaces

[jonesliu-eaton]

We used to use libUSB library before, but we need to switch to the hid API library.
Previously, reading two descriptors through libUSB was done using the following method：
int len = usb_control_msg(hidif->dev_handle,
USB_ENDPOINT_IN+1,
USB_REQ_GET_DESCRIPTOR,
(USB_DT_REPORT << 8) + 1, hidif->interfa,
(char*)hidif->ReportDesc, hidif->ReportDescSize,
USB_TIMEOUT);

But now, only the first descriptor can be obtained through the hid API, not the second one
unsigned char descriptor[REPORT_DSC_SIZE];
len = hid_get_report_descriptor(hidif->handle, hidif->ReportDesc, sizeof(descriptor));

So, How can I get two descriptors via hid API library??

[Youw]

I'm not sure what do you mean. HID device only supposed to have a single HID Report descriptor.

If you have two HID devices on the same USB but on different interfaces - you need to open those separately (available as different devices when hid_enumerate), and get a report descriptor from each device respectively.

[jonesliu-eaton]

I'm referring to one USB HID device, which has two independent HID interfaces (each with a report descriptor).

for libusb:
(USB_DT_REPORT << 8) ----report descriptor index is 0
(USB_DT_REPORT << 8) + 1 ----report descriptor index is 1

so, If I want to get two descriptor , I just use this meter " (USB_DT_REPORT << 8) + 1"
I print the length of report descriptor is 2555---Heavyweight report descriptor

but for hidAPI:
hid_get_report_descriptor(hidif->handle, hidif->ReportDesc, sizeof(descriptor));----this method obtain report descriptor for index 0.
I print the length of report descriptor is 1826 ------Lightweight report descriptor

Copilot prompts me to use the winUSB library（for windows） to read dual descriptors and use "IOHIDDeviceCopyMatchingElements" for MacOSX.

#define _CRT_SECURE_NO_WARNINGS
#include <windows.h>
#include <setupapi.h>
#include <hidsdi.h>
#include <winusb.h>
#include <stdio.h>
#include "hidapi.h"
#pragma comment(lib, "setupapi.lib")
#pragma comment(lib, "hid.lib")
#pragma comment(lib, "winusb.lib")

// Modify these to your device VID/PID
#define VID 0x1234
#define PID 0x5678

void print_hex(const unsigned char* data, int len) {
for (int i = 0; i < len; i++) {
printf("%02X ", data[i]);
if ((i % 16) == 15) printf("\n");
}
printf("\n");
}

// ----------------------------
// Read Report Descriptor#1 via WinUSB control transfer
// ----------------------------
BOOL GetReportDesc_Index1_WinUSB(HANDLE hDev, UCHAR* buf, ULONG bufSize, ULONG* outLen)
{
WINUSB_INTERFACE_HANDLE hWinUSB = NULL;
if (!WinUsb_Initialize(hDev, &hWinUSB)) {
printf("WinUsb_Initialize failed.\n");
return FALSE;
}

WINUSB_SETUP_PACKET pkt;
ZeroMemory(&pkt, sizeof(pkt));

// GET_DESCRIPTOR(Report, index=1)
pkt.RequestType = 0x81; // IN + Standard + Interface
pkt.Request = USB_REQUEST_GET_DESCRIPTOR; // 0x06
pkt.Value = (USB_DESCRIPTOR_TYPE_REPORT << 8) | 1;  // Report desc, index=1
pkt.Index = 0;  // interface 0, modify if your HID interface is >0
pkt.Length = (USHORT)bufSize;

BOOL ok = WinUsb_ControlTransfer(hWinUSB, pkt, buf, bufSize, outLen, NULL);
WinUsb_Free(hWinUSB);
return ok;

}

// ----------------------------
// Main
// ----------------------------
int main()
{
printf("=== HID Dual Descriptor Reader (Windows) ===\n");

hid_init();

// 1. Enumerate HID device using hidapi
struct hid_device_info* devs = hid_enumerate(VID, PID);
if (!devs) {
    printf("Device not found.\n");
    return -1;
}
printf("Device path: %s\n", devs->path);

// 2. Open device using Windows CreateFile
HANDLE h = CreateFileA(
    devs->path,
    GENERIC_READ | GENERIC_WRITE,
    FILE_SHARE_READ | FILE_SHARE_WRITE,
    NULL,
    OPEN_EXISTING,
    FILE_FLAG_OVERLAPPED,
    NULL
);

if (h == INVALID_HANDLE_VALUE) {
    printf("CreateFile failed.\n");
    return -1;
}

// 3. Read Report Descriptor #0 via HidD_GetReportDescriptor
UCHAR report0[4096];
memset(report0, 0, sizeof(report0));

if (HidD_GetReportDescriptor(h, report0, sizeof(report0))) {
    printf("\n[Report Descriptor #0]\n");
    print_hex(report0, 128); // print first 128 bytes
} else {
    printf("HidD_GetReportDescriptor failed.\n");
}

// 4. Read Physical Descriptor
UCHAR phys[4096];
memset(phys, 0, sizeof(phys));

if (HidD_GetPhysicalDescriptor(h, phys, sizeof(phys))) {
    printf("\n[Physical Descriptor]\n");
    print_hex(phys, 128);
} else {
    printf("HidD_GetPhysicalDescriptor failed.\n");
}

// 5. Read Report Descriptor #1 (if exists) via WinUSB control transfer
printf("\n[Report Descriptor #1 via WinUSB]\n");
UCHAR report1[4096];
memset(report1, 0, sizeof(report1));
ULONG actLen = 0;

if (GetReportDesc_Index1_WinUSB(h, report1, sizeof(report1), &actLen)) {
    printf("Success, length = %lu\n", actLen);
    print_hex(report1, actLen);
} else {
    printf("No Descriptor #1, or device doesn't support multiple report descriptors.\n");
}

CloseHandle(h);
hid_free_enumeration(devs);
hid_exit();
return 0;

}

[jonesliu-eaton]

for libusb

read light descriptor(one report descriptor):

int len = usb_control_msg(hidif->dev_handle,
USB_ENDPOINT_IN+1,
USB_REQ_GET_DESCRIPTOR,
(USB_DT_REPORT << 8), hidif->interfa, // Report desc, index=0
(char*)hidif->ReportDesc, hidif->ReportDescSize,
USB_TIMEOUT);

read weight descriptor(two report descriptor):
int len = usb_control_msg(hidif->dev_handle,
USB_ENDPOINT_IN+1,
USB_REQ_GET_DESCRIPTOR,
(USB_DT_REPORT << 8) + 1, hidif->interfa, // Report desc, index=1
(char*)hidif->ReportDesc, hidif->ReportDescSize,
USB_TIMEOUT);

So, Is there a quick method to get weight descriptor?

[Youw]

So as I mentioned before: a single USB device with two HID interfaces are two different logical HID devices and those are represented as two different logical hid_device-es.
You should get two different devices when you hid_enumerate(vid, pid) and you can open them separately with hid_open_path. Then you hid_get_report_descriptor separately on each of those.

[jonesliu-eaton]

What I understand is that a device has a unique handle, even if the PID/VID is the same. But according to your statement, a device will have two handles, each handle will retrieve a different descriptor.

If I had two devices, the PVD/VID is the same. How can I distinguish the interface of individual devices.

For example, device A and device B have the same PID/VID. Device A having interfaces 1 and 2 and device B having interfaces 3 and 4. I need to read the descriptors of interface 1 and 2 from device A, concatenate the two descriptor buffers, and return them to device A. Then, I need to read the descriptors of interface 3 and 4 from device B, concatenate the two descriptor buffers, and return them to device B.

[jonesliu-eaton]

This is my code for get handle, I need to pass VID/PID array, serial number as parameters.

typedef struct HIDInterfaceMatcher_t {
  unsigned short vendor_id;
  unsigned short product_id;
} HIDInterfaceMatcher;

typedef struct HIDInterface_t {
	hid_device *handle;
	unsigned short vendorId;
	unsigned short productId;
	uchar   ReportDesc[REPORT_DSC_SIZE];  /*!< Store Report Descriptor          */
	ushort  ReportDescSize;               /*!< Size of Report Descriptor        */
} HIDInterface;

static hid_return hid_get_usb_handleOne(HIDInterface* const hidif,unsigned short vendorId,
	int deviceIndex,const char *pSerialNum,HIDInterfaceMatcher const* const matcher,int length)
{
	if (!hidif) 
		return HID_RET_DEVICE_NOT_FOUND;
	int count = 0;
	HIDInterfaceMatcher const* tempMatch = matcher;
	for (int i = 0; i < length; i++, tempMatch++) {
		struct hid_device_info* info = hid_enumerate(tempMatch->vendor_id,tempMatch->product_id);
		struct hid_device_info* devs = info;
		while (devs) {
			/* --- Serial number match case --- */
			if (pSerialNum && pSerialNum[0]) {
				char* serial = WcharToCharStr(devs->serial_number);
				if (serial) {
					if (strcmp(pSerialNum, serial) == 0) {
						printf("found serial %s device\n", pSerialNum);
						free(serial);
						hid_device* handle = hid_open_path(devs->path);
						hidif->handle = handle;
						hidif->vendorId = tempMatch->vendor_id;
						hidif->productId = tempMatch->product_id;
						hid_free_enumeration(info);
						return HID_RET_SUCCESS;
					}
					free(serial);
				}
			}
			/* --- Index match case --- */
			else if (count == deviceIndex) {  //if the device has no serial number, use device index
				printf("found index %d device\n", deviceIndex);
				hid_device* handle = hid_open_path(devs->path);
				hidif->handle = handle;
				hidif->vendorId = tempMatch->vendor_id;
				hidif->productId = tempMatch->product_id;
				hid_free_enumeration(info);
				return HID_RET_SUCCESS;
			}
			count++;
			devs = devs->next;
		}
		hid_free_enumeration(info);
	}
	printf("no matching USB device found.\n");
	return HID_RET_DEVICE_NOT_FOUND;
}

This is my code for getting descriptor, I need to pass in a handle as the parameter to get the descriptor：

static hid_return hid_prepare_report_descriptor(HIDInterface* const hidif)
{
	if (!hidif || !hidif->handle) {
		return HID_RET_FAIL_GET_REPORT;
	}
#if HID_API_VERSION >= HID_API_MAKE_VERSION(0, 14, 0)

	// IMPORTANT: HIDAPI returns int, not unsigned!
	int len = hid_get_report_descriptor(hidif->handle,hidif->ReportDesc,sizeof(hidif->ReportDesc));

	if (len < 0) {
		printf("Failed to get report descriptor, error = %d\n", len);
		return HID_RET_FAIL_GET_REPORT;
	}
	hidif->ReportDescSize = len;
	printf("Report Descriptor length = %d bytes\n", len);
	// Print the descriptor correctly
	for (int i = 0; i < len; i++) {
		if (i % 10 == 0) {
			printf("\n");
		}
		printf("0x%02X, ", hidif->ReportDesc[i]);
	}
	printf("\n");
#else
	(void)hidif; // suppress unused warning
	return HID_RET_FAIL_GET_REPORT;  // Not supported
#endif
	return HID_RET_SUCCESS;
}

[Youw]

If I had two devices, the PVD/VID is the same. How can I distinguish the interface of individual devices.

Since that is the same USB device, VID/PID and serial_number is going to be the same. Since USB interfaces are different - interface_number will be different.

[jonesliu-eaton]

If I had two devices, the PVD/VID is the same. How can I distinguish the interface of individual devices.

Since that is the same USB device, VID/PID and serial_number is going to be the same. Since USB interfaces are different - interface_number will be different.

What I understand is that a device has a unique handle, even if the PID/VID is the same. But according to your statement, a device will have two handles, each handle will retrieve a different descriptor.

[Youw]

What I understand is that a device has a unique handle, even if the PID/VID is the same

Which device? The thing is that HIDAPI doesn't provide a handle to USB device. It provides a handle to HID device, which is an interface abstraction, and not a USB device abstraction.

Your single physical USB device has two different HID devices, and those are two different (HID) device handles, so you should open them something like (not tested psuedo code):

struct hid_device_info* info = hid_enumerate(tempMatch->vendor_id,tempMatch->product_id);
struct hid_device_info* dev_info = info;
while (devs) {
	char* serial = WcharToCharStr(dev_info->serial_number);
	if (serial) {
		if (strcmp(pSerialNum, serial) == 0) {
			printf("found HID device, serial: %s , USB interface: %d, path: %s\n", pSerialNum, dev_info->interface_number, dev_info->path);
			if (dev_info->interface_number == 1) {
			    hidif->handle_i1 = hid_open_path(dev_info->path);
			}
			if (dev_info->interface_number == 2) {
			    hidif->handle_i2 = hid_open_path(dev_info->path);
			}
			hidif->vendorId = tempMatch->vendor_id;
			hidif->productId = tempMatch->product_id;
		}
		free(serial);
	}
}
hid_free_enumeration(info);
if (hidif->handle_i1 && hidif->handle_i2) {
    return HID_RET_SUCCESS;
}
hid_close(handle_i1);
hid_close(handle_i2);
hidif->handle_i1 = NULL;
hidif->handle_i2 = NULL;
return HID_RET_DEVICE_NOT_FOUND;

And later get two descriptors separately from handle_i1 and handle_i2.