improved monitor, auto exit

Author: pavelrevak

README.md

@@ -240,7 +240,11 @@ RESET soft
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
 RESET machine
 
-$ mpytool reset -- monitor   # reset and monitor output
+$ mpytool reset -- monitor   # reset and monitor until program ends
+RESET soft
+MONITOR (until program ends, -f to follow)
+
+$ mpytool reset -- monitor -f  # reset and monitor continuously
 RESET soft
 MONITOR (Ctrl+C to stop)
 
@@ -261,7 +265,8 @@ REPL (Ctrl+] to exit)  CWD: /  PATH: : :.frozen :/lib
 
 $ mpytool -p /dev/ttyUSB0 repl       # specify port
 $ mpytool -b 9600 repl               # specify baudrate
-$ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor at 9600 baud
+$ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor until program ends
+$ mpytool monitor -f                        # follow output continuously (Ctrl-C to stop)
 ```
 
 The `repl` command with `-v` flag displays current working directory (CWD) and `sys.path` before entering REPL, making it easy to see the device state after `mount`, `cd`, or `path` commands.
@@ -270,24 +275,30 @@ Both `repl` and `monitor` can be used as general-purpose serial tools - not just
 
 ### Execute Python code on device
 ```
-$ mpytool exec "print('Hello!')"
+$ mpytool exec "print('Hello!')"         # execute and stream output
 EXEC: print('Hello!')
 Hello!
 
 $ mpytool exec "import sys; print(sys.version)"
 EXEC: import sys; print(sys.version)
 3.4.0; MicroPython v1.24.0
+
+$ mpytool exec "long_task()" -t 30       # timeout after 30 seconds
+$ mpytool exec "start_server()" -t 0     # fire-and-forget (don't wait)
 ```
 
 ### Run local Python file on device
 ```
-$ mpytool run script.py                  # run script (fire-and-forget)
+$ mpytool run script.py                  # run and stream output
+RUN: script.py (128 bytes)
+Hello from script!
+
+$ mpytool run script.py -t 0             # fire-and-forget (don't wait)
 RUN: script.py (128 bytes)
 
-$ mpytool run script.py -- monitor       # run script and capture output
+$ mpytool run script.py -t 10            # timeout after 10 seconds
 RUN: script.py (128 bytes)
-MONITOR (Ctrl+C to stop)
-Hello from script!
+Done!
 ```
 
 ### Edit file on device

README_API.md

@@ -1045,20 +1045,24 @@ Low-level REPL communication. Usually accessed via `mpy.comm`.
 
 ### Methods
 
-#### exec(command, timeout=5)
+#### exec(command, timeout=None, stream=False)
 
 Execute Python command on device.
 
 ```python
-mpy.comm.exec(command, timeout=5)
+mpy.comm.exec(command, timeout=None, stream=False)
 ```
 
 **Parameters:**
 - `command` (str): Python code to execute
-- `timeout` (int): Maximum wait time in seconds. `0` = submit only (send code, don't wait for output)
+- `timeout` (float|None): Total wall time in seconds. `None` = wait forever, `0` = submit only (fire-and-forget)
+- `stream`: Output mode:
+  - `False` (default): Return all output as `bytes`
+  - `True`: Return a generator yielding `bytes` chunks
+  - file-like object: Write chunks to it (supports both binary and text streams via `io.TextIOBase` detection), return `b''`
 
 **Returns:**
-- `bytes`: Command stdout output (`b''` when timeout=0)
+- `bytes`, generator, or `b''` (when stream is file-like or timeout=0)
 
 **Example:**
 ```python
@@ -1068,6 +1072,15 @@ b'Hello\r\n'
 >>> mpy.comm.exec("import sys")
 b''
 
+# Streaming output (generator)
+>>> for chunk in mpy.comm.exec("print('Hello')", stream=True):
+...     print(chunk)
+
+# Stream to stdout
+>>> import sys
+>>> mpy.comm.exec("print('Hello')", stream=sys.stdout.buffer)
+b''
+
 # Submit code without waiting for output (fire-and-forget)
 >>> mpy.comm.exec("while True: print('tick')", timeout=0)
 b''
@@ -1132,23 +1145,24 @@ mpy.comm.enter_raw_repl()
 mpy.comm.exit_raw_repl()
 ```
 
-#### exec_raw_paste(command, timeout=5)
+#### exec_raw_paste(command, timeout=5, stream=False)
 
 Execute Python command using raw-paste mode with flow control.
 
 Raw-paste mode compiles code as it receives it, using less RAM and providing
 better reliability for large code transfers. Requires MicroPython 1.17+.
 
 ```python
