extmod/machine_usb_device: Add dynamic VID/PID configuration support.

pi-anl · pi-anl · commit 0ee5d1d2b8c8 · 2025-10-20T12:18:52.000+11:00
This commit adds comprehensive VID/PID (Vendor ID/Product ID) configuration
support to the USB device implementation, allowing both runtime and build-time
customization of USB device identification.

Key features:
- Runtime VID/PID properties (usb.vid, usb.pid) for dynamic configuration
- Build-time VID/PID override macros (MICROPY_HW_USB_RUNTIME_VID/PID)
- Dynamic descriptor patching based on custom VID/PID values
- Automatic VID/PID reset on USB deactivation for clean state
- Support for both runtime and static USB device modes
- Validation of VID/PID ranges (1-65535) with proper error handling
- Re-enumeration support in static mode for immediate VID/PID changes

The implementation uses a fallback system where custom VID/PID values
override runtime defaults, which in turn override compile-time defaults.
This provides maximum flexibility for different deployment scenarios.

Files modified:
- extmod/machine_usb_device.c: VID/PID properties and validation logic
- shared/tinyusb/mp_usbd.h: VID/PID structure fields and runtime macros
- shared/tinyusb/mp_usbd_descriptor.c: Dynamic descriptor patching for VID/PID
- docs/library/machine.USBDevice.rst: Comprehensive VID/PID documentation
diff --git a/docs/library/machine.USBDevice.rst b/docs/library/machine.USBDevice.rst
@@ -10,7 +10,7 @@ class USBDevice -- USB Device driver
 
 USBDevice provides a low-level Python API for implementing USB device functions using
 Python code. This includes both runtime device descriptor configuration and
-build-time customization of USB configuration.
+build-time customization of USB Vendor ID (VID) and Product ID (PID).
 
 .. warning:: This low-level API assumes familiarity with the USB standard. There
    are high-level `usb driver modules in micropython-lib`_ which provide a
@@ -412,5 +412,95 @@ Usage Examples
     usb.builtin_driver = usb.BUILTIN_CDC | usb.BUILTIN_NCM
     usb.active(True)
 
+**Custom VID/PID (Runtime Mode):**
+::
+
+    import machine
+
+    # Create custom device descriptor with your VID/PID
+    custom_device_desc = bytearray([
+        18,     # bLength
+        1,      # bDescriptorType (Device)
+        0x00, 0x02,  # bcdUSB (USB 2.0)
+        0x02,   # bDeviceClass (CDC)
+        0x00,   # bDeviceSubClass
+        0x00,   # bDeviceProtocol
+        64,     # bMaxPacketSize0
+        0x34, 0x12,  # idVendor (0x1234)
+        0x78, 0x56,  # idProduct (0x5678)
+        0x00, 0x01,  # bcdDevice (1.0)
+        1,      # iManufacturer
+        2,      # iProduct
+        3,      # iSerialNumber
+        1       # bNumConfigurations
+    ])
+
+    usb = machine.USBDevice()
+    usb.active(False)
+    usb.config(desc_dev=custom_device_desc)
+    usb.builtin_driver = usb.BUILTIN_CDC
+    usb.active(True)
+
+Dynamic VID/PID Configuration
+-----------------------------
+
+**Runtime VID/PID Properties (All Modes):**
+
+Both runtime and non-runtime USB device modes support dynamic VID/PID
+configuration using simple Python properties:
+
+::
+
+    import machine
+
+    usb = machine.USBDevice()
+    usb.active(False)
+
+    # Set custom VID/PID dynamically
+    usb.vid = 0x1234
+    usb.pid = 0x5678
+
+    usb.builtin_driver = usb.BUILTIN_CDC
+    usb.active(True)
+
+    # Check current values
+    print(f"VID: 0x{usb.vid:04X}, PID: 0x{usb.pid:04X}")
+
+    # Reset to firmware defaults
+    usb.active(False)
+    usb.vid = 0  # 0 means use builtin default
+    usb.pid = 0
+    usb.active(True)
+
+**Build-time VID/PID Override:**
+
+For additional customization, VID/PID defaults can be set at build time
+using the ``MICROPY_HW_USB_RUNTIME_VID`` and ``MICROPY_HW_USB_RUNTIME_PID``
+macros:
+
+**Override VID/PID at Build Time:**
+::
+
+    # Build with custom VID/PID
+    make CFLAGS_EXTRA="-DMICROPY_HW_USB_RUNTIME_VID=0x1234 -DMICROPY_HW_USB_RUNTIME_PID=0x5678"
+
+**Port-specific Configuration:**
+::
+
+    # In mpconfigport.h or boards/BOARD/mpconfigboard.h
+    #define MICROPY_HW_USB_RUNTIME_VID (0x1234)
+    #define MICROPY_HW_USB_RUNTIME_PID (0x5678)
+
+This allows customizing the USB VID/PID defaults even when ``MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE``
+is disabled and only built-in drivers are available. If not specified, these
+macros default to ``MICROPY_HW_USB_VID`` and ``MICROPY_HW_USB_PID``.
+
+**VID/PID Property Notes:**
+
+- Properties can only be set when ``usb.active`` is ``False``
+- Setting VID/PID to ``0`` uses the firmware default value
+- Valid range is 1-65535 (0x0001-0xFFFF)
+- Changes are automatically reset when deactivating USB
+- Works in both runtime and non-runtime USB device modes
 
 .. _usb driver modules in micropython-lib: https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme
diff --git a/extmod/machine_usb_device.c b/extmod/machine_usb_device.c
@@ -109,6 +109,8 @@ static mp_obj_t usb_device_make_new(const mp_obj_type_t *type, size_t n_args, si
             o->builtin_driver = MP_OBJ_FROM_PTR(&builtin_none_obj);
         }
         #endif
+        o->custom_vid = 0; // 0 = use builtin default
+        o->custom_pid = 0; // 0 = use builtin default
 
         #if MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
         // Initialize runtime-only fields
@@ -232,6 +234,9 @@ static mp_obj_t usb_device_active(size_t n_args, const mp_obj_t *args) {
             } else {
                 // Disable all classes when deactivating
                 mp_usbd_update_class_state(USB_BUILTIN_FLAG_NONE);
+                // Reset custom VID/PID for clean state
+                usbd->custom_vid = 0;
+                usbd->custom_pid = 0;
             }
             #endif
         }
@@ -582,6 +587,18 @@ static void usb_device_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
         // Load attribute.
         if (attr == MP_QSTR_builtin_driver) {
             dest[0] = self->builtin_driver;
+        } else if (attr == MP_QSTR_vid) {
+            uint16_t vid = self->custom_vid;
+            if (vid == 0) {
+                vid = MICROPY_HW_USB_RUNTIME_VID;
+            }
+            dest[0] = MP_OBJ_NEW_SMALL_INT(vid);
+        } else if (attr == MP_QSTR_pid) {
+            uint16_t pid = self->custom_pid;
+            if (pid == 0) {
+                pid = MICROPY_HW_USB_RUNTIME_PID;
+            }
+            dest[0] = MP_OBJ_NEW_SMALL_INT(pid);
         } else {
             // Continue lookup in locals_dict.
             dest[1] = MP_OBJ_SENTINEL;
@@ -657,6 +674,54 @@ static void usb_device_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
             // Store the builtin_driver (could be legacy constant or new bitfield object)
             self->builtin_driver = dest[1];
             dest[0] = MP_OBJ_NULL;
+        } else if (attr == MP_QSTR_vid) {
+            #if MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
+            // In runtime mode, require deactivation before changing VID
+            if (self->active) {
+                mp_raise_OSError(MP_EINVAL); // Need to deactivate first
+            }
+            #endif
+            mp_int_t vid = mp_obj_get_int(dest[1]);
+            if (vid < 0 || vid > 0xFFFF) {
+                mp_raise_ValueError(MP_ERROR_TEXT("VID must be 0-65535"));
+            }
+            self->custom_vid = (uint16_t)vid;
+
+            #if !MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
+            // In static mode, if USB is active, trigger re-enumeration
+            if (self->active) {
+                #ifndef NO_QSTR
+                tud_disconnect();
+                mp_hal_delay_ms(100);
+                tud_connect();
+                #endif
+            }
+            #endif
+            dest[0] = MP_OBJ_NULL;
+        } else if (attr == MP_QSTR_pid) {
+            #if MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
+            // In runtime mode, require deactivation before changing PID
+            if (self->active) {
+                mp_raise_OSError(MP_EINVAL); // Need to deactivate first
+            }
+            #endif
+            mp_int_t pid = mp_obj_get_int(dest[1]);
+            if (pid < 0 || pid > 0xFFFF) {
+                mp_raise_ValueError(MP_ERROR_TEXT("PID must be 0-65535"));
+            }
+            self->custom_pid = (uint16_t)pid;
+
+            #if !MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
+            // In static mode, if USB is active, trigger re-enumeration
+            if (self->active) {
+                #ifndef NO_QSTR
+                tud_disconnect();
+                mp_hal_delay_ms(100);
+                tud_connect();
+                #endif
+            }
+            #endif
+            dest[0] = MP_OBJ_NULL;
         }
     }
 }
