Merge pull request #15651 from bergzand/pr/usbus/gen_serial

usbus: Add USB peripheral serial string support

sys/Makefile.dep

@@ -951,6 +951,8 @@ ifneq (,$(filter usbus,$(USEMODULE)))
   DEFAULT_MODULE += auto_init_usbus
   USEMODULE += core_thread_flags
   USEMODULE += event
+  USEMODULE += luid
+  USEMODULE += fmt
   ifeq (,$(filter usbdev_mock,$(USEMODULE)))
     FEATURES_REQUIRED += periph_usbdev
   endif

sys/include/usb.h

@@ -96,6 +96,32 @@ extern "C" {
 #define CONFIG_USB_CONFIGURATION_STR    "USB config"
 #endif
 
+/**
+ * @brief USB peripheral serial string
+ *
+ * Compile-time value to override the serial string with. An LUID-based hex
+ * string is generated when this value is not used.
+ *
+ * This string does not have to be a number, but it must be unique between
+ * devices with identical VID:PID combination.
+ */
+#ifdef DOXYGEN
+#define CONFIG_USB_SERIAL_STR           "RIOT-12345"
+#endif
+
+/**
+ * @brief USB peripheral serial string length
+ *
+ * Maximum value is 63. Sensible values are between 8 to 32 depending on the
+ * number of expected devices.
+ *
+ * The length here is in bytes. The generated hex string is twice as many chars
+ * in length due to conversion from bytes to hex chars.
+ */
+#if !defined(CONFIG_USB_SERIAL_STR) && !defined(CONFIG_USB_SERIAL_BYTE_LENGTH)
+#define CONFIG_USB_SERIAL_BYTE_LENGTH 8
+#endif
+
 /**
  * @brief USB peripheral device version
  *

sys/include/usb/usbus.h

@@ -399,6 +399,7 @@ struct usbus {
     usbus_string_t manuf;                           /**< Manufacturer string                   */
     usbus_string_t product;                         /**< Product string                        */
     usbus_string_t config;                          /**< Configuration string                  */
+    usbus_string_t serial;                          /**< serial string                  */
     usbus_endpoint_t ep_out[USBDEV_NUM_ENDPOINTS];  /**< USBUS OUT endpoints                   */
     usbus_endpoint_t ep_in[USBDEV_NUM_ENDPOINTS];   /**< USBUS IN endpoints                    */
     event_queue_t queue;                            /**< Event queue                           */
@@ -415,6 +416,12 @@ struct usbus {
     usbus_state_t state;                            /**< Current state                         */
     usbus_state_t pstate;                           /**< state to recover to from suspend      */
     uint8_t addr;                                   /**< Address of the USB peripheral         */
+#ifndef CONFIG_USB_SERIAL_STR
+    /**
+     * @brief Hex representation of the device serial number
+     */
+    char serial_str[2 * CONFIG_USB_SERIAL_BYTE_LENGTH + 1];
+#endif
 };
 
 /**

sys/usb/Kconfig

@@ -81,6 +81,32 @@ config USB_DEFAULT_LANGID
     help
         The default value is EN-US (0x0409).
 
+config USB_CUSTOM_SERIAL_STR
+    bool "Configure a custom USB serial string"
+
+config USB_SERIAL_STR
+    string "Serial string"
+    depends on USB_CUSTOM_SERIAL_STR
+    help
+        USB peripheral serial string
+
+        Compile-time value to override the serial string with. An LUID-based hex
+        string is generated when this value is not used.
+
+        This string does not have to be a number, but it must be unique between
+        devices with identical VID:PID combination.
+
+config USB_SERIAL_BYTE_LENGTH
+    int "USB peripheral serial string length"
+    depends on !USB_CUSTOM_SERIAL_STR
+    range 0 63
+    default 8
+    help
+        The length here is in bytes. The generated hex string is twice as many chars
+        in length due to conversion from bytes to hex chars.
+
+comment "WARNING: The serial string is empty!"
+    depends on USB_SERIAL_STR = "" && USB_CUSTOM_SERIAL_STR
 
 rsource "usbus/Kconfig"
 endif # KCONFIG_USB

sys/usb/usbus/usbus.c

@@ -21,6 +21,8 @@
 #include "kernel_defines.h"
 #include "bitarithm.h"
 #include "event.h"
+#include "fmt.h"
+#include "luid.h"
 #include "thread.h"
 #include "thread_flags.h"
 #include "periph/usbdev.h"
@@ -254,6 +256,18 @@ static void *_usbus_thread(void *args)
     usbus_add_string_descriptor(usbus, &usbus->product, CONFIG_USB_PRODUCT_STR);
     usbus_add_string_descriptor(usbus, &usbus->manuf, CONFIG_USB_MANUF_STR);
 
+#ifdef CONFIG_USB_SERIAL_STR
+    usbus_add_string_descriptor(usbus, &usbus->serial, CONFIG_USB_SERIAL_STR);
+#else
+    static_assert(CONFIG_USB_SERIAL_BYTE_LENGTH <= UINT8_MAX/4,
+                  "USB serial byte length must be at most 63 due to protocol "
+                  "limitations");
+    uint8_t luid_buf[CONFIG_USB_SERIAL_BYTE_LENGTH];
+    luid_get(luid_buf, sizeof(luid_buf));
+    fmt_bytes_hex(usbus->serial_str, luid_buf, sizeof(luid_buf));
+    usbus_add_string_descriptor(usbus, &usbus->serial, usbus->serial_str);
+#endif
+
     usbus->state = USBUS_STATE_DISCONNECT;
 
     /* Initialize handlers */

sys/usb/usbus/usbus_fmt.c

@@ -288,6 +288,7 @@ size_t usbus_fmt_descriptor_dev(usbus_t *usbus)
     desc.product_id = CONFIG_USB_PID;
     desc.manufacturer_idx = usbus->manuf.idx;
     desc.product_idx = usbus->product.idx;
+    desc.serial_idx = usbus->serial.idx;
     /* USBUS supports only a single config at the moment */
     desc.num_configurations = 1;
     usbus_control_slicer_put_bytes(usbus, (uint8_t *)&desc,