Implement serialports monitor / resolve #10

HISTORY.rst

@@ -4,6 +4,7 @@ Release History
 0.6.0 (?)
 ---------
 
+* Implemented ``serialports monitor`` (`issue #10 <https://github.com/ivankravets/platformio/issues/10>`_)
 * Fixed an issue ``ImportError: No module named platformio.util`` (`issue #9 <https://github.com/ivankravets/platformio/issues/9>`_)
 * Fixed bug with auto-conversation from Arduino \*.ino to \*.cpp
 

docs/ide.rst

@@ -21,7 +21,7 @@ Put to the project directory ``Makefile`` wrapper with contents:
 
 .. code-block:: make
 
-    # Uncomment lines below for Mac/Linux OS
+    # Uncomment lines below if you have problems with $PATH
     #SHELL := /bin/bash
     #PATH := /usr/local/bin:$(PATH)
 

docs/userguide/cmd_serialports.rst

@@ -5,28 +5,31 @@ platformio serialports
 
 .. contents::
 
+platformio serialports list
+---------------------------
+
 Usage
------
+~~~~~
 
 .. code-block:: bash
 
-    platformio serialports
+    platformio serialports list
 
 
 Description
------------
+~~~~~~~~~~~
 
 List available `Serial Ports <http://en.wikipedia.org/wiki/Serial_port>`_
 
 
 Examples
---------
+~~~~~~~~
 
 1. Unix OS
 
 .. code-block:: bash
 
-    $ platformio serialports
+    $ platformio serialports list
     /dev/cu.SLAB_USBtoUART
     ----------
     Hardware ID: USB VID:PID=10c4:ea60 SNR=0001
@@ -42,7 +45,7 @@ Examples
 
 .. code-block:: bash
 
-    $ platformio serialports
+    $ platformio serialports list
     COM4
     ----------
     Hardware ID: USB VID:PID=0451:F432
@@ -52,3 +55,189 @@ Examples
     ----------
     Hardware ID: USB VID:PID=10C4:EA60 SNR=0001
     Description: Silicon Labs CP210x USB to UART Bridge (COM3)
+
+
+platformio serialports monitor
+------------------------------
+
+Usage
+~~~~~
+
+.. code-block:: bash
+
+    platformio serialports monitor [OPTIONS]
+
+
+Description
+~~~~~~~~~~~
+
+This is a console application that provides a small terminal
+application. It is based on `Miniterm <http://pyserial.sourceforge.net/examples.html#miniterm>`_
+and itself does not implement any terminal features such
+as *VT102* compatibility. However it inherits these features from the terminal
+it is run. For example on GNU/Linux running from an *xterm* it will support the
+escape sequences of the *xterm*. On *Windows* the typical console window is dumb
+and does not support any escapes. When *ANSI.sys* is loaded it supports some
+escapes.
+
+To control *monitor* please use these "hot keys":
+
+* ``Ctrl+]`` Quit
+* ``Ctrl+T`` Menu
+* ``Ctrl+T followed by Ctrl+H`` Help
+
+Options
+~~~~~~~
+
+.. option::
+    -p, --port
+
+Port, a number or a device name
+
+.. option::
+    -b, --baud
+
+Set baud rate, default ``9600``
+
+.. option::
+    --parity
+
+Set parity (*None, Even, Odd, Space, Mark*), one of
+[``N``, ``E``, ``O``, ``S``, ``M``], default ``N``
+
+.. option::
+    --rtscts
+
+Enable ``RTS/CTS`` flow control, default ``Off``
+
+.. option::
+    --xonxoff
+
+Enable software flow control, default ``Off``
+
+.. option::
+    --rts
+
+Set initial ``RTS`` line state, default ``0``
+
+.. option::
+    --dtr
+
+Set initial ``DTR`` line state, default ``0``
+
+.. option::
+    --echo
+
+Enable local echo, default ``Off``
+
+.. option::
+    --cr
+
+Do not send ``CR+LF``, send ``R`` only, default ``Off``
+
+.. option::
+    --lf
+
+Do not send ``CR+LF``, send ``LF`` only, default ``Off``
+
+.. option::
+    -d, --debug
+
+Debug received data (escape non-printable chars). ``--debug`` can be given
+multiple times:
+
+0. just print what is received
+1. escape non-printable characters, do newlines as unusual
+2. escape non-printable characters, newlines too
+3. hex dump everything
+
+.. option::
+    --exit-char
+
+ASCII code of special character that is used to exit the application,
+default ``0x1d``
+
+.. option::
+    --menu-char
+
+ASCII code of special character that is used to control miniterm (menu),
+default ``0x14``
+
+.. option::
+    ---quiet
+
+Diagnostics: suppress non-error messages, default ``Off``
+
+Examples
+~~~~~~~~
+
+1. Show available option for command
+
+.. code-block:: bash
+
+    $ platformio serialports monitor --help
+    Usage: platformio serialports monitor [OPTIONS]
+
+    Options:
+      -p, --port TEXT       Port, a number or a device name
+      -b, --baud INTEGER    Set baud rate, default=9600
+      --parity [N|E|O|S|M]  Set parity, default=N
+      --rtscts              Enable RTS/CTS flow control, default=Off
+      --xonxoff             Enable software flow control, default=Off
+      --rts [0|1]           Set initial RTS line state, default=0
+      --dtr [0|1]           Set initial DTR line state, default=0
+      --echo                Enable local echo, default=Off
+      --cr                  Do not send CR+LF, send CR only, default=Off
+      --lf                  Do not send CR+LF, send LF only, default=Off
+      -d, --debug           Debug received data (escape non-printable chars)
+                            --debug can be given multiple times:
+                            0: just print what is received
+                            1: escape non-printable characters, do newlines as
+                               unusual
+                            2: escape non-printable characters, newlines too
+                            3: hex dump everything
+      --exit-char INTEGER   ASCII code of special character that is used to exit
+                            the application, default=0x1d
+      --menu-char INTEGER   ASCII code of special character that is used to
+                            control miniterm (menu), default=0x14
+      --quiet               Diagnostics: suppress non-error messages, default=Off
+      --help                Show this message and exit.
+
+2. Communicate with serial device and print help inside terminal
+
+.. code-block:: bash
+
+    $ platformio serialports monitor
+
+    --- Available ports:
+    --- /dev/cu.Bluetooth-Incoming-Port n/a
+    --- /dev/cu.Bluetooth-Modem n/a
+    --- /dev/cu.SLAB_USBtoUART CP2102 USB to UART Bridge Controller
+    --- /dev/cu.obd2ecu-SPPDev n/a
+    Enter port name:/dev/cu.SLAB_USBtoUART
+    --- Miniterm on /dev/cu.SLAB_USBtoUART: 9600,8,N,1 ---
+    --- Quit: Ctrl+]  |  Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+    Hello PlatformIO!
+    --- pySerial (2.7) - miniterm - help
+    ---
+    --- Ctrl+]   Exit program
+    --- Ctrl+T   Menu escape key, followed by:
+    --- Menu keys:
+    ---    Ctrl+T  Send the menu character itself to remote
+    ---    Ctrl+]  Send the exit character itself to remote
+    ---    Ctrl+I  Show info
+    ---    Ctrl+U  Upload file (prompt will be shown)
+    --- Toggles:
+    ---    Ctrl+R  RTS          Ctrl+E  local echo
+    ---    Ctrl+D  DTR          Ctrl+B  BREAK
+    ---    Ctrl+L  line feed    Ctrl+A  Cycle repr mode
+    ---
+    --- Port settings (Ctrl+T followed by the following):
+    ---    p          change port
+    ---    7 8        set data bits
+    ---    n e o s m  change parity (None, Even, Odd, Space, Mark)
+    ---    1 2 3      set stop bits (1, 2, 1.5)
+    ---    b          change baud rate
+    ---    x X        disable/enable software flow control
+    ---    r R        disable/enable hardware flow control
+    --- exit ---

