Add usb port or path information

[nxpfrankli]

It is not all devices that provided iserial info.

If two such devices plug into PC, need a method to distinguish it.

ref: libusb/libusb#885 and #250

[Youw]

hidapi itself internally uses path to distinguish/open different devices. Meaning if dev1->path != dev2->path (per character, not per pointer), those are different devices.

Can you clarify what do you mean by distinguish ? What is the use-case?

[nxpfrankli]

I think path here means /dev/hidraw0 or /dev/hidraw1. but hidraw0 or hidraw1 is depend on device plug sequence. If device 1 plug on usb port firstly, it become hidraw0, if device 2 plug on usb port firstly, device 2 will be hidraw0

Now our test program uuu with libusb work like

uuu -m 1:10 image_A ///for board A
uuu -m 1:12 image_B. ///for board B.

Board A and B will be power on off random.

[nxpfrankli]

https://github.com/NXPmicro/mfgtools/wiki/Example#multi-boards-support

[Youw]

If you want uniquly identify a specific device regardless when it was connected, or to which USB port - it is possible only by commenicating with the device itself, e.g. asking its unique ID (yeap, serial_number is most commonly used for this purpose). Otherwise it is literally not possible.

Some platforms (e.g. Windows) - don't even give you an API to ask to which USB port device is connected, or even is it a USB device or not.

Even if you have a USB path of the device (e.g.: bus_no->port_no->...etc.) - it can easily change after reboot/kernel upgrade/another hub connected/etc.
No one guarantees that it can be preserved.

hidapi is a library to work with HID devices. HID != USB. A HID device could be a USB or Bluetooth or I2C or virtual bus-less device.

[nxpfrankli]

1. About reboot and new hub connected, which is quite few happen once whole system setup. bus_no->port_no is preserved at quite long time. We have not met that change at our test farm. Windows provided API to get usb hub information, our old mfgtool use windows native API to get it. Since more and more requirement at linux side, we have to rewrite mfgtools with libusb.

Currently uuu work well with libusb at windows and linux environment. but new mac os requirement coming. That's reason why consider HIDAPI now.

2. just need provide backend device info, USB HID provide a USB port path, bluetooth provide a bt device path, I2C, provide a I2C device address and so on.

[todbot]

The problem is the hidapi path doesn't reflect to any particular protocol, but just a location in the OS's HID driver. This is especially evident on Linux where /dev/hidraw1 can be a USB, BLE or I2C device. HIDAPI has no way of knowing what the underlying hardware protocol is: it's communicating with the OS's HID driver. The same is true for other OSes.

It sounds like your process is: 1. Issue HID command to device to trigger bootloader mode, 2. Issue LIBUSB command to upload new firmware. Is this correct? If so, what if you did something like:

a. Pick a device randomly
b. Issue to it the HID command to go to bootloader
c. Re-enumerate devices in libusb & hidapi
d. Note differences
e. Issue HID command to device not in bootloader mode
f. Now both devices are in bootloader mode
g. Issue command to either device to upload firmware & reset. Device is now in normal mode
h. Issue command to remaining device to upload firmware & reset. Other device is now in normal mode

This algorithm depends on there being some differences detectable in step (d) between the device in bootloader and normal mode (the product_string is different, it doesn't show up in hid_enumerate(), etc.) but otherwise you don't need to know much about the devices. Would this work?

[nxpfrankli]

1. not use HID send a command. but HID download small firmware image, which is difference for difference boards with the same chip (pid and vid is the same).

If the wrong image download by HID, the behavior is unexpected.

[triplef]

I second this suggestion, as it can be crucial to distinguish multiple devices of the same kind being connected.

On macOS kIOHIDLocationIDKey can give you this information, and you can e.g. use that to correlate a CoreMIDI device with a HID device using the USBLocationID property of the MIDIDeviceRef.

However I don’t think there’s currently a way to access or use the location ID with HIDAPI.

[JoergAtGithub]

Let me guess, these "3rd party devices that don’t return a serial number" which require "need to correlate MIDI and HID devices on the same port" are made by PioneerDJ...
and you need to send a keep-alive code over MIDI to enable USB audio...
while the controls use a mixture of MIDI and HID at the same time

[Youw]

are you planning to merge that get-descriptor branch soon?

That's the first thing I'm focused right now. But I really do not have anought capacity to make an estimate "when".

[triplef]

Thanks for your comments on the PR, I'll make those changes shortly.

I do keep wondering though if there's not some better way to support this kind of correlation. The API that you suggested in the PR, while it works, just feels kind of cumbersome with the fact that each device needs to be opened and closed again during enumeration to check its location ID...

I know the library is all about a unified API across platforms, but since this use case will anyway require platform-specific code on the client side, wouldn't it make things a lot easier both in the library and client code if hid_device_info contained a platform-specific device reference (IOHIDDeviceRev on Mac, HANDLE on Windows, etc.) that clients can use directly to implement such behavior on their end?

Anyway, just thinking out loud here. Thanks for working through this with me!

[triplef]

I’ve implemented the API as you suggested on both Mac and Windows, and I guess it works out all right (feel free to ignore my previous comment 😉).

• Mac: Add Mac-specific API to get device location ID #378
• Windows: Add Windows-specific API to get device container ID #379

[Youw]

a platform-specific device reference (IOHIDDeviceRev on Mac, HANDLE on Windows, etc.)

That completely defetes the goal of having a unified cross-platform API.

that clients can use directly to implement such behavior on their end

There is a high chance the user code will break some internal invariance/break the library.

opened and closed again during enumeration

That's a good point - in such case we could have two function: one that accepts the hid device (as I suggested on review), and the other one that accepts the path instead: hid_darwin_get_location_id_from_path.
That way we save resources on creating the full hid_device (e.g. creating a read thread).
As for opening an IOHIDDeviceRef handle - that is relatively cheap operation itself anyway.