Merge pull request #2275 from gebart/pr/ftdi-tools

Add tools for finding USB serial devices' `tty` names on Linux.

dist/tools/usb-serial/README.md

@@ -0,0 +1,72 @@
+USB to serial adapter tools
+================================
+
+Tools for finding connected USB to serial adapter devices.
+
+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`.
+
+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)'
+
+      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
+
+
+Limitations
+-----------
+
+Only tested on Linux, and probably only works on Linux.

dist/tools/usb-serial/find-tty.sh

@@ -0,0 +1,43 @@
+#!/bin/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
+# 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
+    fi
+    # See if the device has any tty devices assigned to it, get the first match
+    tty=$(find ${ttydirs} -maxdepth 1 -mindepth 1 -printf '%f\n' | head -n 1 2>/dev/null)
+    if [ -z "${tty}" ]; then
+        continue
+    fi
+    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 first found tty
+        echo "/dev/${tty}"
+        exit 0
+    fi
+    # else: Match any of the given serials
+    for s in "${@}"; do
+        echo "${serial}" | egrep -e "${s}" -q
+        if [ $? -eq 0 ]; then
+            # return first tty
+            echo "/dev/${tty}"
+            exit 0
+        fi
+    done
+done
+# not found
+exit 1;

dist/tools/usb-serial/list-ttys.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+
+# Copyright (C) 2015 Eistec AB
+# Copyright (C) 2015 Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
+#
+# 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:
+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
+    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