tools/mpremote: Add new CLI utility to interact with remote device.

This has been under development since April 2017.  See #3034 and #6375.
Signed-off-by: Damien George <damien@micropython.org>

tools/mpremote/LICENSE

+The MIT License (MIT)
+
+Copyright (c) 2021 Damien P. George
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

tools/mpremote/README.md

+# mpremote -- MicroPython remote control
+
+This CLI tool provides an integrated set of utilities to remotely interact with
+and automate a MicroPython device over a serial connection.
+
+The simplest way to use this tool is:
+
+    mpremote
+
+This will automatically connect to the device and provide an interactive REPL.
+
+The full list of supported commands are:
+
+    mpremote connect <device>        -- connect to given device
+                                        device may be: list, auto, id:x, port:x
+                                        or any valid device name/path
+    mpremote disconnect              -- disconnect current device
+    mpremote mount <local-dir>       -- mount local directory on device
+    mpremote eval <string>           -- evaluate and print the string
+    mpremote exec <string>           -- execute the string
+    mpremote run <file>              -- run the given local script
+    mpremote fs <command> <args...>  -- execute filesystem commands on the device
+                                        command may be: cat, ls, cp, rm, mkdir, rmdir
+                                        use ":" as a prefix to specify a file on the device
+    mpremote repl                    -- enter REPL
+                                        options:
+                                            --capture <file>
+                                            --inject-code <string>
+                                            --inject-file <file>
+
+Multiple commands can be specified and they will be run sequentially.  Connection
+and disconnection will be done automatically at the start and end of the execution
+of the tool, if such commands are not explicitly given.  Automatic connection will
+search for the first available serial device.  If no action is specified then the
+REPL will be entered.
+
+Shortcuts can be defined using the macro system.  Built-in shortcuts are:
+
+- a0, a1, a2, a3: connect to `/dev/ttyACM?`
+- u0, u1, u2, u3: connect to `/dev/ttyUSB?`
+- c0, c1, c2, c3: connect to `COM?`
+- cat, ls, cp, rm, mkdir, rmdir, df: filesystem commands
+- reset: reset the device
+- bootloader: make the device enter its bootloader
+
+Any user configuration, including user-defined shortcuts, can be placed in
+.config/mpremote/config.py.  For example:
+
+    # Custom macro commands
+    commands = {
+        "c33": "connect id:334D335C3138",
+        "bl": "bootloader",
+        "double x=4": "eval x*2",
+    }
+
+Examples:
+
+    mpremote
+    mpremote a1
+    mpremote connect /dev/ttyUSB0 repl
+    mpremote ls
+    mpremote a1 ls
+    mpremote exec "import micropython; micropython.mem_info()"
+    mpremote eval 1/2 eval 3/4
+    mpremote mount .
+    mpremote mount . exec "import local_script"
+    mpremote ls
+    mpremote cat boot.py
+    mpremote cp :main.py .
+    mpremote cp main.py :
+    mpremote cp -r dir/ :

tools/mpremote/mpremote.py

+#!/usr/bin/env python3
+
+import sys
+from mpremote import main
+
+sys.exit(main.main())

tools/mpremote/mpremote/__init__.py

+# empty

tools/mpremote/mpremote/console.py

