diff --git a/HISTORY.rst b/HISTORY.rst index 237d8223..126a4f2d 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -4,6 +4,7 @@ Release History 0.6.0 (?) --------- +* Implemented ``serialports monitor`` (`issue #10 `_) * Fixed an issue ``ImportError: No module named platformio.util`` (`issue #9 `_) * Fixed bug with auto-conversation from Arduino \*.ino to \*.cpp diff --git a/docs/ide.rst b/docs/ide.rst index 130fd5d9..2cface06 100644 --- a/docs/ide.rst +++ b/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) diff --git a/docs/userguide/cmd_serialports.rst b/docs/userguide/cmd_serialports.rst index 50b0cc73..04b1950b 100644 --- a/docs/userguide/cmd_serialports.rst +++ b/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 `_ 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 `_ +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 --- diff --git a/platformio/commands/serialports.py b/platformio/commands/serialports.py index 79b3d67d..769e9a70 100644 --- a/platformio/commands/serialports.py +++ b/platformio/commands/serialports.py @@ -1,13 +1,21 @@ # Copyright (C) Ivan Kravets # 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") @@ -15,3 +23,46 @@ def cli(): 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