USB Custom Descriptors

[thestumbler]

I have a project with 20 or so RP2350 modules in a single system. The USB interface isn't used in the application, but for development and testing. It is becoming a pain to sort out which com port is which module.

I found a helpful discussion here by user Hippy. This substantially works, and I understand it well. At the end of that discussion it is noted that version 1.23 now includes dynamic USB drivers. Hippy points out: "Crafting initial versions of those is somewhat more complicated than copying what the MicroPython defaults are." I found some examples of dynamic USB code, but they are for changing more advanced aspects of the interface. I can't find any examples, complicated or not, of how to just change the USB descriptors (and serial number).

With that background, here is what I'd like to accomplish. By assigning a custom product descriptor, I can easily grab the desired com port from scripts on the PC. For example, "proto_meter_00, _01, _02, _03", etc. Here's an example I built last night:

Found port  /dev/cu.usbmodem101
   vid/pid       2e8a:0005
   description   proto_meter04
   manufacturer  TheStumbler
   product       proto_meter04
   serial        d589db7044d42859

Taking this approach, however, means that I would have to build a separate UF2 firmware file for each module. A smoother approach would be to make the product descriptor constant, say "proto_meter", and tweak the serial number by appending the meter number to the existing serial number (note that the meter number is read from DIP switches on each module). Ideally I'd like to be able to generate USB descriptors like below and only have a single UF2 firmware build (manually tweaked example of the above):

Found port  /dev/cu.usbmodem101
   vid/pid       2e8a:0005
   description   proto_meter
   manufacturer  TheStumbler
   product       proto_meter
   serial        d589db7044d42859-04

Questions:

(1) [NEW WAY] Are there any examples of changing USB descriptors using the dynamic USB device feature of the latest 1.23 release?

(2) [OLD WAY]

(2a) Applying the approach suggested by Mr Hippy raises a few build issues outside my previous MicroPython experiences. Other than replacing the CMakeLists.txt file in the rp2 directory, what's the usual process for dealing with custom cmake files? I tried to put CMakeLists.txt in my custom build folder, no joy. Then I extracted just the necessary bits into the .cmake file in the custom board folder, but that didn't work either.

(2b) Reading the documentation for the rp2 port closer, it states that the main way to build things is to use cmake, and the make commands are merely a convenience. But I couldn't figure out how to do a cmake-only build, and there are no examples of such that I could find. Perhaps if I knew that, I could have solved (2a) on my own.

(2c) Unlike Hippy, I put my changed USB files in my custom board folder rather than the main rp2 directory. But otherwise I still had to modify the main CMakeLists.txt file in the rp2 folder. But when I looked into changing the serial number, it seems that I have to tweak mp_usbd_port_get_serial_number() in file usbd.c. Is there an accepted way to localize all these changes to only the custom board folder? I'd like to not touch the main MicroPython code at all, and limit the changes to the custom board folder. But I don't know how to do that.

[mattytrentini]

You might want to watch the demo Damien presented on using USBDevice. You're right that the 'new way' allows you to modify the descriptors dynamically, though you'll probably find it much better to use an FTDI cable to connect to the REPL (otherwise, if your REPL is accessed over the same USB, the connection will drop when you update the descriptors).

If you're not already aware, there are some good examples in micropython-lib/usb.

There should be no need to build firmware to modify descriptors.

[thestumbler]

I'm getting much closer. I figured out how to make the strings, but updating the USB descriptor (as opposed to creating a whole new one) is eluding me so far. But I only want to update strings for the default CDC descriptor. There doesn't seem to be a method to only update the string dictionary (nor even examine the current dictionary). But it's after midnight and maybe things will be clearer in the morning.

Here's my start so far:

import machine
import sys
sys.path.extend(['/lib'])

# from shared/tinyusb/tusb_config.h
#    USBD_STR_MANUF (0x01)
#    USBD_STR_PRODUCT (0x02)
#    USBD_STR_SERIAL (0x03)
# from shared/tinyusb/mp_usbd_descriptor.c
#   .iManufacturer = USBD_STR_MANUF,
#   .iProduct = USBD_STR_PRODUCT,
#   .iSerialNumber = USBD_STR_SERIAL,

# string indices in the default descriptor
i_str_manuf = 0x01
i_str_product = 0x02
i_str_serial = 0x03

# module ID (will be read from DIP switches)
module_id = 0x03

# build some strings
str_module_id = f'{module_id:02x}'
str_unique_id = f'{int.from_bytes(machine.unique_id()):x}'
str_serial = f'{str_unique_id}_{str_module_id}'
str_product = f'proto_meter_{module_id:02x}'
str_manuf = 'TheStumbler'

# make the strings dictionary
mystrings = {}
mystrings[0] = None # need this for language
mystrings[i_str_manuf] = str_manuf
mystrings[i_str_product] = str_product
mystrings[i_str_serial] = str_serial

# for s in mystrings.items(): print(s)

desc_dev = machine.USBDevice.BUILTIN_CDC.desc_dev
desc_cfg = machine.USBDevice.BUILTIN_CDC.desc_cfg

# this isn't working, manually or in boot.py
# machine.USBDevice.active(False)
# machine.USBDevice.config(
#  desc_dev, desc_cfg, \
#  desc_strs=mystrings \
# )
# machine.USBDevice.active(True)

When it fails, I get this message:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: argument has wrong type

[thestumbler]

BTW, even though I h ent succeeded yet, I completely prefer this new dynamic method over rebuilding the firmware for each different module ID in my system. I did that last night for just four meters, so I could have some working firmware to begin integration testing. That was a pain in the neck!

I also need to finish watching the presentation you linked. I got about 15 minutes in and said to myself, "Ah ha. I got this" and started trying to implement it. Maybe I missed some key points later on in the video.

[scruss]

It looks like you're using MacOS, so I don't know how easily this is done there. But on Linux, the board with machine.unique_id() == 0ecb4f7dccb7027b appears as serial port /dev/serial/by-id/usb-MicroPython_Board_in_FS_mode_0ecb4f7dccb7027b-if00

[thestumbler]

Yeah, for some reason their BSD style doesn't implement that technique. But even if it did, I'd still have to manually sort out the unique ID for each of 20-some modules and map them in an initialization script. I already do this, because even without that /dev folder, I can see the serial number using various utilities like lsusb.

By making my own custom string descriptors, I can completely automate the init script that scans the usb serial ports and initializes some variables for ease of use.

This init script assigns a shell variable to all 20-some modules in an assembly, and then I have a bunch of aliases to the mpremote and rshell tools. End result, I can simply type mpr0 reset or rs18, etc., to work with any desired meter.