diff --git a/shared/tinyusb/mp_usbd.h b/shared/tinyusb/mp_usbd.h
@@ -97,6 +97,14 @@ static inline void mp_usbd_init_tud(void) {
     #endif
 }
 
+// Allow runtime override of VID/PID defaults
+#ifndef MICROPY_HW_USB_RUNTIME_VID
+#define MICROPY_HW_USB_RUNTIME_VID MICROPY_HW_USB_VID
+#endif
+#ifndef MICROPY_HW_USB_RUNTIME_PID
+#define MICROPY_HW_USB_RUNTIME_PID MICROPY_HW_USB_PID
+#endif
+
 // Individual USB class flags for bitfield operations
 #define USB_BUILTIN_FLAG_NONE  0x00
 #define USB_BUILTIN_FLAG_CDC   0x01
@@ -148,6 +156,9 @@ typedef struct {
     bool active; // Has the user set the USB device active?
     bool trigger; // Has the user requested the active state change (or re-activate)?
 
+    uint16_t custom_vid; // Custom VID (0 = use builtin default)
+    uint16_t custom_pid; // Custom PID (0 = use builtin default)
+
 
     // Temporary pointers for xfer data in progress on each endpoint
     // Ensuring they aren't garbage collected until the xfer completes
@@ -172,6 +183,8 @@ typedef struct {
     mp_obj_base_t base;
     mp_obj_t builtin_driver; // Points to one of mp_type_usb_device_builtin_nnn
     bool active; // Has the user set the USB device active?
+    uint16_t custom_vid; // Custom VID (0 = use builtin default)
+    uint16_t custom_pid; // Custom PID (0 = use builtin default)
 } mp_obj_usb_device_t;
 
 static inline void mp_usbd_init(void) {
diff --git a/shared/tinyusb/mp_usbd_descriptor.c b/shared/tinyusb/mp_usbd_descriptor.c
@@ -46,8 +46,8 @@ const tusb_desc_device_t mp_usbd_builtin_desc_dev = {
     .bDeviceSubClass = MISC_SUBCLASS_COMMON,
     .bDeviceProtocol = MISC_PROTOCOL_IAD,
     .bMaxPacketSize0 = CFG_TUD_ENDPOINT0_SIZE,
-    .idVendor = MICROPY_HW_USB_VID,
-    .idProduct = MICROPY_HW_USB_PID,
+    .idVendor = MICROPY_HW_USB_RUNTIME_VID,
+    .idProduct = MICROPY_HW_USB_RUNTIME_PID,
     .bcdDevice = 0x0100,
     .iManufacturer = USBD_STR_MANUF,
     .iProduct = USBD_STR_PRODUCT,
@@ -353,6 +353,22 @@ const uint16_t *tud_descriptor_string_cb(uint8_t index, uint16_t langid) {
 #if !MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
 
 const uint8_t *tud_descriptor_device_cb(void) {
+    // Check if custom VID/PID is set
+    if (MP_STATE_VM(usbd) != MP_OBJ_NULL) {
+        mp_obj_usb_device_t *usbd = MP_OBJ_TO_PTR(MP_STATE_VM(usbd));
+        if (usbd->custom_vid != 0 || usbd->custom_pid != 0) {
+            // Create custom descriptor with overridden VID/PID
+            static tusb_desc_device_t custom_desc;
+            custom_desc = mp_usbd_builtin_desc_dev; // Copy default
+            if (usbd->custom_vid != 0) {
+                custom_desc.idVendor = usbd->custom_vid;
+            }
+            if (usbd->custom_pid != 0) {
+                custom_desc.idProduct = usbd->custom_pid;
+            }
+            return (const uint8_t*)&custom_desc;
+        }
+    }
     return (const void *)&mp_usbd_builtin_desc_dev;
 }
 
