Reimplement Serial Terminal feature and documentation based on PR feedback

Author: screamerbg

README.md

@@ -514,6 +514,33 @@ $ mbed export -i uvision -m K64F
 
 Mbed CLI creates a `.uvprojx` file in the projectfiles/uvision folder. You can open the project file with uVision.
 
+### Serial terminal
+
+You can open a serial terminal to the COM port of a connected Mbed target (usually board) using the `mbed sterm` command. If no COM port is specified, Mbed CLI will attempt to detect the connected Mbed targets and their COM ports.
+
+There are various options to `mbed sterm`:
+* `--port <COM port>` to specify system COM port to connect to.
+* `--baudrate <numeric>` to select the communication baudrate, where the default value is 9600.
+* `--echo <on|off>` to switch local echo (default is `on`).
+* `--reset` to reset the connected target by sending Break before opening the serial terminal.
+
+You can also set default port, baudrate and echo mode using the `TERM_PORT`, `TERM_BAUDRATE` and `TERM_ECHO` Mbed CLI configuration options.
+
+The following shortcuts are available within the serial terminal:
+- Quit: `CTRL+C` or `CTRL+J`
+- Reset: `CTRL+B` or `CTRL+R`
+- Echo toggle: `CTRL+E`
+- Terminal information: `TAB` or `CTRL+I`
+- Help: `CTRL+H`
+- Menu: `CTRL+T`
+- Change baud rate: `CTRL+T+B`
+
+To automate things, you can also add the `--sterm` option to `mbed compile -f` to compile a new program, flash the program/firmware image to the connected target and then open serial terminal to it's COM port:
+
+```
+$ mbed compile -t GCC_ARM -m K64F -f --sterm
+```
+
 ## Testing
 
 Use the `mbed test` command to compile and run tests.

mbed/mbed.py

@@ -34,7 +34,6 @@
 import zipfile
 import argparse
 import tempfile
-from mbed_cdc import mbed_cdc
 
 
 # Application version
@@ -1752,6 +1751,30 @@ def formaturl(url, format="default"):
                     url = 'https://%s/%s' % (m.group(2), m.group(3))
     return url
 
