Add serial port discovery (#1498)

Co-authored-by: Stefan Rueger <[email protected]>

CMakeLists.txt

@@ -125,6 +125,7 @@ if(USE_STATIC_LIBS)
     set(PREFERRED_LIBFTDI libftdi.a ftdi)
     set(PREFERRED_LIBFTDI1 libftdi1.a ftdi1)
     set(PREFERRED_LIBREADLINE libreadline.a)
+    set(PREFERRED_LIBSERIALPORT libserialport.a)
     set(PREFERRED_LIBGPIOD libgpiod.a gpiod)
 else()
     set(PREFERRED_LIBELF elf)
@@ -134,6 +135,7 @@ else()
     set(PREFERRED_LIBFTDI ftdi)
     set(PREFERRED_LIBFTDI1 ftdi1)
     set(PREFERRED_LIBREADLINE readline)
+    set(PREFERRED_LIBSERIALPORT serialport)
     set(PREFERRED_LIBGPIOD gpiod)
 endif()
 
@@ -225,6 +227,15 @@ elseif(MSVC)
     set(HAVE_LIBREADLINE 1)
 endif()
 
+#-------------------------------------
+# Find libserialport
+
+find_library(HAVE_LIBSERIALPORT NAMES ${PREFERRED_LIBSERIALPORT})
+if(HAVE_LIBSERIALPORT)
+    set(LIB_LIBSERIALPORT ${HAVE_LIBSERIALPORT})
+    set(HAVE_LIBSERIALPORT 1)
+endif()
+
 # -------------------------------------
 # Find libgpiod, if needed
 if(HAVE_LINUXGPIO)
@@ -319,6 +330,7 @@ if (DEBUG_CMAKE)
     message(STATUS "HAVE_LIBFTDI: ${HAVE_LIBFTDI}")
     message(STATUS "HAVE_LIBFTDI1: ${HAVE_LIBFTDI1}")
     message(STATUS "HAVE_LIBREADLINE: ${HAVE_LIBREADLINE}")
+    message(STATUS "HAVE_LIBSERIALPORT: ${HAVE_LIBSERIALPORT}")
     message(STATUS "HAVE_LIBELF_H: ${HAVE_LIBELF_H}")
     message(STATUS "HAVE_LIBELF_LIBELF_H: ${HAVE_LIBELF_LIBELF_H}")
     message(STATUS "HAVE_USB_H: ${HAVE_USB_H}")
@@ -377,6 +389,12 @@ else()
     message(STATUS "DON'T HAVE libreadline")
 endif()
 
+if(HAVE_LIBSERIALPORT)
+    message(STATUS "DO HAVE    libserialport")
+else()
+    message(STATUS "DON'T HAVE libserialport")
+endif()
+
 if(BUILD_DOC)
 	message(STATUS "ENABLED    doc")
 else()

src/Makefile.am

@@ -63,7 +63,7 @@ avrdude_CFLAGS   = @ENABLE_WARNINGS@
 libavrdude_a_CFLAGS   = @ENABLE_WARNINGS@
 libavrdude_la_CFLAGS  = $(libavrdude_a_CFLAGS)
 
-avrdude_LDADD  = $(top_builddir)/$(noinst_LIBRARIES) @LIBUSB_1_0@ @LIBHIDAPI@ @LIBUSB@ @LIBFTDI1@ @LIBFTDI@ @LIBHID@ @LIBELF@ @LIBPTHREAD@ -lm
+avrdude_LDADD  = $(top_builddir)/$(noinst_LIBRARIES) @LIBUSB_1_0@ @LIBHIDAPI@ @LIBUSB@ @LIBFTDI1@ @LIBFTDI@ @LIBHID@ @LIBELF@ @LIBPTHREAD@ @LIBSERIALPORT@ -lm
 
 bin_PROGRAMS = avrdude
 

src/avrdude.1

@@ -601,20 +601,53 @@ Note that the result will be stored in the EEPROM cell at address 0.
 .It Fl P Ar port
 Use
 .Ar port
-to identify the device to which the programmer is attached.  By
-default the
-.Pa /dev/ppi0
-port is used, but if the programmer type normally connects to the
-serial port, the
-.Pa /dev/cuaa0
-port is the default.  If you need to use a different parallel or
-serial port, use this option to specify the alternate port name.
+to identify the connection through which the programmer is attached. This
+can be a parallel, serial, spi or linuxgpio connection. The programmer
+normally specifies the connection type; in absence of a -P specification,
+system-dependent default values
+.Pa default_parallel ,
+.Pa default_serial ,
+.Pa default_spi ,
+or
+.Pa default_linuxgpio
+from the configuration file are used. If you need to use a different port,
+use this option to specify the alternate port name.
+.Pp
+If
+.Nm
+has been configured with libserialport support, a serial port can be specified
+using a predefined serial adapter type in avrdude.conf or .avrduderc, e.g.,
+.Ar ch340
+or
+.Ar ft232r .
+If more than one serial adapter of the same type is connected, they can be
+distinguished by appending a serial number, e.g.,
+.Ar ft232r:12345678 .
+Note that the USB to serial chip has to have a serial number for this to work.
+.Nm Avrdude
+can check for leading and trailing serial number matches as well.
+In the above example,
+.Ar ft232r:1234
+would also result in a match, and so would
+.Ar ft232r:...5678 .
+If the USB to serial chip is not known to
+.Nm ,
+it can be specified using the hexadecimal USB vendor ID, hexadecimal
+product ID and an optional serial number, following the serial number
+matching rules described above, e.g.,
+.Ar usb:0x2341:0x0043
+or
+.Ar usb:2341:0043:12345678 .
+To see a list of currently plugged-in serial ports use -P ?s. In order to
+see a list of all possible serial adapters known to
+.Nm
+use -P ?sa.
 .Pp
 On Win32 operating systems, the parallel ports are referred to as lpt1
 through lpt3, referring to the addresses 0x378, 0x278, and 0x3BC,
 respectively.  If the parallel port can be accessed through a different
 address, this address can be specified directly, using the common C
-language notation (i. e., hexadecimal values are prefixed by
+language notation (i.e., hexadecimal values are prefixed by
 .Ql 0x
 ).
 .Pp
@@ -984,7 +1017,6 @@ See below for a list of programmers accepting extended parameters
 or issue
 .Nm
 -x help ... to see the extended options of the chosen programmer.
-
 .El
 .Ss Terminal mode
 In this mode,
@@ -1873,7 +1905,7 @@ avrdude: Target prepared for ISP, signed off.
 avrdude: Please restart avrdude without power-cycling the target.
 .Ed
 .Pp
-If the target AVR has been set up for debugWire mode (i. e. the
+If the target AVR has been set up for debugWire mode (i.e., the
 .Em DWEN
 fuse is programmed), normal ISP connection attempts will fail as
 the
@@ -1919,7 +1951,7 @@ one byte at a time.
 For that reason, updating the flash ROM from terminal mode does not
 work.
 .Pp
-Page-mode programming the EEPROM through JTAG (i.e. through an
+Page-mode programming the EEPROM through JTAG (i.e., through an
 .Fl U
 option) requires a prior chip erase.
 This is an inherent feature of the way JTAG EEPROM programming works.

src/avrdude.conf.in

@@ -2967,6 +2967,50 @@ serialadapter
     usbpid                 = 0x7523;
 ;
 
+#------------------------------------------------------------
+# ch9102
+#------------------------------------------------------------
+
+serialadapter
+    id                     = "ch9102";
+    desc                   = "WCH CH9102 USB to serial adapter";
+    usbvid                 = 0x1a86;
+    usbpid                 = 0x55d4;
+;
+
+#------------------------------------------------------------
+# cp210x
+#------------------------------------------------------------
+
+serialadapter
+    id                     = "cp210x";
+    desc                   = "Silabs CP210x USB to serial adapter";
+    usbvid                 = 0x10c4;
+    usbpid                 = 0xea60, 0xea70, 0xea71;
+;
+
+#------------------------------------------------------------
+# ft231x / ft234x / ft230x
+#------------------------------------------------------------
+
+serialadapter
+    id                     = "ft231x", "ft234x", "ft230x";
+    desc                   = "FTDI FT23X series USB to serial adapter";
+    usbvid                 = 0x0403;
+    usbpid                 = 0x6015;
+;
+
+#------------------------------------------------------------
+# pl2303
+#------------------------------------------------------------
+
+serialadapter
+    id                     = "pl2303";
+    desc                   = "Profilic PL2303 USB to serial adapter";
+    usbvid                 = 0x067b;
+    usbpid                 = 0x2303;
+;
+
 #
 # PART DEFINITIONS
 #

src/cmake_config.h.in

@@ -99,3 +99,6 @@
 
 /* Define to 1 if you have the `readline' library (-lreadline). */
 #cmakedefine HAVE_LIBREADLINE 1
+
+/* Define to 1 if you have the `serialport' library */
+#cmakedefine HAVE_LIBSERIALPORT 1

src/configure.ac

@@ -185,6 +185,19 @@ if test x$have_libhidapi = xyes; then
 fi
 AC_SUBST(LIBHIDAPI, $LIBHIDAPI)
 
+AH_TEMPLATE([HAVE_LIBSERIALPORT],
+            [Define if libserialport is found])
+AC_CHECK_LIB([serialport], [sp_open], [have_libserialport=yes])
+if test x$have_libserialport = xyes; then
+   case $target in
+       *)
+               LIBSERIALPORT="-lserialport"
+               ;;
+   esac
+   AC_DEFINE([HAVE_LIBSERIALPORT])
+   AC_CHECK_HEADERS([libserialport.h])
+fi
+AC_SUBST(LIBSERIALPORT, $LIBSERIALPORT)
 
 AH_TEMPLATE([HAVE_LIBFTDI1],
             [Define if FTDI support is enabled via libftdi1])
@@ -604,6 +617,12 @@ else
    echo "DON'T HAVE libreadline"
 fi
 
+if test x$have_libserialport = xyes; then
+   echo "DO HAVE    libserialport"
+else
+   echo "DON'T HAVE libserialport"
+fi
+
 if test x$have_pthread = xyes; then
    echo "DO HAVE    pthread"
 else

src/doc/avrdude.texi

@@ -373,7 +373,7 @@ Windows programming software.
 For many years, the AVRDUDE source resided in public repositories on
 savannah.nongnu.org,
 where it continued to be enhanced and ported to other systems.  In
-addition to FreeBSD, AVRDUDE now runs on Linux and Windows.  The
+addition to FreeBSD, AVRDUDE now runs on Linux, MacOS and Windows.  The
 developers behind the porting effort primarily were Ted Roth, Eric
 Weddington, and J@"org Wunsch.
 
@@ -680,12 +680,30 @@ hardware.
 Note that the result will be stored in the EEPROM cell at address 0.
 
 @item -P @var{port}
-Use port to identify the device to which the programmer is attached.
-Normally, the default parallel port is used, but if the programmer type
-normally connects to the serial port, the default serial port will be
-used. See Appendix A, Platform Dependent Information, to find out the
-default port names for your platform. If you need to use a different
-parallel or serial port, use this option to specify the alternate port name.
+
+Use @var{port} to identify the connection through which the programmer is
+attached. This can be a parallel, serial, spi or linuxgpio connection. The
+programmer normally specifies the connection type; in absence of a @code{-P}
+specification, system-dependent default values @code{default_parallel},
+@code{default_serial}, @code{default_spi}, or @code{default_linuxgpio} from
+the configuration file are used. If you need to use a different port, use this
+option to specify the alternate port name.
+
+If avrdude has been configured with libserialport support, a serial port can
+be specified using a predefined serial adapter type in @var{avrdude.conf} or
+@var{.avrduderc}, e.g., @code{ch340} or @code{ft232r}. If more than one serial
+adapter of the same type is connected, they can be distinguished by appending
+a serial number, e.g., @code{ft232r:12345678}. Note that the USB to serial
+chip has to have a serial number for this to work. Avrdude can check for
+leading and trailing serial number matches as well. In the above example,
+@code{ft232r:1234} would also result in a match, and so would
+@code{ft232r:...5678}. If the USB to serial chip is not known to avrdude, it
+can be specified using the hexadecimal USB vendor ID, hexadecimal product ID
+and an optional serial number, following the serial number matching rules
+described above, e.g., @code{usb:0x2341:0x0043} or
+@code{usb:2341:0043:12345678}. To see a list of currently plugged-in serial
+ports use @code{-P ?s}. In order to see a list of all possible serial adapters
+known to avrdude use @code{-P ?sa}.
 
 On Win32 operating systems, the parallel ports are referred to as lpt1
 through lpt3, referring to the addresses 0x378, 0x278, and 0x3BC,
@@ -1762,7 +1780,7 @@ $ avrdude -cusbasp -pattiny13 -Ueeprom:r:-:i 2>/dev/null
 $ avrdude -pattiny13 -qq -U flash:r:-:r | strings
 
 Main menu
-Distance: %dcm
+Distance: %d cm
 Exit
 
 @end cartouche
@@ -1827,6 +1845,52 @@ AVR64EA48
 @end smallexample
 
 @page
+
+@noindent
+@strong{List of all curently plugged-in serial devices known to the libserialport library:}
+
+@smallexample
+@cartouche
+
+$ avrdude -P ?s
+Possible candidate serial ports are:
+  -P /dev/ttyUSB0 or -P ft232r:A600K203
+  -P /dev/ttyUSB1 or -P ft232r:MCU8
+  -P /dev/ttyUSB3, -P ch340 or -P ch340-115k
+Note that above ports might not be connected to a target board or an AVR programmer.
+Also note there may be other direct serial ports not listed above.
+
+@end cartouche
+@end smallexample
+
+
+@noindent
+@strong{List of all serial adapters known to AVRDUDE, i.e., defined in avrdude.conf:}
+
+@smallexample
+@cartouche
+
+$ avrdude -P ?sa
+Valid serial adapters are:
+  ch340      = [usbvid 0x1a86, usbpid 0x7523]
+  ch340-115k = [usbvid 0x1a86, usbpid 0x7523]
+  ch341a     = [usbvid 0x1a86, usbpid 0x5512]
+  ch9102     = [usbvid 0x1a86, usbpid 0x55d4]
+  cp210x     = [usbvid 0x10c4, usbpid 0xea60 0xea70 0xea71]
+  ft2232h    = [usbvid 0x0403, usbpid 0x6010]
+  ft231x     = [usbvid 0x0403, usbpid 0x6015]
+  ft234x     = [usbvid 0x0403, usbpid 0x6015]
+  ft230x     = [usbvid 0x0403, usbpid 0x6015]
+  ft232h     = [usbvid 0x0403, usbpid 0x6014]
+  ft232r     = [usbvid 0x0403, usbpid 0x6001]
+  ft4232h    = [usbvid 0x0403, usbpid 0x6011]
+  pl2303     = [usbvid 0x067b, usbpid 0x2303]
+
+@end cartouche
+@end smallexample
+
+@page
+
 @noindent
 @strong{AVRDUDE in a bash script creating terminal scripts that reset a part to factory settings:}
 @smallexample

src/libavrdude.h

@@ -1249,6 +1249,10 @@ typedef struct {
 extern "C" {
 #endif
 
+int setport_from_serialadapter(char **portp, const SERIALADAPTER *ser, const char *sernum);
+int setport_from_vid_pid(char **portp, int vid, int pid, const char *sernum);
+int list_available_serialports(LISTID programmers);
+
 int str_starts(const char *str, const char *starts);
 int str_eq(const char *str1, const char *str2);
 int str_contains(const char *str, const char *substr);
@@ -1265,6 +1269,7 @@ char *str_uc(char *s);
 char *str_lcfirst(char *s);
 char *str_ucfirst(char *s);
 char *str_utoa(unsigned n, char *buf, int base);
+char *str_endnumber(const char *str);
 const char *str_plural(int x);
 const char *str_inname(const char *fn);
 const char *str_outname(const char *fn);