-mpy.comm.exec_raw_paste(command, timeout=5)
+mpy.comm.exec_raw_paste(command, timeout=5, stream=False)
 ```
 
 **Parameters:**
 - `command` (str or bytes): Python code to execute
-- `timeout` (int): Maximum wait time in seconds. `0` = submit only (send code, don't wait for output)
+- `timeout` (float|None): Total wall time in seconds. `0` = submit only (fire-and-forget)
+- `stream`: Output mode (same as `exec()`: `False`/`True`/file-like object)
 
 **Returns:**
-- `bytes`: Command stdout output (`b''` when timeout=0)
+- `bytes`, generator, or `b''` (depending on `stream` and `timeout`)
 
 **Example:**
 ```python
@@ -1165,20 +1179,21 @@ b'99\r\n'
 - `MpyError`: If raw-paste mode is not supported by device
 - `CmdError`: If command raises an exception on device
 
-#### try_raw_paste(command, timeout=5)
+#### try_raw_paste(command, timeout=5, stream=False)
 
 Try raw-paste mode, fall back to regular exec if not supported.
 
 ```python
-mpy.comm.try_raw_paste(command, timeout=5)
+mpy.comm.try_raw_paste(command, timeout=5, stream=False)
 ```
 
 **Parameters:**
 - `command` (str or bytes): Python code to execute
