Merge pull request #47 from r2axz/r2axz-add-uart-interface-names

ADD: interface descriptor device names

README.md

@@ -26,7 +26,7 @@ board works with your computer, don't bother fixing it.
 * 7 or 8 bit word length;
 * None, even, odd parity;
 * 1, 1.5, and 2 stop bits;
-* Works with _CDC Class_ drives on _Linux_, _OS X_, and _Windows_;
+* Works with _CDC Class_ drives on _Linux_, _macOS_, and _Windows_;
 * Supports all baud rates up to 2 MBaud;
 * **TXA** signal for controlling RS-485 transceivers (**DE**, **/RE**);
 * _DMA_ _RX_/_TX_ for high-speed communications;
@@ -106,6 +106,20 @@ by the host. Please take this behaviour into account if you rely on the
 
 _UART DMA RX/TX_ buffer size is **1024** bytes.
 
+## Mapping Logical Port Names to Physical Ports
+
+Unfortunately, operating systems ignore CDC port names reported by the firmware.
+_Linux_ and _macOS_ tend to assign device numbers incrementally so that UART1 gets
+the lowest and UART3 the highest **/dev/ttyACM...** (Linux) or
+**/dev/tty.usbmodem...** (macOS) numbers. On the other hand, _Windows_ can get
+pretty creative when assigning COM port numbers to USB CDC devices.
+
+To find out which physical UART corresponds to a particular COM port on _Windows_,
+open **Device Manager**, right-click on the COM port under **Ports (COM & LPT)**,
+and choose **Properties**. Open the **Details** tab and select
+the **Bus reported device description** property.
+The **Value** field will indicate the physical UART name.
+
 ## Advanced Configuration
 
 _bluepill-serial-monster_ provides a configuration shell that allows

usb_descriptors.c

@@ -67,16 +67,22 @@ const usb_endpoint_t usb_endpoints[usb_endpoint_address_last] = {
     },
 };
 
-const usb_string_descriptor_t usb_string_lang            = USB_ARRAY_DESC(usb_language_code_en_US);
-const usb_string_descriptor_t usb_string_manufacturer    = USB_STRING_DESC("R2AXZ Kirill Kotyagin");
-const usb_string_descriptor_t usb_string_product         = USB_STRING_DESC("Bluepill Serial Monster");
-const usb_string_descriptor_t usb_string_serial          = USB_STRING_DESC("NO SERIAL"); /* Placeholder, replaced by STM32 UID */
+const usb_string_descriptor_t usb_string_lang                   = USB_ARRAY_DESC(usb_language_code_en_US);
+const usb_string_descriptor_t usb_string_manufacturer           = USB_STRING_DESC("R2AXZ Kirill Kotyagin");
+const usb_string_descriptor_t usb_string_product                = USB_STRING_DESC("Bluepill Serial Monster");
+const usb_string_descriptor_t usb_string_serial                 = USB_STRING_DESC("NO SERIAL"); /* Placeholder, replaced by STM32 UID */
+const usb_string_descriptor_t usb_string_uart_1_interface_name  = USB_STRING_DESC("UART1");
+const usb_string_descriptor_t usb_string_uart_2_interface_name  = USB_STRING_DESC("UART2");
+const usb_string_descriptor_t usb_string_uart_3_interface_name  = USB_STRING_DESC("UART3");
 
 const usb_string_descriptor_t *usb_string_descriptors[usb_string_index_last] = {
     &usb_string_lang,
     &usb_string_manufacturer,
     &usb_string_product,
     &usb_string_serial,
+    &usb_string_uart_1_interface_name,
+    &usb_string_uart_2_interface_name,
+    &usb_string_uart_3_interface_name,
 };
 
 const usb_device_descriptor_t usb_device_descriptor = {
@@ -126,7 +132,7 @@ const usb_device_configuration_descriptor_t usb_configuration_descriptor = {
         .bInterfaceClass        = usb_class_cdc,
         .bInterfaceSubClass     = usb_subclass_cdc_acm,
         .bInterfaceProtocol     = USB_PROTOCOL_CDC_DEFAULT,
-        .iInterface             = usb_string_index_none
+        .iInterface             = usb_string_index_uart_1_interface_name,
     },
     .cdc_hdr_0 = {
         .bFunctionLength        = sizeof(usb_configuration_descriptor.cdc_hdr_0),
@@ -208,7 +214,7 @@ const usb_device_configuration_descriptor_t usb_configuration_descriptor = {
         .bInterfaceClass        = usb_class_cdc,
         .bInterfaceSubClass     = usb_subclass_cdc_acm,
         .bInterfaceProtocol     = USB_PROTOCOL_CDC_DEFAULT,
-        .iInterface             = usb_string_index_none
+        .iInterface             = usb_string_index_uart_2_interface_name,
     },
     .cdc_hdr_1 = {
         .bFunctionLength        = sizeof(usb_configuration_descriptor.cdc_hdr_1),
@@ -290,7 +296,7 @@ const usb_device_configuration_descriptor_t usb_configuration_descriptor = {
         .bInterfaceClass        = usb_class_cdc,
         .bInterfaceSubClass     = usb_subclass_cdc_acm,
         .bInterfaceProtocol     = USB_PROTOCOL_CDC_DEFAULT,
-        .iInterface             = usb_string_index_none
+        .iInterface             = usb_string_index_uart_3_interface_name,
     },
     .cdc_hdr_2 = {
         .bFunctionLength        = sizeof(usb_configuration_descriptor.cdc_hdr_2),

usb_descriptors.h

@@ -25,6 +25,9 @@ typedef enum {
     usb_string_index_manufacturer,
     usb_string_index_product,
     usb_string_index_serial,
+    usb_string_index_uart_1_interface_name,
+    usb_string_index_uart_2_interface_name,
+    usb_string_index_uart_3_interface_name,
     usb_string_index_last,
 } __attribute__ ((packed)) usb_string_index_t;