mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
48a02d60e2
For scripts it can be useful to output not only one, but multiple formats (e.g. to obtain both path and serial of a TTY). The script now support passing multiple formats. Note that only simple formats can be combined, as the JSON and markdown table won't mix well with any other format.
112 lines
3.7 KiB
Markdown
112 lines
3.7 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.
|
|
|
|
Note: Formats other than `json` and `table` can be combined. A script that
|
|
required both path and serial of TTYs could use:
|
|
|
|
```
|
|
./ttys.py --format path serial
|
|
```
|
|
|
|
This will output one TTY per line with the selected fields separated by space.
|
|
To use a different separator than space (e.g. to create CSV files), the option
|
|
`--format-sep` can be used. If a field value contains the separator, it will
|
|
be quoted and quotation chars inside will be escaped.
|
|
|
|
### 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.
|