-- `timeout` (int): Maximum wait time in seconds. `0` = submit only (send code, don't wait for output)
+- `timeout` (float|None): Total wall time in seconds. `0` = submit only (fire-and-forget)
+- `stream`: Output mode (same as `exec()`: `False`/`True`/file-like object)
 
 **Returns:**
-- `bytes`: Command stdout output (`b''` when timeout=0)
+- `bytes`, generator, or `b''` (depending on `stream` and `timeout`)
 
 **Example:**
 ```python
@@ -1191,6 +1206,37 @@ This method automatically detects if raw-paste mode is supported and caches
 the result. On older MicroPython versions, it silently falls back to regular
 `exec()`.
 
+#### monitor(stream=False, follow=False)
+
+Monitor device output in normal REPL mode.
+
+By default, reads output until REPL prompt (`>>>`) is detected (program finished).
+With `follow=True`, reads indefinitely (Ctrl-C to stop).
+
+```python
+mpy.comm.monitor(stream=False, follow=False)
+```
+
+**Parameters:**
+- `stream`: Output mode (same as `exec()`: `False`/`True`/file-like object)
+- `follow` (bool): If `True`, don't stop at REPL prompt
+
+**Returns:**
+- `bytes`, generator, or `b''` (depending on `stream`)
+
+**Example:**
+```python
+# Capture output until program ends
+>>> output = mpy.comm.monitor()
+
+# Stream to stdout
+>>> import sys
+>>> mpy.comm.monitor(stream=sys.stdout.buffer)
+
+# Follow continuously
+>>> mpy.comm.monitor(stream=sys.stdout.buffer, follow=True)
+```
+
 ## Exception Classes
 
 ### MpyError

mpytool/mount.py

@@ -179,7 +179,7 @@
 _ESCAPE_BYTE = bytes([ESCAPE])
 
 _SOFT_REBOOT = b'soft reboot'
-_REPL_PROMPT = b'>>> '
+from mpytool.mpy_comm import REPL_PROMPT as _REPL_PROMPT
 _REBOOT_BUF_MAX = 256
 _REBOOT_BUF_KEEP = 64
 _LISTDIR_LIMIT = 1000  # max entries returned by CMD_LISTDIR

mpytool/mpy_comm.py

@@ -1,5 +1,6 @@
 """MicroPython tool: MPY communication"""
 
+import io as _io
 import re as _re
 import time as _time
 
@@ -13,6 +14,10 @@
 CTRL_D = b'\x04'  # Execute / Soft reset / End raw-paste
 CTRL_E = b'\x05'  # Paste mode
 
+# REPL prompt
+REPL_PROMPT = b'>>> '
+REPL_PROMPT_LINE = b'\r\n' + REPL_PROMPT
+
 # Raw-paste mode
 RAW_PASTE_ENTER = CTRL_E + b'A' + CTRL_A  # Enter raw-paste mode sequence
 RAW_PASTE_ACK = b'\x01'  # Flow control ACK
@@ -121,7 +126,7 @@ def stop_current_operation(self):
             if attempt >= 4:
                 self._conn.write(b'\x18')
             try:
-                self._conn.read_until(b'\r\n>>> ', timeout=0.2)
+                self._conn.read_until(REPL_PROMPT_LINE, timeout=0.2)
                 self._repl_mode = False
                 return True
             except _conn.Timeout:
@@ -149,7 +154,7 @@ def exit_raw_repl(self):
             return
         self._log.info('EXIT RAW REPL')
         self._conn.write(CTRL_B)
-        self._conn.read_until(b'\r\n>>> ')
+        self._conn.read_until(REPL_PROMPT_LINE)
         self._repl_mode = False
 
     def soft_reset(self):
@@ -176,6 +181,52 @@ def reset_state(self):
         self._repl_mode = None
         self._raw_paste_supported = None
 
+    def monitor(self, stream=False, follow=False):
+        """Monitor device output in normal REPL mode.
+
+        Reads device output until REPL prompt (>>>) is detected,
+        or indefinitely if follow=True.
+
+        Arguments:
+            stream: False = return bytes, True = yield chunks,
+                file-like object = write chunks to it and return b''
+            follow: if True, don't stop at REPL prompt
+
+        Returns:
+            bytes result, generator, or b'' (when stream is file-like)
+        """
+        self.exit_raw_repl()
+        if stream is True:
+            return self._monitor_chunks(follow)
+        if stream:
+            return self._monitor_to(stream, follow)
+        return b''.join(self._monitor_chunks(follow))
+
+    def _monitor_chunks(self, follow):
+        """Yield output chunks until REPL prompt (or forever if follow)."""
+        prompt_len = len(REPL_PROMPT_LINE)
+        tail = b''
+        while True:
+            data = self._conn.read(timeout=0.1)
+            if data is None:
+                continue
+            yield data
+            if not follow:
+                # Keep enough bytes so prompt split across chunks is found
+                tail = tail[-(prompt_len - 1):] + data
+                if REPL_PROMPT_LINE in tail:
+                    return
+
+    def _monitor_to(self, out, follow):
+        """Write monitor output to file-like object."""
+        text_mode = isinstance(out, _io.TextIOBase)
+        for chunk in self._monitor_chunks(follow):
+            out.write(
+                chunk.decode('utf-8', 'backslashreplace')
+                if text_mode else chunk)
+            out.flush()
+        return b''
+
     def exec(self, command, timeout=None, stream=False):
         """Execute command
 
@@ -333,7 +384,6 @@ def _exec_stream_to(self, command, timeout, out):
 
         Supports both binary and text streams (io.TextIOBase).
         """
-        import io as _io
         start_time = _time.time()
         result = bytearray()
         text_mode = isinstance(out, _io.TextIOBase)

mpytool/mpytool.py

@@ -438,13 +438,14 @@ def cmd_rm(self, *file_names):
                 self.verbose(f"RM: {path}", 1)
                 self.mpy.delete(path)
 
-    def cmd_monitor(self):
-        self.verbose("MONITOR (Ctrl+C to stop)", 1)
+    def cmd_monitor(self, follow=False):
+        if follow:
+            self.verbose("MONITOR (Ctrl+C to stop)", 1)
+        else:
+            self.verbose("MONITOR (until program ends, -f to follow)", 1)
+        out = getattr(_sys.stdout, 'buffer', _sys.stdout)
         try:
-            while True:
-                line = self.conn.read_line()
-                line = line.decode('utf-8', 'backslashreplace')
-                print(line)
+            self.mpy.comm.monitor(stream=out, follow=follow)
         except KeyboardInterrupt:
             self.verbose('', level=0, overwrite=True)  # newline after ^C
         except (_mpytool.ConnError, OSError) as err:
@@ -907,11 +908,13 @@ def _dispatch_reset(self, commands, is_last_group):
         reconnect = has_more if mode in ('machine', 'rts') else True
         self.cmd_reset(mode=mode, reconnect=reconnect, timeout=args.timeout)
 
-    @command('monitor', 'Monitor device output. Press Ctrl-C to stop.')
+    @command('monitor', 'Monitor device output until program ends.')
+    @option('-f', '--follow', action='store_true',
+        help='follow output continuously (Ctrl-C to stop)')
     def _dispatch_monitor(self, commands, is_last_group):
-        _, commands[:] = _make_parser(
+        args, commands[:] = _make_parser(
             self._dispatch_monitor).parse_known_args(commands)
-        self.cmd_monitor()
+        self.cmd_monitor(follow=args.follow)
 
     @command('repl', 'Interactive REPL session. Press Ctrl-] to exit.')
     def _dispatch_repl(self, commands, is_last_group):