USB VID/PID Specs for devices that support Native USB

[bruno-f-cruz]

Discussed in #28

^{Originally posted by Poofjunior November 26, 2023}
I know many existing Harp devices are built with an FTDI chip doing the heavy work of native USB communication. But with the possibility of future devices being built from a different chip that supports native USB, quite a few options open up in terms of being able to use the OS to identify device types.

I'd love for us to consider reserving usb product IDs for mature Harp devices where possible. Pragmatically, open source projects can use the "gifted" vendor id and reserve a product id, free of charge, through pid.codes.

There are two big benefits to being able to set usb descriptor fields. First, we could deploy a firmware update over USB to a specific device identified by type and serial number.

Second, we could identify device types without needing to guess their COM port, which would streamline connecting a new workstation connected to many Harp devices since we don't need to guess their COM port. It would also avoid issues where COM ports change when we add additional devices after-the-fact--very useful for people building ad-hoc experiment rigs!

Current devices from Harp-Tech wont support these features because the FTDI chip leaves them fixed. Since RP2040-based devices running the harp.core.rp2040 library won't have this constraint, there's a chance for us to define preferred behavior for future devices that can support native USB.

Related: I think putting our devices on pid.codes also give us more visibility to other people who could become future tool developers. There's a whole untapped community of open source embedded and hobbyist EEs for whom footprints made on OSHWA and pid.codes is a form of legitimization of our work. (I am from this community!)

[Poofjunior]

Meeting References (Jan 18, 2024)

• https://www.ftdichip.com/Support/Documents/TechnicalNotes/TN_100_USB_VID-PID_Guidelines.pdf
• https://www.ftdichip.com/Support/Knowledgebase/index.html?usbserialnumbercontrol.htm

Notes from the references above:

• FTDI VID and PIDs are fixed
  • It is possible to change the PID and reserve one through FTDI directly
• It is possible to set a unique serial number (not VID/PID) on the FTDI chip that is instance-specific (2nd link) and is queriable at the USB layer.

The above notes give us a path to be able to make unique serial numbers for existing Harp devices that use FTDI chips.

[Poofjunior]

Here's a proposed specification.

First, note that manufacturer description, product description, and serial number are all queriable fields at the native USB level before attaching a serial port to it (COM0, etc. for Windows, /dev/ttyACM0 etc for Linux.)

For devices, where we can edit these fields (i.e: all devices created with an RP2xx0), I propose:

MANUFACTURER_DESCRIPTION = "Harp Tech"
PRODUCT_DESCRIPTION = "<whoami>.<device_name>"
SERIAL_NUMBER = "<unique_flash_id>" 

Exposing these fields enables us to build automation tools that let us:

• identify all devices of a specific type, and update their firmware
• identify devices by instance number, and assign a specific serial port to it.
  • (Linux distributions using udev do this automatically by creating a symlink to a unique serial port using the above fields)

This can be done in any project using the Allen Harp Core already by adding the following to the top-level project's CMakeLists.txt

add_definitions(-DUSBD_MANUFACTURER="Allen Institute")
add_definitions(-DUSBD_PRODUCT="white-rabbit")