mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
Merge #19099
19099: dist/tools/usb-serial: Clean up legacy scripts r=aabadie a=maribu ### Contribution description Refactor the old bash scripts to use `ttys.py` instead and update the documentation. ### Testing procedure The pi fleet should still work without modification. ### Issues/PRs references Fixes https://github.com/RIOT-OS/RIOT/issues/15814 Co-authored-by: Marian Buschsieweke <marian.buschsieweke@ovgu.de>
This commit is contained in:
bors[bot]
GitHub
commit
07031d0239
118
dist/tools/usb-serial/README.md
vendored
118
dist/tools/usb-serial/README.md
vendored
@ -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 <FILTER_VARIANT_1> || ./ttys.py <FILTER_VARIANT_2>
|
||||
|
||||
### Build System Integration
|
||||
|
||||
By adding
|
||||
|
||||
TTY_BOARD_FILTER := <FILTER PARAMETERS>
|
||||
|
||||
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
|
||||
|
||||
41
dist/tools/usb-serial/find-tty.sh
vendored
41
dist/tools/usb-serial/find-tty.sh
vendored
@ -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
|
||||
|
||||
31
dist/tools/usb-serial/list-ttys.sh
vendored
31
dist/tools/usb-serial/list-ttys.sh
vendored
@ -1,33 +1,6 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Copyright (C) 2015 Eistec AB
|
||||
# Copyright (C) 2015 Ludwig Knüpfer <ludwig.knuepfer@fu-berlin.de>
|
||||
#
|
||||
#!/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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user