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

This commit adds VID/PID (Vendor ID/Product ID) configuration support to
the USB device implementation, allowing both runtime and build-time
customization of USB device identification.

Features include runtime VID/PID properties (usb.vid, usb.pid), build-time
VID/PID override macros, dynamic descriptor patching, and automatic VID/PID
reset on USB deactivation. The implementation uses a fallback system where
custom values override runtime defaults, which override compile-time defaults.

Also fixes USB disconnect/connect in static mode by adding tud_disconnect()
and tud_connect() calls to properly handle device activation and deactivation,
enabling runtime VID/PID changes to take effect.

Signed-off-by: Andrew Leech <[email protected]>

Author: pi-anl

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,134 @@ 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)
+- Custom values persist across active()/inactive() cycles
+- Works in both runtime and non-runtime USB device modes
+
+.. important::
+   **Runtime VID/PID changes work correctly.**
+
+   VID/PID can be changed at runtime using ``active(False)`` → set VID/PID →
+   ``active(True)``. The device will re-enumerate with the new VID/PID values.
+
+   **Note:** On some operating systems (e.g., Windows with WSL), you may need to
+   manually forward the new USB device when the VID/PID changes.
+
+   **Runtime usage:**
+   ::
+
+       import machine
+
+       usb = machine.USBDevice()
+       usb.active(False)
+       usb.vid = 0x1234  # Your custom VID
+       usb.pid = 0x5678  # Your custom PID
+       usb.builtin_driver = usb.BUILTIN_CDC
+       usb.active(True)
+       # Device will enumerate with VID:0x1234 PID:0x5678
+
+   **Persistent configuration (recommended for production):**
+
+   To ensure the custom VID/PID is applied on every boot, place the
+   configuration in ``boot.py``::
+
+       import machine
+
+       usb = machine.USBDevice()
+       usb.active(False)
+       usb.vid = 0x1234  # Your custom VID
+       usb.pid = 0x5678  # Your custom PID
+       usb.builtin_driver = usb.BUILTIN_CDC
+       usb.active(True)
+
+   After saving to ``boot.py``, the device will enumerate with the custom
+   VID/PID on every subsequent boot.
 
 .. _usb driver modules in micropython-lib: https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme

extmod/machine_usb_device.c

@@ -101,6 +101,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
@@ -221,9 +223,17 @@ static mp_obj_t usb_device_active(size_t n_args, const mp_obj_t *args) {
                     mp_obj_usb_builtin_t *builtin = MP_OBJ_TO_PTR(usbd->builtin_driver);
                     mp_usbd_update_class_state(builtin->flags);
                 }
+
+                // Connect to USB host
+                tud_connect();
             } else {
+                // Disconnect from USB host first
+                tud_disconnect();
+
                 // Disable all classes when deactivating
                 mp_usbd_update_class_state(USB_BUILTIN_FLAG_NONE);
+                // Note: custom_vid/pid are NOT reset here - they persist
+                // across deactivation so users can set them before activating
             }
             #endif
         }
