mpytool 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

mpytool/mpy_comm.py

@@ -2,6 +2,17 @@
 
 import mpytool.conn as _conn
 
+# REPL control characters
+CTRL_A = b'\x01'  # Enter raw REPL
+CTRL_B = b'\x02'  # Exit raw REPL
+CTRL_C = b'\x03'  # Interrupt
+CTRL_D = b'\x04'  # Execute / Soft reset / End raw-paste
+CTRL_E = b'\x05'  # Paste mode
+
+# 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
+
 
 class MpyError(Exception):
     """General MPY error"""
@@ -41,6 +52,7 @@ class MpyComm():
         self._conn = conn
         self._log = log
         self._repl_mode = None
+        self._raw_paste_supported = None  # None = unknown, True/False = detected
 
     @property
     def conn(self):
@@ -60,8 +72,6 @@ class MpyComm():
             return True
         if self._log:
             self._log.info('STOP CURRENT OPERATION')
-
-        # Flush any pending data first
         self._conn.flush()
 
         # Try multiple attempts with short timeouts
@@ -70,9 +80,9 @@ class MpyComm():
         for attempt in range(15):
             # Alternate: Ctrl-C, Ctrl-C, Ctrl-B, repeat
             if attempt % 3 == 2:
-                self._conn.write(b'\x02')  # Ctrl-B - exit raw REPL
+                self._conn.write(CTRL_B)
             else:
-                self._conn.write(b'\x03')  # Ctrl-C - interrupt program
+                self._conn.write(CTRL_C)
             try:
                 self._conn.read_until(b'\r\n>>> ', timeout=0.2)
                 self._repl_mode = False
@@ -96,7 +106,7 @@ class MpyComm():
                 self._log.warning('..retry %d/%d', retries, max_retries)
         if self._log:
             self._log.info('ENTER RAW REPL')
-        self._conn.write(b'\x01')
+        self._conn.write(CTRL_A)
         self._conn.read_until(b'\r\n>')
         self._repl_mode = True
 
@@ -105,7 +115,7 @@ class MpyComm():
             return
         if self._log:
             self._log.info('EXIT RAW REPL')
-        self._conn.write(b'\x02')
+        self._conn.write(CTRL_B)
         self._conn.read_until(b'\r\n>>> ')
         self._repl_mode = False
 
@@ -114,9 +124,21 @@ class MpyComm():
         self.exit_raw_repl()
         if self._log:
             self._log.info('SOFT RESET')
-        self._conn.write(b'\x04')
+        self._conn.write(CTRL_D)
         self._conn.read_until(b'soft reboot', timeout=1)
         self._repl_mode = None
+        self._raw_paste_supported = None
+
+    def soft_reset_raw(self):
+        """Soft reset in raw REPL mode - clears RAM but doesn't run boot.py/main.py"""
+        self.enter_raw_repl()
+        if self._log:
+            self._log.info('SOFT RESET (raw)')
+        self._conn.write(CTRL_D)
+        self._conn.read_until(b'soft reboot', timeout=1)
+        self._conn.read_until(b'>', timeout=1)
+        self._repl_mode = True
+        self._raw_paste_supported = None
 
     def exec(self, command, timeout=5):
         """Execute command
@@ -131,18 +153,17 @@ class MpyComm():
         Raises:
             CmdError when command return error
         """
-        # wait for prompt
         self.enter_raw_repl()
         if self._log:
             self._log.info("CMD: %s", command)
         self._conn.write(bytes(command, 'utf-8'))
-        self._conn.write(b'\x04')
+        self._conn.write(CTRL_D)
         self._conn.read_until(b'OK', timeout)
-        result = self._conn.read_until(b'\x04', timeout)
+        result = self._conn.read_until(CTRL_D, timeout)
         if result:
             if self._log:
                 self._log.info('RES: %s', bytes(result))
-        err = self._conn.read_until(b'\x04>', timeout)
+        err = self._conn.read_until(CTRL_D + b'>', timeout)
         if err:
             raise CmdError(command, result, err)
         return result
@@ -150,3 +171,111 @@ class MpyComm():
     def exec_eval(self, command, timeout=5):
         result = self.exec(f'print({command})', timeout)
         return eval(result)
+
+    def exec_raw_paste(self, command, timeout=5):
+        """Execute 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.
+
+        Arguments:
+            command: command to execute (str or bytes)
+            timeout: maximum waiting time for result
+
+        Returns:
+            command STDOUT result
+
+        Raises:
+            CmdError when command returns error
+            MpyError when raw-paste mode is not supported
+        """
+        self.enter_raw_repl()
+
+        if isinstance(command, str):
+            command = command.encode('utf-8')
+
+        if self._log:
+            self._log.info("CMD (raw-paste, %d bytes)", len(command))
+
+        self._conn.write(RAW_PASTE_ENTER)
+
+        # Read response: 'R' + status (0=not supported, 1=supported)
+        header, status = self._conn.read_bytes(2, timeout)
+        if header != ord('R'):
+            raise MpyError(f"Unexpected raw-paste header: {header!r}")
+
+        if status == 0:
+            self._raw_paste_supported = False
+            raise MpyError("Raw-paste mode not supported by device")
+
+        if status != 1:
+            raise MpyError(f"Unexpected raw-paste status: {status}")
+
+        self._raw_paste_supported = True
+
+        # Read window size (16-bit little-endian)
+        window_bytes = self._conn.read_bytes(2, timeout)
+        window_size = int.from_bytes(window_bytes, 'little')
+        if self._log:
+            self._log.info("Raw-paste window size: %d", window_size)
+
+        # Send data with flow control
+        remaining_window = window_size
+        offset = 0
+
+        while offset < len(command):
+            # Check for incoming flow control byte (non-blocking)
+            if remaining_window == 0 or self._conn._has_data(0):
+                flow_byte = self._conn.read_bytes(1, timeout)
+                if flow_byte == RAW_PASTE_ACK:
+                    remaining_window += window_size
+                elif flow_byte == CTRL_D:
+                    # Device wants to abort - syntax error during compilation
+                    self._conn.write(CTRL_D)
+                    break
+
+            # Send data up to remaining window size
+            if remaining_window > 0:
+                chunk_size = min(remaining_window, len(command) - offset)
+                self._conn.write(command[offset:offset + chunk_size])
+                offset += chunk_size
+                remaining_window -= chunk_size
+
+        self._conn.write(CTRL_D)
+
+        # Consume remaining ACKs and wait for CTRL_D echo
+        while True:
+            byte = self._conn.read_bytes(1, timeout)
+            if byte == CTRL_D:
+                break
+
+        result = self._conn.read_until(CTRL_D, timeout)
+        if result and self._log:
+            self._log.info('RES: %s', bytes(result))
+        err = self._conn.read_until(CTRL_D + b'>', timeout)
+        if err:
+            raise CmdError(command.decode('utf-8', errors='replace'), result, err)
+        return result
+
+    def try_raw_paste(self, command, timeout=5):
+        """Try raw-paste mode, fall back to regular exec if not supported.
+
+        Arguments:
+            command: command to execute
+            timeout: maximum waiting time for result
+
+        Returns:
+            command STDOUT result
+        """
+        # If we know raw-paste is not supported, skip it
+        if self._raw_paste_supported is False:
+            return self.exec(command, timeout)
+
+        try:
+            return self.exec_raw_paste(command, timeout)
+        except MpyError as e:
+            if "not supported" in str(e):
+                if self._log:
+                    self._log.info("Raw-paste not supported, using regular exec")
+                return self.exec(command, timeout)
+            raise