From ad1f523e7ebae5f260e9c586b28e0d75d715cf65 Mon Sep 17 00:00:00 2001
From: Damien George <damien@micropython.org>
Date: Thu, 24 Feb 2022 14:05:51 +1100
Subject: [PATCH] tools/mpremote: Add "resume" and "soft-reset" commands.

This makes the auto soft-reset behaviour of mpremote more logical, and now
configurable via these new commands.

Signed-off-by: Damien George <damien@micropython.org>
---
 docs/reference/mpremote.rst     | 36 +++++++++++++++++++++++++++++++++
 tools/mpremote/mpremote/main.py | 15 +++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst
index 7a7d787a5a..8e3cf9aa5a 100644
--- a/docs/reference/mpremote.rst
+++ b/docs/reference/mpremote.rst
@@ -60,6 +60,25 @@ The full list of supported commands are:
 
       $ mpremote disconnect
 
+  After a disconnect, auto soft-reset is enabled.
+
+- resume a previous ``mpremote`` session:
+
+  .. code-block:: bash
+
+      $ mpremote resume
+
+  This disables auto soft-reset.
+
+- perform a soft-reset of the device:
+
+  .. code-block:: bash
+
+      $ mpremote soft-reset
+
+  This will clear out the Python heap and restart the interpreter.  It also
+  disables auto soft-reset.
+
 - enter the REPL on the connected device:
 
    .. code-block:: bash
@@ -117,11 +136,28 @@ The full list of supported commands are:
       $ mpremote mount <local-dir>
 
 Multiple commands can be specified and they will be run sequentially.
+
+
+Auto connection and soft-reset
+------------------------------
+
 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.
 
+Once connected to a device, ``mpremote`` will automatically soft-reset the
+device if needed.  This clears the Python heap and restarts the interpreter,
+making sure that subsequent Python code executes in a fresh environment.  Auto
+soft-reset is performed the first time one of the following commands are
+executed: ``mount``, ``eval``, ``exec``, ``run``, ``fs``.  After doing a
+soft-reset for the first time, it will not be done again automatically, until a
+``disconnect`` command is issued.
+
+Auto soft-reset behaviour can be controlled by the ``resume`` command.  And the
+``soft-reset`` command can be used to perform an explicit soft reset.
+
+
 Shortcuts
 ---------
 
diff --git a/tools/mpremote/mpremote/main.py b/tools/mpremote/mpremote/main.py
index 1073bec7fa..a53ea66f39 100644
--- a/tools/mpremote/mpremote/main.py
+++ b/tools/mpremote/mpremote/main.py
@@ -39,6 +39,8 @@ _COMMANDS = {
         or any valid device name/path""",
     ),
     "disconnect": (False, False, 0, "disconnect current device"),
+    "resume": (False, False, 0, "resume a previous mpremote session (will not auto soft-reset)"),
+    "soft-reset": (False, True, 0, "perform a soft-reset of the device"),
     "mount": (True, False, 1, "mount local directory on device"),
     "repl": (
         False,
@@ -434,6 +436,7 @@ def main():
 
     args = sys.argv[1:]
     pyb = None
+    auto_soft_reset = True
     did_action = False
 
     try:
@@ -460,13 +463,19 @@ def main():
             elif cmd == "help":
                 print_help()
                 sys.exit(0)
+            elif cmd == "resume":
+                auto_soft_reset = False
+                continue
+
+            # The following commands need a connection, and either a raw or friendly REPL.
 
             if pyb is None:
                 pyb = do_connect(["auto"])
 
             if need_raw_repl:
                 if not pyb.in_raw_repl:
-                    pyb.enter_raw_repl()
+                    pyb.enter_raw_repl(soft_reset=auto_soft_reset)
+                    auto_soft_reset = False
             else:
                 if pyb.in_raw_repl:
                     pyb.exit_raw_repl()
@@ -476,6 +485,10 @@ def main():
             if cmd == "disconnect":
                 do_disconnect(pyb)
                 pyb = None
+                auto_soft_reset = True
+            elif cmd == "soft-reset":
+                pyb.enter_raw_repl(soft_reset=True)
+                auto_soft_reset = False
             elif cmd == "mount":
                 path = args.pop(0)
                 pyb.mount_local(path)