diff --git a/dist/tools/usb-serial/README.md b/dist/tools/usb-serial/README.md index d7df920f05..e7fcf4581a 100644 --- a/dist/tools/usb-serial/README.md +++ b/dist/tools/usb-serial/README.md @@ -3,52 +3,94 @@ USB to serial adapter tools Tools for finding connected USB to serial adapter devices. -Usage ------ +`ttys.py` +--------- + +Lists currently connected USB to serial adapters by searching through UDEV +that match the given filters formatted with in the specified format. + +By default, all USB serial adapters present are printed as a markdown table. + +### Usage + + usage: ttys.py [-h] [--most-recent] [--format FORMAT] [--serial SERIAL] [--driver DRIVER] [--model MODEL] + [--model-db MODEL_DB] [--vendor VENDOR] [--vendor-db VENDOR_DB] [--iface-num IFACE_NUM] + [--exclude-serial [EXCLUDE_SERIAL ...]] + +### Output Formats + +With the parameter `--format FORMAT` a different format than the default +markdown table can be selected, e.g. `json` results in JSON output and `path` +will print the paths of the matching TTYs without any formatting (useful for +scripting). The full list of formats can be obtained by running the script with +the `--help` parameter + +### Filtering + +For each column in the table, there is a matching filtering option. Except for +the `--serial` filter, all filters expect regular expressions that are tried +to match against the value in the given column. The `--serial` filter however +only matches if the serial of the TTY matches the given value literally. A +TTY is considered matching if and only if all filters apply. + +There is an additional `--exclude-serial` option that can be used to exclude +serial devices (even before any filters are checked). If this option is absent +and the environment variable `EXCLUDE_TTY_SERIAL` is set, the serials in the +variable (separated by space) are used instead. This is useful if some bogus +serial devices are present, such as configuration interfaces of fancy monitors. + +### Limiting Results + +The parameter `--most-recent` will only print the most recently connect serial. +It can be combined with filters, in which case it will print the most recently +connected TTY among those matching all filters. + +### Exit Code + +The script exits with 0 if at least one TTY was found and 1 otherwise. + +### Chaining + +By relying on the exit code, it is simple to test for multiple variants of the +same board that e.g. differ in the UART to USB interface in the shell, e.g. +using + + ./ttys.py || ./ttys.py + +### Build System Integration + +By adding + + TTY_BOARD_FILTER := + +to the `Makefile.include` of your board, running `make MOST_RECENT_PORT=1 term` +will connect to the most recently connected board matching the provided +filters. Refer to https://api.riot-os.org/flashing.html#multiple-boards-simple +for more details. + +`list-ttys.sh` +-------------- + +A wrapper that runs `./ttys.py --format path` for backward compatibility. + +### Usage ./list-ttys.sh -List all currently connected USB to serial adapters by searching through -`/sys/bus/usb/devices/`. - ./find-tty.sh [serial_regex1] [serial_regex2] ... [serial_regexZ] +`find-tty.sh` +------------- -Write to `stdout` all ttys connected to the chosen programmer. -`serial_regexN` are extended regular expressions (as understood by `egrep`) -containing a pattern matched against the USB device serial number. Each of the -given expressions are tested, against each serial number, and matching ttys are -output (one tty per line). +Prints the paths to all TTY interfaces whose serial matches any of the given +arguments literally. -In order to search for an exact match against the device serial, use -'^serialnumber$' as the pattern. If no pattern is given, `find-tty.sh` returns -all found USB ttys (in an arbitrary order, this is not guaranteed to be -the `/dev/ttyUSBX` with the lowest number). +It basically runs `ttys.py --format path --serial "$arg"` for every argument +`$arg` and is intended for backward compatibility, as directly interacting with +`ttys.py` is the more flexible approach. -Serial strings from all connected USB ttys can be found from the list generated -by `list-ttys.sh`. - -Exit codes ----------- -`find-tty.sh` returns 0 if a match is found, 1 otherwise. - -Makefile example usage ----------------------- - -The script `find-tty.sh` is designed for use from within a board -`Makefile.include`. An example section is shown below (for an OpenOCD based -solution): - - # Add serial matching command - ifneq ($(PROGRAMMER_SERIAL),) - OOCD_BOARD_FLAGS += -c 'ftdi_serial $(PROGRAMMER_SERIAL)' - endif - - PORT_LINUX_EXACT = $(if $(PROGRAMMER_SERIAL),$(firstword $(shell $(RIOTTOOLS)/usb-serial/find-tty.sh "^$(PROGRAMMER_SERIAL)$$")),) - - PORT_LINUX = $(if $(PORT_LINUX_EXACT),$(PORT_LINUX_EXACT),$(firstword $(shell $(RIOTTOOLS)/usb-serial/find-tty.sh))) - - PORT_DARWIN = $(shell ls -1 /dev/tty.SLAB_USBtoUART* | head -n 1) +### Usage + ./find-tty.sh [serial_1] [serial_2] ... [serial_n] Limitations diff --git a/dist/tools/usb-serial/find-tty.sh b/dist/tools/usb-serial/find-tty.sh index 1a896afa29..136513d3ef 100755 --- a/dist/tools/usb-serial/find-tty.sh +++ b/dist/tools/usb-serial/find-tty.sh @@ -1,46 +1,15 @@ #!/usr/bin/env bash -# -# Copyright (C) 2015 Eistec AB -# # This file is subject to the terms and conditions of the GNU Lesser General # Public License v2.1. See the file LICENSE in the top level directory for more # details. -# -# Find all USB to serial devices +exit_code=1 -# default error status code -status=1 - -# iterate over usb-tty devices: -for basedev in $(find /sys/bus/usb/devices/ -regex "/sys/bus/usb/devices/[0-9]+[^:/]*" -maxdepth 2 -follow 2>/dev/null); do - ttydirs=$(find ${basedev} -regex "${basedev}/[^/]*:.*" -mindepth 2 -maxdepth 3 -name tty -follow 2>/dev/null) - if [ -z "${ttydirs}" ]; then - continue +for serial in "$@"; do + if ./ttys.py --format path --serial "$serial"; then + exit_code=0 fi - # See if the device has any tty devices assigned to it - for tty in $(find ${ttydirs} -maxdepth 1 -mindepth 1 -printf '%f\n' 2>/dev/null); do - parent=$(echo ${basedev} | sed -e 's%\(/sys/bus/usb/devices/[^/]*\)/.*%\1%') - serial=$(cat "${parent}/serial" 2>/dev/null) - # split results into array - - if [ $# -lt 1 ]; then - # No arguments given, return all ttys - echo "/dev/${tty}" - status=0 - continue - fi - # else: Match any of the given serials - for s in "${@}"; do - echo "${serial}" | egrep -e "${s}" -q - if [ $? -eq 0 ]; then - # return tty - echo "/dev/${tty}" - status=0 - fi - done - done done -exit $status; +exit $exit_code diff --git a/dist/tools/usb-serial/list-ttys.sh b/dist/tools/usb-serial/list-ttys.sh index 5a61400063..9bd4c0c492 100755 --- a/dist/tools/usb-serial/list-ttys.sh +++ b/dist/tools/usb-serial/list-ttys.sh @@ -1,33 +1,6 @@ -#!/usr/bin/env bash - -# Copyright (C) 2015 Eistec AB -# Copyright (C) 2015 Ludwig Knüpfer -# +#!/usr/bin/env sh # This file is subject to the terms and conditions of the GNU Lesser General # Public License v2.1. See the file LICENSE in the top level directory for more # details. -if [ ! -d /sys/bus/usb/devices ]; then - echo "$(basename "$0"): /sys/bus/usb/devices not a directory (/sys is not mounted?)" >&2 - exit 1 -fi - -# iterate over usb-tty devices: -while IFS= read -r -d '' basedev -do - ttydirs=$(find "${basedev}" -regex "${basedev}/[^/]*:.*" -mindepth 2 -maxdepth 3 -name tty -follow 2>/dev/null) - if [ -z "${ttydirs}" ]; then - continue - fi - # See if the device has any tty devices assigned to it. - ttys=$(find "${ttydirs}" -maxdepth 1 -mindepth 1 -printf '%f, ' | sed -e 's/, $/\n/' 2>/dev/null) - if [ -z "${ttys}" ]; then - continue - fi - # Get all info - parent=$(echo "${basedev}" | sed -e 's%\(/sys/bus/usb/devices/[^/]*\)/.*%\1%') - serial=$(cat "${parent}/serial" 2>/dev/null) - manuf=$(cat "${parent}/manufacturer" 2>/dev/null) - product=$(cat "${parent}/product" 2>/dev/null) - echo "${parent}: ${manuf} ${product}, serial: '${serial}', tty(s): ${ttys}" -done < <(find /sys/bus/usb/devices/ -regex "/sys/bus/usb/devices/[0-9]+[^:/]*" -maxdepth 2 -follow -print0 2>/dev/null); +./ttys.py --format path