@@ -574,22 +584,29 @@ 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;
         }
     } else if (dest[1] != MP_OBJ_NULL) {
         // Store attribute.
         if (attr == MP_QSTR_builtin_driver) {
-            #if MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
-            // In runtime mode, require deactivation before changing builtin_driver
+            // Require deactivation before changing builtin_driver in both modes
             if (self->active) {
-                mp_raise_OSError(MP_EINVAL); // Need to deactivate first
+                mp_raise_OSError(MP_EINVAL);
             }
-            #else
-            // In static mode, allow changing builtin_driver when active
-            // This will update the class state and trigger re-enumeration
-            #endif
 
             // Handle new bitfield builtin types and legacy constants
             uint8_t flags = 0;
@@ -632,23 +649,31 @@ static void usb_device_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
             // Update the internal class state based on flags
             mp_usbd_update_class_state(flags);
 
-            #if !MICROPY_HW_ENABLE_USB_RUNTIME_DEVICE
-            // In static mode, if USB is active, trigger re-enumeration
-            // to update the host with the new configuration
-            if (self->active) {
-                #ifndef NO_QSTR
-                // Disconnect and reconnect to trigger enumeration with new descriptors
-                tud_disconnect();
-                // Small delay to ensure host recognizes disconnection
-                mp_hal_delay_ms(100);
-                tud_connect();
-                #endif
-            }
-            #endif
-
             // 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) {
+            // Require deactivation before changing VID in both modes
+            if (self->active) {
+                mp_raise_OSError(MP_EINVAL);
+            }
+            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;
+            dest[0] = MP_OBJ_NULL;
+        } else if (attr == MP_QSTR_pid) {
+            // Require deactivation before changing PID in both modes
+            if (self->active) {
+                mp_raise_OSError(MP_EINVAL);
+            }
+            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;
+            dest[0] = MP_OBJ_NULL;
         }
     }
 }

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) {

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,
@@ -141,35 +141,41 @@ static const uint8_t *mp_usbd_generate_desc_cfg_unified(uint8_t flags, uint8_t *
     *desc++ = 0x80;                        // bmAttributes (bit 7 must be 1)
     *desc++ = USBD_MAX_POWER_MA / 2;       // bMaxPower (in 2mA units)
 
-    // Add enabled class descriptors
+    // Track current interface number for dynamic assignment
+    uint8_t itf_num = 0;
+
+    // Add enabled class descriptors with dynamically calculated interface numbers
     #if CFG_TUD_CDC
     if (flags & USB_BUILTIN_FLAG_CDC) {
         const uint8_t cdc_desc[] = {
-            TUD_CDC_DESCRIPTOR(USBD_ITF_CDC, USBD_STR_CDC, USBD_CDC_EP_CMD,
+            TUD_CDC_DESCRIPTOR(itf_num, USBD_STR_CDC, USBD_CDC_EP_CMD,
                 USBD_CDC_CMD_MAX_SIZE, USBD_CDC_EP_OUT, USBD_CDC_EP_IN, USBD_CDC_IN_OUT_MAX_SIZE)
         };
         memcpy(desc, cdc_desc, sizeof(cdc_desc));
         desc += sizeof(cdc_desc);
+        itf_num += 2;  // CDC uses 2 interfaces
     }
     #endif
 
     #if CFG_TUD_MSC
     if (flags & USB_BUILTIN_FLAG_MSC) {
         const uint8_t msc_desc[] = {
-            TUD_MSC_DESCRIPTOR(USBD_ITF_MSC, USBD_STR_MSC, USBD_MSC_EP_OUT, USBD_MSC_EP_IN, USBD_MSC_IN_OUT_MAX_SIZE)
+            TUD_MSC_DESCRIPTOR(itf_num, USBD_STR_MSC, USBD_MSC_EP_OUT, USBD_MSC_EP_IN, USBD_MSC_IN_OUT_MAX_SIZE)
         };
         memcpy(desc, msc_desc, sizeof(msc_desc));
         desc += sizeof(msc_desc);
+        itf_num += 1;  // MSC uses 1 interface
     }
     #endif
 
     #if CFG_TUD_NCM
     if (flags & USB_BUILTIN_FLAG_NCM) {
         const uint8_t ncm_desc[] = {
-            TUD_CDC_NCM_DESCRIPTOR(USBD_ITF_NET, USBD_STR_NET, USBD_STR_NET_MAC, USBD_NET_EP_CMD, 64, USBD_NET_EP_OUT, USBD_NET_EP_IN, USBD_NET_IN_OUT_MAX_SIZE, CFG_TUD_NET_MTU)
+            TUD_CDC_NCM_DESCRIPTOR(itf_num, USBD_STR_NET, USBD_STR_NET_MAC, USBD_NET_EP_CMD, 64, USBD_NET_EP_OUT, USBD_NET_EP_IN, USBD_NET_IN_OUT_MAX_SIZE, CFG_TUD_NET_MTU)
         };
         memcpy(desc, ncm_desc, sizeof(ncm_desc));
         desc += sizeof(ncm_desc);
+        itf_num += 2;  // NCM uses 2 interfaces (control + data)
     }
     #endif
 
@@ -345,6 +351,23 @@ 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 (0 means use default)
+    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) {
+            // Patch the default descriptor with custom VID/PID values.
+            // We override whichever fields are non-zero (0 = keep default).
+            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;
 }