From e684c8df1c3ab26cdf9c6fc7fdb1f1ac8d04e124 Mon Sep 17 00:00:00 2001 From: Stefan Rueger Date: Thu, 18 Jun 2026 19:11:05 +0100 Subject: [PATCH] Update documentation for -P usb: syntax --- src/avrdude.1 | 27 ++++++++++++++------------ src/doc/avrdude.texi | 45 +++++++++++++++++++++++--------------------- 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/src/avrdude.1 b/src/avrdude.1 index 347ec1d9..238bbb71 100644 --- a/src/avrdude.1 +++ b/src/avrdude.1 @@ -613,9 +613,19 @@ they are automatically identified via their vendor and product IDs from avrdude.conf or .avrduderc. Only when there are multiple programmers of the same type plugged into the host computer is the -P option needed, see below. Some -c programmers, however, ignore the -P option altogether, eg, -teensy, ch341a or avrftdi; these cannot distinguish multiple plugged-in +pickit2, teensy, ch341a or avrftdi; these cannot distinguish multiple plugged-in programmers. .Pp +Most USB programmers, however, support the command-line syntax -P +usb[::][:] which allows the user to override the +vendor and product IDs with hexadecimal numbers and and/or +request a match of the desired device's serial number with . The +match is done after stripping any existing colons from the given serial +number on the command line, and right-to-left, so only the least +significant bytes from the serial number need to be given. The JTAG ICE +mkII, JTAGICE3, SNAP, and PICKit5 programmers are examples for this -P +port syntax. +.Pp If .Nm has been configured with libserialport support, a serial port can be specified @@ -626,10 +636,10 @@ or 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, +The USB to serial chip has to have a serial number for this to work. Note +that serial number matches for serial adapters (in contrast to matches for +USB programmers above) ist from left-to-right. For matches from +right-to-left, serial adapters can use the ellipses. In the above example, .Ar ft232r:1234 would also result in a match, and so would .Ar ft232r:...5678 . @@ -698,13 +708,6 @@ For examples, see the respective .Em Troubleshooting entry in the detailed pdf documentation. .Pp -The -c pickit5 programmer allows overriding the vendor and product IDs -with hexadecimal numbers and using -P usb::. The -form -P usb: requests AVRDUDE select the PICkit5 programmer with -a serial number that ends in and with vid/pid from the -configuration files. It is also possible to override vid/pid and require a -serialno match via -P usb:::. -.Pp For the XBee programmer the target MCU is to be programmed wirelessly over a ZigBee mesh using the XBeeBoot bootloader. The ZigBee 64-bit address for the target MCU's own XBee device must be supplied as a 16-character hexadecimal diff --git a/src/doc/avrdude.texi b/src/doc/avrdude.texi index f225bfc7..bb4ac273 100644 --- a/src/doc/avrdude.texi +++ b/src/doc/avrdude.texi @@ -840,26 +840,37 @@ they are automatically identified via their vendor and product IDs from @code{avrdude.conf} or @code{.avrduderc}. Only when there are multiple programmers of the same type plugged into the host computer is the @code{-P} option needed, see below. Some @code{-c} programmers, however, -ignore the @code{-P} option altogether, eg, teensy, ch341a or avrftdi; +ignore the @code{-P} option altogether, eg, pickit5, teensy, ch341a or avrftdi; these cannot distinguish multiple plugged-in programmers. +Most USB programmers, however, support the command-line syntax @code{-P +usb[:@var{vid}:@var{pid}][:@var{serialno}]} which allows the user to +override the vendor and product IDs with hexadecimal numbers @var{vid} and +@var{pid} and/or request a match of the desired device's serial number with +@var{serialno}. The match is done after stripping any existing colons from the +given serial number on the command line, and right-to-left, so only the +least significant bytes from the serial number need to be given. The JTAG +ICE mkII, JTAGICE3, SNAP, and PICKit5 programmers are examples for this +@code{-P} port syntax. + If avrdude has been configured with libserialport support, a serial port can be specified using a predefined serial adapter type in @code{avrdude.conf} or @code{.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}. -Depending on the used shell, @code{?} may need to be quoted as in -@code{"?"} or @code{\?}. +@code{ft232r:12345678}. The USB to serial chip has to have a serial number +for this to work. Note that serial number matches for serial adapters (in +contrast to matches for USB programmers above) ist from left-to-right. For +matches from right-to-left, serial adapters can use the ellipses. 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}. Depending on the used +shell, @code{?} may need to be quoted as in @code{"?"} or @code{\?}. For the JTAG ICE mkII, if AVRDUDE has been built with libusb support, the port can be specified as @code{usb}[:@var{serialno}]. In that case, the @@ -889,14 +900,6 @@ usb:@var{serialno}}. The USBasp serial number is matched from the end, so only the unique least significant bytes are needed. For examples, see the respective entry in @ref{Troubleshooting}. -The @code{-c pickit5} programmer allows overriding the vendor and product -IDs with hexadecimal numbers @var{vid} and @var{pid} using @code{-P -usb:@var{vid}:@var{pid}}. The form @code{-P usb:@var{serialno}} requests -AVRDUDE select the PICkit5 programmer with a serial number that ends in -@var{serialno} and with @var{vid}/@var{pid} from the configuration files. -It is also possible to override @var{vid}/@var{pid} and require a -@var{serialno} match via @code{-P usb:@var{vid}:@var{pid}:@var{serialno}}. - For the XBee programmer the target MCU is to be programmed wirelessly over a ZigBee mesh using the XBeeBoot bootloader. The ZigBee 64-bit address for the target MCU's own XBee device must be supplied as a