platformio/commands/serialports.py

@@ -1,17 +1,68 @@
 # Copyright (C) Ivan Kravets <[email protected]>
 # See LICENSE for details.
 
-from click import command, echo, secho
+import sys
+
+from click import Choice, echo, group, option, secho
+from serial.tools import miniterm
 
 from platformio.util import get_serialports
 
 
-@command("serialports", short_help="List Serial ports")
+@group(short_help="List or Monitor Serial ports")
 def cli():
+    pass
+
+
+@cli.command("list", short_help="List Serial ports")
+def serialports_list():
 
     for item in get_serialports():
         secho(item['port'], fg="cyan")
         echo("----------")
         echo("Hardware ID: %s" % item['hwid'])
         echo("Description: %s" % item['description'])
         echo("")
+
+
+@cli.command("monitor", short_help="Monitor Serial port")
+@option("--port", "-p", help="Port, a number or a device name")
+@option("--baud", "-b", type=int, default=9600,
+        help="Set baud rate, default=9600")
+@option("--parity", default="N", type=Choice(["N", "E", "O", "S", "M"]),
+        help="Set parity, default=N")
+@option("--rtscts", is_flag=True,
+        help="Enable RTS/CTS flow control, default=Off")
+@option("--xonxoff", is_flag=True,
+        help="Enable software flow control, default=Off")
+@option("--rts", default="0", type=Choice(["0", "1"]),
+        help="Set initial RTS line state, default=0")
+@option("--dtr", default="0", type=Choice(["0", "1"]),
+        help="Set initial DTR line state, default=0")
+@option("--echo", is_flag=True,
+        help="Enable local echo, default=Off")
+@option("--cr", is_flag=True,
+        help="Do not send CR+LF, send CR only, default=Off")
+@option("--lf", is_flag=True,
+        help="Do not send CR+LF, send LF only, default=Off")
+@option("--debug", "-d", count=True,
+        help="""Debug received data (escape non-printable chars)
+# --debug can be given multiple times:
+# 0: just print what is received
+# 1: escape non-printable characters, do newlines as unusual
+# 2: escape non-printable characters, newlines too
+# 3: hex dump everything""")
+@option("--exit-char", type=int, default=0x1d,
+        help="ASCII code of special character that is used to exit the "
+        "application, default=0x1d")
+@option("--menu-char", type=int, default=0x14,
+        help="ASCII code of special character that is used to control "
+        "miniterm (menu), default=0x14")
+@option("--quiet", is_flag=True,
+        help="Diagnostics: suppress non-error messages, default=Off")
+def serialports_monitor(**_):
+    sys.argv = sys.argv[3:]
+    try:
+        miniterm.main()
+    except:  # pylint: disable=W0702
+        pass