+# Wrapper for the MbedTermnal functionality
+def mbed_sterm(port, baudrate=9600, echo=True, reset=False, sterm=False):
+    try:
+        from mbed_terminal import MbedTerminal
+    except (IOError, ImportError, OSError):
+        error("The serial terminal functionality requires that the 'mbed-terminal' python module is installed.\nYou can install mbed-terminal by running 'pip install mbed-terminal'.", 1)
+
+    result = False
+    mbed_serial = MbedTerminal(port, baudrate=baudrate, echo=echo)
+    if mbed_serial.serial:
+        if reset:
+            mbed_serial.reset()
+
+        if sterm:
+            # Some boards will reset the COM port after SendBreak, e.g. STLink based
+            if not mbed_serial.serial.is_open:
+                mbed_serial = MbedTerminal(port, baudrate=baudrate, echo=echo)
+
+            try:
+                result = mbed_serial.terminal()
+            except:
+                pass
+    return result
+
 
 # Subparser handling
 parser = argparse.ArgumentParser(prog='mbed',
@@ -2470,7 +2493,7 @@ def compile_(toolchain=None, target=None, profile=False, compile_library=False,
                     error("Unable to flash the target board connected to your system.", 1)
 
             if flash or sterm:
-                if not mbed_cdc(detected['port'], reset=flash, sterm=sterm):
+                if not mbed_sterm(detected['port'], reset=flash, sterm=sterm):
                     error("Unable to reset the target board connected to your system.\nThis might be caused by an old interface firmware.\nPlease check the board page for new firmware.", 1)
 
     program.set_defaults(target=target, toolchain=tchain)
@@ -2634,16 +2657,14 @@ def export(ide=None, target=None, source=False, clean=False, supported=False, ap
     program.set_defaults(target=target)
 
 
-# Test command
+# Detect command
 @subcommand('detect',
-    dict(name=['-r', '--reset'], dest='reset', action='store_true', help='Reset detected targets (via SendBreak)'),
-    dict(name=['-s', '--sterm'], dest='sterm', action='store_true', help='Open serial terminal for detected targets'),
     hidden_aliases=['det'],
-    help='Detect connected mbed targets/boards\n\n',
+    help='Detect connected Mbed targets/boards\n\n',
     description=(
-        "Detects mbed targets/boards connected to this system and shows supported\n"
+        "Detect Mbed targets/boards connected to this system and show supported\n"
         "toolchain matrix."))
-def detect(reset=False, sterm=False):
+def detect():
     # Gather remaining arguments
     args = remainder
     # Find the root of the program
@@ -2653,7 +2674,7 @@ def detect(reset=False, sterm=False):
     with cd(program.path):
         tools_dir = program.get_tools_dir()
 
-    if tools_dir and not (reset or sterm):
+    if tools_dir:
         # Prepare environment variables
         env = program.get_env()
 
@@ -2666,9 +2687,7 @@ def detect(reset=False, sterm=False):
             if very_verbose:
                 error(str(e))
     else:
-        if not tools_dir:
-            warning("The mbed OS tools were not found in \"%s\". \nLimited information will be shown about connected mbed targets/boards" % program.path)
-
+        warning("The mbed-os tools were not found in \"%s\". \nLimited information will be shown about connected targets/boards" % program.path)
         targets = program.get_detected_targets()
         if targets:
             unknown_found = False
@@ -2678,13 +2697,47 @@ def detect(reset=False, sterm=False):
                     action("Detected unknown target connected to \"%s\" and using com port \"%s\"" % (target['mount'], target['serial']))
                 else:
                     action("Detected \"%s\" connected to \"%s\" and using com port \"%s\"" % (target['name'], target['mount'], target['serial']))
-                mbed_cdc(target['serial'], reset=reset, sterm=sterm)
 
             if unknown_found:
                 warning("If you're developing a new target, you can mock the device to continue your development. "
-                        "Use 'mbedls --mock ID:NAME' to do so (see 'mbedls --help' for more information)")
-        else:
-            error("This command requires that the 'mbed-greentea' python module is installed.\nYou can install mbed-greentea by running 'pip install mbed-greentea'.", 1)
+"Use 'mbedls --mock ID:NAME' to do so (see 'mbedls --help' for more information)")
+
+
+# Serial terminal command
+@subcommand('sterm',
+    dict(name=['-p', '--port'], help='Communication port. Default: auto-detect'),
+    dict(name=['-b', '--baudrate'], help='Communication baudrate. Default: 9600'),
+    dict(name=['-e', '--echo'], help='Switch local echo on/off. Default: on'),
+    dict(name=['-r', '--reset'], action='store_true', help='Reset the targets (via SendBreak) before opening terminal.'),
+    hidden_aliases=['term'],
+    help='Open serial terminal to connected target.\n\n',
+    description=(
+        "Open serial terminal to connected target (usually board), or connect to a user-specified COM port\n"))
+def sterm(port=None, baudrate=None, echo=None, reset=False, sterm=True):
+    # Gather remaining arguments
+    args = remainder
+    # Find the root of the program
+    program = Program(getcwd(), False)
+
+    port = port or program.get_cfg('TERM_PORT', None)
+    baudrate = baudrate or program.get_cfg('TERM_BAUDRATE', 9600)
+    echo = echo or program.get_cfg('TERM_ECHO', 'on')
+
+    if port:
+        action("Opening serial terminal to the specified COM port \"%s\"" % port)
+        mbed_sterm(port, baudrate=baudrate, echo=echo, reset=reset, sterm=sterm)
+    else:
+        action("Detecting connected targets/boards to your system...")
+        targets = program.get_detected_targets()
+        if not targets:
+            error("Couldn't detect connected targets/boards to your system.\nYou can manually specify COM port via the '--port' option.", 1)
+
+        for target in targets:
+            if target['name'] is None:
+                action("Opening serial terminal to unknown target at \"%s\"" % target['serial'])
+            else:
+                action("Opening serial terminal to \"%s\"" % target['name'])
+            mbed_sterm(target['serial'], baudrate=baudrate, echo=echo, reset=reset, sterm=sterm)
 
 
 # Generic config command

mbed/mbed_cdc.py renamed to mbed/mbed_terminal.py

@@ -19,34 +19,41 @@
 # pylint: disable=too-many-nested-blocks, too-many-public-methods, too-many-instance-attributes, too-many-statements
 # pylint: disable=invalid-name, missing-docstring, bad-continuation
 
-def mbed_cdc(port, reset=False, sterm=False, baudrate=9600, timeout= 10, print_term_header=True):
-    try:
-        from serial import Serial, SerialException
-        import serial.tools.miniterm as miniterm
-    except (IOError, ImportError, OSError):
-        return False
-
-    def get_instance(*args, **kwargs):
+
+# Global class used for global config
+class MbedTerminal(object):
+    serial = None # Serial() object
+    port = None
+    baudrate = None
+    echo = None
+
+    def __init__(self, port, baudrate=9600, echo=True, timeout=10):
+        self.port = port
+        self.baudrate = int(baudrate)
+        self.timeout = int(timeout)
+        self.echo = bool(echo)
+
+        try:
+            from serial import Serial, SerialException
+        except (IOError, ImportError, OSError):
+            return False
+
         try:
-            serial_port = Serial(*args, **kwargs)
-            serial_port.flush()
+            self.serial = Serial(self.port, baudrate=self.baudrate, timeout=self.timeout)
+            self.serial.flush()
+            self.serial.reset_input_buffer()
         except Exception as e:
-            error("Unable to open serial port connection to \"%s\"" % port)
+            print 'error'
+            self.serial = None
             return False
-        return serial_port
 
-    def cdc_reset(serial_instance):
+    def terminal(self, print_header=True):
         try:
-            serial_instance.sendBreak()
-        except:
-            try:
-                serial_instance.setBreak(False) # For Linux the following setBreak() is needed to release the reset signal on the target mcu.
-            except:
-                return False
-        return True
+            import serial.tools.miniterm as miniterm
+        except (IOError, ImportError, OSError):
+            return False
 
-    def cdc_term(serial_instance):
-        term = miniterm.Miniterm(serial_instance, echo=True)
+        term = miniterm.Miniterm(self.serial, echo=self.echo)
         term.exit_character = '\x03'
         term.menu_character = '\x14'
         term.set_rx_encoding('UTF-8')
@@ -55,6 +62,32 @@ def cdc_term(serial_instance):
         def console_print(text):
             term.console.write('--- %s ---\n' % text)
 
+        def get_print_help():
+            return """
+--- Mbed Serial Terminal (0.3a)
+--- Based on miniterm from pySerial
+---
+--- CTRL+B     Send Break (reset target)
+--- CTRL+C     Exit terminal
+--- CTRL+E     Toggle local echo
+--- CTRL+H     Help
+--- CTRL+T     Menu escape key, followed by:
+---    P       Change COM port
+---    B       Change baudrate
+---    TAB     Show detailed terminal info
+---    CTRL+A  Change encoding (default UTF-8)
+---    CTRL+F  Edit filters
+---    CTRL+L  Toggle EOL
+---    CTRL+R  Toggle RTS
+---    CTRL+D  Toggle DTR
+---    CTRL+C  Send control character to remote
+---    CTRL+T  Send control character to remote
+"""
+
+        def print_help():
+            term.console.write(get_print_help())
+
+
         def input_handler():
             menu_active = False
             while term.alive:
@@ -64,27 +97,27 @@ def input_handler():
                     c = '\x03'
                 if not term.alive:
                     break
-                if menu_active:
+                if menu_active and c in ['p', 'b', '\t', '\x01', '\x03', '\x04', '\x05', '\x06', '\x0c', '\x14']:
                     term.handle_menu_key(c)
                     menu_active = False
                 elif c == term.menu_character:
                     console_print('[MENU]')
                     menu_active = True # next char will be for menu
-                elif c == '\x02' or  c == '\x12': # ctrl+b/ctrl+r sendbreak
+                elif c == '\x02': # ctrl+b sendbreak
                     console_print('[RESET]')
-                    cdc_reset(term.serial)
-                elif c == '\x03' or c == '\x1d': # ctrl+c/ctrl+]
+                    self.reset()
+                elif c == '\x03': # ctrl+c
                     console_print('[QUIT]')
                     term.stop()
                     term.alive = False
                     break
                 elif c == '\x05': # ctrl+e
                     console_print('[ECHO %s]' % ('OFF' if term.echo else 'ON'))
                     term.echo = not term.echo
-                elif c == '\x08': # ctrl+e
-                    print term.get_help_text()
-                elif c == '\t': # tab/ctrl+i
-                    term.dump_port_settings()
+                elif c == '\x08': # ctrl+h
+                    print_help()
+#                elif c == '\t': # tab/ctrl+i
+#                    term.dump_port_settings()
                 else:
                     text = c
                     for transformation in term.tx_transformations:
@@ -97,10 +130,8 @@ def input_handler():
                         term.console.write(echo_text)
         term.writer = input_handler
 
-        if print_term_header:
-            console_print('Terminal on {p.name} - {p.baudrate},{p.bytesize},{p.parity},{p.stopbits}'.format(p=term.serial))
-            console_print('Quit: CTRL+C | Reset: CTRL+B | Echo: CTRL+E')
-            console_print('Info: TAB    | Help:  Ctrl+H | Menu: Ctrl+T')
+        if print_header:
+            console_print("Terminal on {p.name} - {p.baudrate},{p.bytesize},{p.parity},{p.stopbits}".format(p=term.serial))
 
         term.start()
 
@@ -113,20 +144,12 @@ def input_handler():
 
         return True
 
-
-    result = False
-    serial_port = get_instance(port, baudrate=baudrate, timeout=timeout)
-    if serial_port:
-        serial_port.reset_input_buffer()
-        if reset:
-            result = cdc_reset(serial_port)
-
-        if sterm:
-            if not serial_port.is_open:
-                serial_port = get_instance(port, baudrate=baudrate, timeout=timeout)
+    def reset(self):
+        try:
+            self.serial.sendBreak()
+        except:
             try:
-                result = cdc_term(serial_port)
+                self.serial.setBreak(False) # For Linux the following setBreak() is needed to release the reset signal on the target mcu.
             except:
-                pass
-
-    return result
+                return False
+        return True