From b8bb3d8ca7fc1fcf62f2255c5b6a76c3622f7526 Mon Sep 17 00:00:00 2001
From: Yann Sionneau <ys@m-labs.hk>
Date: Fri, 19 Jun 2015 17:06:50 +0200
Subject: [PATCH] manual: explain how to select TCube device from serial number

---
 artiq/frontend/thorlabs_tcube_controller.py |  4 +++-
 doc/manual/ndsp_reference.rst               | 16 ++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/artiq/frontend/thorlabs_tcube_controller.py b/artiq/frontend/thorlabs_tcube_controller.py
index d4dc18388..d6aea8cbf 100755
--- a/artiq/frontend/thorlabs_tcube_controller.py
+++ b/artiq/frontend/thorlabs_tcube_controller.py
@@ -13,7 +13,9 @@ def get_argparser():
                         help="type of the Thorlabs T-Cube device to control",
                         choices=["TDC001", "TPZ001"])
     parser.add_argument("-d", "--device", default=None,
-                        help="serial port. Omit for simulation mode.")
+                        help="serial device. See documentation for how to "
+                             "specify a USB Serial Number. Omit for simulation "
+                             "mode.")
     simple_network_args(parser, 3255)
     verbosity_args(parser)
     return parser
diff --git a/doc/manual/ndsp_reference.rst b/doc/manual/ndsp_reference.rst
index 8ac75ac7b..829b1263d 100644
--- a/doc/manual/ndsp_reference.rst
+++ b/doc/manual/ndsp_reference.rst
@@ -88,6 +88,8 @@ Controller
 Thorlabs T-Cube
 ---------------
 
+.. _tdc001-controller-usage-example:
+
 TDC001 controller usage example
 +++++++++++++++++++++++++++++++
 
@@ -98,6 +100,15 @@ First, run the TDC001 controller::
 .. note::
     On Windows the serial port (the ``-d`` argument) will be of the form ``COMx``.
 
+.. note::
+    Anything compatible `with serial_for_url <http://pyserial.sourceforge.net/pyserial_api.html#serial.serial_for_url>`_
+    can be given as a device in ``-d`` argument.
+
+    For instance, if you want to specify the Vendor/Product ID and the USB Serial Number, you can do:
+
+    ``-d hwgrep://<VID>:<PID> SNR=<serial_number>``.
+    The hwgrep URL works on both Linux and Windows.
+
 Then, send commands to it via the ``artiq_rpctool`` utility::
 
     $ artiq_rpctool ::1 3255 list-targets
@@ -118,6 +129,11 @@ First, run the TPZ001 controller::
 .. note::
     On Windows the serial port (the ``-d`` argument) will be of the form ``COMx``.
 
+.. note::
+    See the :ref:`TDC001 documentation <tdc001-controller-usage-example>` for
+    how to specify the USB Serial Number of the device instead of the
+    /dev/ttyUSBx (or the COMx name).
+
 Then, send commands to it via the ``artiq_rpctool`` utility::
 
     $ artiq_rpctool ::1 3255 list-targets