+import sys
+
+try:
+    import select, termios
+except ImportError:
+    termios = None
+    select = None
+    import msvcrt
+
+
+class ConsolePosix:
+    def __init__(self):
+        self.infd = sys.stdin.fileno()
+        self.infile = sys.stdin.buffer.raw
+        self.outfile = sys.stdout.buffer.raw
+        self.orig_attr = termios.tcgetattr(self.infd)
+
+    def enter(self):
+        # attr is: [iflag, oflag, cflag, lflag, ispeed, ospeed, cc]
+        attr = termios.tcgetattr(self.infd)
+        attr[0] &= ~(
+            termios.BRKINT | termios.ICRNL | termios.INPCK | termios.ISTRIP | termios.IXON
+        )
+        attr[1] = 0
+        attr[2] = attr[2] & ~(termios.CSIZE | termios.PARENB) | termios.CS8
+        attr[3] = 0
+        attr[6][termios.VMIN] = 1
+        attr[6][termios.VTIME] = 0
+        termios.tcsetattr(self.infd, termios.TCSANOW, attr)
+
+    def exit(self):
+        termios.tcsetattr(self.infd, termios.TCSANOW, self.orig_attr)
+
+    def waitchar(self):
+        # TODO pyb.serial might not have fd
+        select.select([console_in.infd, pyb.serial.fd], [], [])
+
+    def readchar(self):
+        res = select.select([self.infd], [], [], 0)
+        if res[0]:
+            return self.infile.read(1)
+        else:
+            return None
+
+    def write(self, buf):
+        self.outfile.write(buf)
+
+
+class ConsoleWindows:
+    KEY_MAP = {
+        b"H": b"A",  # UP
+        b"P": b"B",  # DOWN
+        b"M": b"C",  # RIGHT
+        b"K": b"D",  # LEFT
+        b"G": b"H",  # POS1
+        b"O": b"F",  # END
+        b"Q": b"6~",  # PGDN
+        b"I": b"5~",  # PGUP
+        b"s": b"1;5D",  # CTRL-LEFT,
+        b"t": b"1;5C",  # CTRL-RIGHT,
+        b"\x8d": b"1;5A",  #  CTRL-UP,
+        b"\x91": b"1;5B",  # CTRL-DOWN,
+        b"w": b"1;5H",  # CTRL-POS1
+        b"u": b"1;5F",  # CTRL-END
+        b"\x98": b"1;3A",  #  ALT-UP,
+        b"\xa0": b"1;3B",  # ALT-DOWN,
+        b"\x9d": b"1;3C",  #  ALT-RIGHT,
+        b"\x9b": b"1;3D",  # ALT-LEFT,
+        b"\x97": b"1;3H",  #  ALT-POS1,
+        b"\x9f": b"1;3F",  # ALT-END,
+        b"S": b"3~",  # DEL,
+        b"\x93": b"3;5~",  # CTRL-DEL
+        b"R": b"2~",  # INS
+        b"\x92": b"2;5~",  # CTRL-INS
+        b"\x94": b"Z",  # Ctrl-Tab = BACKTAB,
+    }
+
+    def enter(self):
+        pass
+
+    def exit(self):
+        pass
+
+    def inWaiting(self):
+        return 1 if msvcrt.kbhit() else 0
+
+    def waitchar(self):
+        while not (self.inWaiting() or pyb.serial.inWaiting()):
+            time.sleep(0.01)
+
+    def readchar(self):
+        if msvcrt.kbhit():
+            ch = msvcrt.getch()
+            while ch in b"\x00\xe0":  # arrow or function key prefix?
+                if not msvcrt.kbhit():
+                    return None
+                ch = msvcrt.getch()  # second call returns the actual key code
+                try:
+                    ch = b"\x1b[" + self.KEY_MAP[ch]
+                except KeyError:
+                    return None
+            return ch
+
+    def write(self, buf):
+        buf = buf.decode() if isinstance(buf, bytes) else buf
+        sys.stdout.write(buf)
+        sys.stdout.flush()
+        # for b in buf:
+        #     if isinstance(b, bytes):
+        #         msvcrt.putch(b)
+        #     else:
+        #         msvcrt.putwch(b)
+
+
+if termios:
+    Console = ConsolePosix
+    VT_ENABLED = True
+else:
+    Console = ConsoleWindows
+
+    # Windows VT mode ( >= win10 only)
+    # https://bugs.python.org/msg291732
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+
+    ERROR_INVALID_PARAMETER = 0x0057
+    ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+
+    def _check_bool(result, func, args):
+        if not result:
+            raise ctypes.WinError(ctypes.get_last_error())
+        return args
+
+    LPDWORD = ctypes.POINTER(wintypes.DWORD)
+    kernel32.GetConsoleMode.errcheck = _check_bool
+    kernel32.GetConsoleMode.argtypes = (wintypes.HANDLE, LPDWORD)
+    kernel32.SetConsoleMode.errcheck = _check_bool
+    kernel32.SetConsoleMode.argtypes = (wintypes.HANDLE, wintypes.DWORD)
+
+    def set_conout_mode(new_mode, mask=0xFFFFFFFF):
+        # don't assume StandardOutput is a console.
+        # open CONOUT$ instead
+        fdout = os.open("CONOUT$", os.O_RDWR)
+        try:
+            hout = msvcrt.get_osfhandle(fdout)
+            old_mode = wintypes.DWORD()
+            kernel32.GetConsoleMode(hout, ctypes.byref(old_mode))
+            mode = (new_mode & mask) | (old_mode.value & ~mask)
+            kernel32.SetConsoleMode(hout, mode)
+            return old_mode.value
+        finally:
+            os.close(fdout)
+
+    # def enable_vt_mode():
+    mode = mask = ENABLE_VIRTUAL_TERMINAL_PROCESSING
+    try:
+        set_conout_mode(mode, mask)
+        VT_ENABLED = True
+    except WindowsError as e:
+        VT_ENABLED = False

tools/mpremote/pyproject.toml

+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

tools/mpremote/setup.cfg

+[metadata]
+name = mpremote
+version = 0.0.4
+author = Damien George
+author_email = damien@micropython.org
+description = Tool for interacting remotely with MicroPython
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/micropython/micropython
+project_urls =
+    Bug Tracker = https://github.com/micropython/micropython/issues
+classifiers =
+    Programming Language :: Python :: 3
+    License :: OSI Approved :: MIT License
+    Operating System :: OS Independent
+
+[options]
+packages = mpremote
+python_requires = >= 3.4
+install_requires =
+    pyserial >= 3.3
+
+[options.entry_points]
+console_scripts =
+  mpremote = mpremote.main:main