mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-01-18 12:52:44 +01:00
100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
USB to serial adapter tools
|
|
================================
|
|
|
|
Tools for finding connected USB to serial adapter devices.
|
|
|
|
`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
|
|
|
|
|
|
`find-tty.sh`
|
|
-------------
|
|
|
|
Prints the paths to all TTY interfaces whose serial matches any of the given
|
|
arguments literally.
|
|
|
|
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.
|
|
|
|
### Usage
|
|
|
|
./find-tty.sh [serial_1] [serial_2] ... [serial_n]
|
|
|
|
|
|
Limitations
|
|
-----------
|
|
|
|
Only tested on Linux, and probably only works on Linux.
|