31. USB to serial adapter tools¶

Tools for finding connected USB to serial adapter devices.

31.1. 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]

Write to stdout the first tty 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 until a match has been found.

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 the first found USB tty (in an arbitrary order, this is not guaranteed to be the /dev/ttyUSBX with the lowest number).

Serial strings from all connected USB ttys can be found from the list generated by list-ttys.sh.

31.2. Exit codes¶

find-tty.sh returns 0 if a match is found, 1 otherwise.

31.3. 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)'

  ifeq ($(PORT),)
    # try to find tty name by serial number, only works on Linux currently.
    ifeq ($(OS),Linux)
      PORT := $(shell $(RIOTBASE)/dist/tools/usb-serial/find-tty.sh "^$(PROGRAMMER_SERIAL)$$")
    endif
  endif
endif

# Fallback PORT if no serial was specified or if the specified serial was not found
ifeq ($(PORT),)
    ifeq ($(OS),Linux)
      PORT := $(shell $(RIOTBASE)/dist/tools/usb-serial/find-tty.sh)
    else ifeq ($(OS),Darwin)
      PORT := $(shell ls -1 /dev/tty.SLAB_USBtoUART* | head -n 1)
    endif
endif

# TODO: add support for windows as host platform
ifeq ($(PORT),)
  $(info CAUTION: No terminal port for your host system found!)
endif
export PORT

31.4. Limitations¶

Only tested on Linux, and probably only works on Linux.