mpytool 2.2.2__tar.gz → 2.2.4__tar.gz

{mpytool-2.2.2 → mpytool-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.2.2
+Version: 2.2.4
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavel.revak@gmail.com>
 License-Expression: MIT
@@ -74,25 +74,25 @@ Then restart your shell (`exec zsh` or `exec bash`) and use `mpytool` directly.
 
 Adding venv bin at the end of PATH keeps your system `python` and `pip` as default, while making `mpytool` available when not found elsewhere.
 
-## Examples:
+## Examples
 
-help:
+### Help
 ```
 $ mpytool --help
 ```
 
-list files:
+### List files
 ```
 $ mpytool -p /dev/ttyACM0 ls         # list CWD (default)
 $ mpytool -p /dev/ttyACM0 ls :/lib   # list /lib
 ```
 
-tree:
+### Tree
 ```
 $ mpytool -p /dev/ttyACM0 tree       # tree of CWD (default)
 ```
 
-copy files (: prefix = device path):
+### Copy files (: prefix = device path)
 ```
 $ mpytool cp main.py :/             # upload file to device root
 $ mpytool cp main.py lib.py :/lib/  # upload multiple files to directory
@@ -103,36 +103,46 @@ $ mpytool cp :/main.py ./           # download file to current directory
 $ mpytool cp :/ ./backup/           # download entire device to backup/
 $ mpytool cp :/old.py :/new.py      # copy file on device
 $ mpytool cp -f main.py :/          # force upload even if unchanged
+$ mpytool cp -m myapp :/            # compile .py to .mpy via mpy-cross
 ```
 
 Path semantics: `:` = device CWD, `:/` = device root. Trailing `/` on source = copy contents only.
 Unchanged files are automatically skipped (compares size and SHA256 hash).
 Use `-f` or `--force` to upload all files regardless.
 
-transfer options:
+### Transfer options
 ```
 $ mpytool cp -z main.py :/           # force compression (auto-detected by default)
 $ mpytool cp --no-compress data.bin :/  # disable compression
 $ mpytool -c 8K cp main.py :/        # set chunk size (512, 1K, 2K, 4K, 8K, 16K, 32K)
+$ mpytool cp -m myapp :/             # compile .py to .mpy before upload
+$ mpytool cp -fm myapp :/            # force upload + compile .mpy
 ```
 
 Compression is auto-detected based on device RAM and deflate module availability.
 Chunk size is auto-detected based on free RAM (larger chunks = faster transfer).
 
-move/rename on device:
+The `-m`/`--mpy` flag compiles `.py` files to `.mpy` bytecode using `mpy-cross` before upload.
+Compiled files are cached in `__pycache__/` (recompiled only when source changes).
+`boot.py` and `main.py` are always uploaded as `.py` (firmware requirement).
+Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version differs
+from device, automatically uses `-b` flag to target the correct bytecode version.
+If `mpy-cross` is not found, falls back to uploading `.py` with a warning.
+
+### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
 $ mpytool mv :/file.py :/lib/       # move file to directory
 $ mpytool mv :/a.py :/b.py :/lib/   # move multiple files to directory
 ```
 
-view file contents:
+### View file contents
 ```
 $ mpytool cat :boot.py            # print file from CWD
 $ mpytool cat :/lib/module.py     # print file with absolute path
 ```
 
-make directory, delete files (: prefix = device path):
+### Make directory, delete files (: prefix = device path)
 ```
 $ mpytool mkdir :lib :data        # create directories in CWD
 $ mpytool mkdir :/lib/subdir      # create with absolute path
@@ -143,7 +153,7 @@ $ mpytool rm :                    # delete everything in CWD
 $ mpytool rm :/                   # delete everything on device (root)
 ```
 
-current working directory:
+### Current working directory
 ```
 $ mpytool pwd                     # print current directory
 /
@@ -153,7 +163,7 @@ $ mpytool cd :..                  # change to parent directory
 $ mpytool cd :/lib -- ls          # change directory and list files
 ```
 
-reset and REPL:
+### Reset and REPL
 ```
 $ mpytool reset              # soft reset (Ctrl-D, runs boot.py/main.py)
 $ mpytool reset --raw        # soft reset in raw REPL (clears RAM only)
@@ -167,7 +177,7 @@ $ mpytool repl               # enter REPL mode
 $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 ```
 
-serial terminal and monitor (general purpose):
+### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
 $ mpytool -p /dev/ttyUSB0 repl       # specify port
@@ -177,13 +187,32 @@ $ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor at 9600 baud
 
 Both `repl` and `monitor` can be used as general-purpose serial tools - not just for MicroPython devices. Use them to interact with any serial device (Arduino, ESP with custom firmware, GPS modules, etc.). When only one serial port is detected, it is used automatically. Default baudrate is 115200.
 
-execute Python code on device:
+### Execute Python code on device
 ```
 $ mpytool exec "print('Hello!')"
 $ mpytool exec "import sys; print(sys.version)"
 ```
 
-show device information:
+### Run local Python file on device
+```
+$ mpytool run script.py                  # run script (fire-and-forget)
+$ mpytool run script.py -- monitor       # run script and capture output
+```
+
+### Serial link speed test
+```
+$ mpytool speedtest
+SPEEDTEST
+               upload      download  verify
+     0B             -             -  ok
+    16B       11.8K/s       24.4K/s  ok
+    32B       13.1K/s       42.6K/s  ok
+  ...
+  4.00K        120K/s       11.1K/s  ok
+  8.00K        157K/s       11.0K/s  ok
+```
+
+### Show device information
 ```
 $ mpytool info
 Platform:    rp2
@@ -201,7 +230,7 @@ MAC WiFi:    aa:bb:cc:dd:ee:01
 MAC WiFi AP: aa:bb:cc:dd:ee:02
 ```
 
-flash operations (RP2 and ESP32):
+### Flash operations (RP2 and ESP32)
 ```
 # RP2 - user flash (entire filesystem area)
 $ mpytool flash                       # show flash info and filesystem type
@@ -227,20 +256,20 @@ $ mpytool flash erase vfs                  # quick erase partition
 $ mpytool flash erase vfs --full           # full erase partition
 ```
 
-OTA firmware update (ESP32):
+### OTA firmware update (ESP32)
 ```
 $ mpytool ota firmware.app-bin                    # flash to next OTA partition
 $ mpytool ota firmware.app-bin -- reset --machine          # flash and reboot
 $ mpytool ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
 ```
 
-multiple commands separated by `--`:
+### Multiple commands separated by `--`
 ```
 $ mpytool cp main.py boot.py : -- reset -- monitor
 $ mpytool rm :old.py -- cp new.py : -- reset
 ```
 
-auto-detect serial port (if only one device is connected):
+### Auto-detect serial port (if only one device is connected)
 ```
 $ mpytool ls lib/
           uhttp/
@@ -248,7 +277,7 @@ $ mpytool ls lib/
   4.95 KB wlan_http.py
 ```
 
-tree view:
+### Tree view
 ```
 $ mpytool tree
    142 KB ./
@@ -266,18 +295,18 @@ $ mpytool tree
   3.03 KB └─ main.py
 ```
 
-connect over network (TCP, default port 23):
+### Connect over network (TCP, default port 23)
 ```
 $ mpytool -a 192.168.1.100 ls
 $ mpytool -a 192.168.1.100:8266 tree
 ```
 
-set baudrate (default 115200):
+### Set baudrate (default 115200)
 ```
 $ mpytool -p /dev/ttyACM0 -b 9600 ls
 ```
 
-show version:
+### Show version
 ```
 $ mpytool -V
 ```

{mpytool-2.2.2 → mpytool-2.2.4}/README.md

@@ -60,25 +60,25 @@ Then restart your shell (`exec zsh` or `exec bash`) and use `mpytool` directly.
 
 Adding venv bin at the end of PATH keeps your system `python` and `pip` as default, while making `mpytool` available when not found elsewhere.
 
-## Examples:
+## Examples
 
-help:
+### Help
 ```
 $ mpytool --help
 ```
 
-list files:
+### List files
 ```
 $ mpytool -p /dev/ttyACM0 ls         # list CWD (default)
 $ mpytool -p /dev/ttyACM0 ls :/lib   # list /lib
 ```
 
-tree:
+### Tree
 ```
 $ mpytool -p /dev/ttyACM0 tree       # tree of CWD (default)
 ```
 
-copy files (: prefix = device path):
+### Copy files (: prefix = device path)
 ```
 $ mpytool cp main.py :/             # upload file to device root
 $ mpytool cp main.py lib.py :/lib/  # upload multiple files to directory
@@ -89,36 +89,46 @@ $ mpytool cp :/main.py ./           # download file to current directory
 $ mpytool cp :/ ./backup/           # download entire device to backup/
 $ mpytool cp :/old.py :/new.py      # copy file on device
 $ mpytool cp -f main.py :/          # force upload even if unchanged
+$ mpytool cp -m myapp :/            # compile .py to .mpy via mpy-cross
 ```
 
 Path semantics: `:` = device CWD, `:/` = device root. Trailing `/` on source = copy contents only.
 Unchanged files are automatically skipped (compares size and SHA256 hash).
 Use `-f` or `--force` to upload all files regardless.
 
-transfer options:
+### Transfer options
 ```
 $ mpytool cp -z main.py :/           # force compression (auto-detected by default)
 $ mpytool cp --no-compress data.bin :/  # disable compression
 $ mpytool -c 8K cp main.py :/        # set chunk size (512, 1K, 2K, 4K, 8K, 16K, 32K)
+$ mpytool cp -m myapp :/             # compile .py to .mpy before upload
+$ mpytool cp -fm myapp :/            # force upload + compile .mpy
 ```
 
 Compression is auto-detected based on device RAM and deflate module availability.
 Chunk size is auto-detected based on free RAM (larger chunks = faster transfer).
 
-move/rename on device:
+The `-m`/`--mpy` flag compiles `.py` files to `.mpy` bytecode using `mpy-cross` before upload.
+Compiled files are cached in `__pycache__/` (recompiled only when source changes).
+`boot.py` and `main.py` are always uploaded as `.py` (firmware requirement).
+Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version differs
+from device, automatically uses `-b` flag to target the correct bytecode version.
+If `mpy-cross` is not found, falls back to uploading `.py` with a warning.
+
+### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
 $ mpytool mv :/file.py :/lib/       # move file to directory
 $ mpytool mv :/a.py :/b.py :/lib/   # move multiple files to directory
 ```
 
-view file contents:
+### View file contents
 ```
 $ mpytool cat :boot.py            # print file from CWD
 $ mpytool cat :/lib/module.py     # print file with absolute path
 ```
 
-make directory, delete files (: prefix = device path):
+### Make directory, delete files (: prefix = device path)
 ```
 $ mpytool mkdir :lib :data        # create directories in CWD
 $ mpytool mkdir :/lib/subdir      # create with absolute path
@@ -129,7 +139,7 @@ $ mpytool rm :                    # delete everything in CWD
 $ mpytool rm :/                   # delete everything on device (root)
 ```
 
-current working directory:
+### Current working directory
 ```
 $ mpytool pwd                     # print current directory
 /
@@ -139,7 +149,7 @@ $ mpytool cd :..                  # change to parent directory
 $ mpytool cd :/lib -- ls          # change directory and list files
 ```
 
-reset and REPL:
+### Reset and REPL
 ```
 $ mpytool reset              # soft reset (Ctrl-D, runs boot.py/main.py)
 $ mpytool reset --raw        # soft reset in raw REPL (clears RAM only)
@@ -153,7 +163,7 @@ $ mpytool repl               # enter REPL mode
 $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
 ```
 
-serial terminal and monitor (general purpose):
+### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
 $ mpytool -p /dev/ttyUSB0 repl       # specify port
@@ -163,13 +173,32 @@ $ mpytool -p /dev/ttyUSB0 -b 9600 monitor   # monitor at 9600 baud
 
 Both `repl` and `monitor` can be used as general-purpose serial tools - not just for MicroPython devices. Use them to interact with any serial device (Arduino, ESP with custom firmware, GPS modules, etc.). When only one serial port is detected, it is used automatically. Default baudrate is 115200.
 
-execute Python code on device:
+### Execute Python code on device
 ```
 $ mpytool exec "print('Hello!')"
 $ mpytool exec "import sys; print(sys.version)"
 ```
 
-show device information:
+### Run local Python file on device
+```
+$ mpytool run script.py                  # run script (fire-and-forget)
+$ mpytool run script.py -- monitor       # run script and capture output
+```
+
+### Serial link speed test
+```
+$ mpytool speedtest
+SPEEDTEST
+               upload      download  verify
+     0B             -             -  ok
+    16B       11.8K/s       24.4K/s  ok
+    32B       13.1K/s       42.6K/s  ok
+  ...
+  4.00K        120K/s       11.1K/s  ok
+  8.00K        157K/s       11.0K/s  ok
+```
+
+### Show device information
 ```
 $ mpytool info
 Platform:    rp2
@@ -187,7 +216,7 @@ MAC WiFi:    aa:bb:cc:dd:ee:01
 MAC WiFi AP: aa:bb:cc:dd:ee:02
 ```
 
-flash operations (RP2 and ESP32):
+### Flash operations (RP2 and ESP32)
 ```
 # RP2 - user flash (entire filesystem area)
 $ mpytool flash                       # show flash info and filesystem type
@@ -213,20 +242,20 @@ $ mpytool flash erase vfs                  # quick erase partition
 $ mpytool flash erase vfs --full           # full erase partition
 ```
 
-OTA firmware update (ESP32):
+### OTA firmware update (ESP32)
 ```
 $ mpytool ota firmware.app-bin                    # flash to next OTA partition
 $ mpytool ota firmware.app-bin -- reset --machine          # flash and reboot
 $ mpytool ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
 ```
 
-multiple commands separated by `--`:
+### Multiple commands separated by `--`
 ```
 $ mpytool cp main.py boot.py : -- reset -- monitor
 $ mpytool rm :old.py -- cp new.py : -- reset
 ```
 
-auto-detect serial port (if only one device is connected):
+### Auto-detect serial port (if only one device is connected)
 ```
 $ mpytool ls lib/
           uhttp/
@@ -234,7 +263,7 @@ $ mpytool ls lib/
   4.95 KB wlan_http.py
 ```
 
-tree view:
+### Tree view
 ```
 $ mpytool tree
    142 KB ./
@@ -252,18 +281,18 @@ $ mpytool tree
   3.03 KB └─ main.py
 ```
 
-connect over network (TCP, default port 23):
+### Connect over network (TCP, default port 23)
 ```
 $ mpytool -a 192.168.1.100 ls
 $ mpytool -a 192.168.1.100:8266 tree
 ```
 
-set baudrate (default 115200):
+### Set baudrate (default 115200)
 ```
 $ mpytool -p /dev/ttyACM0 -b 9600 ls
 ```
 
-show version:
+### Show version
 ```
 $ mpytool -V
 ```

{mpytool-2.2.2 → mpytool-2.2.4}/mpytool/mpy.py

@@ -5,6 +5,9 @@ import zlib
 
 import mpytool.mpy_comm as _mpy_comm
 
+# Timeout for flash I/O operations (open/close/gc) - some FLASH GC can block >5s
+FLASH_IO_TIMEOUT = 20
+
 
 def _escape_path(path: str) -> str:
     """Escape path for use in Python string literal"""
@@ -515,7 +518,7 @@ def _mt_pfind(label):
             self.import_module('deflate as df')
             self.import_module('io as _io')
 
-        self._mpy_comm.exec(f"f = open('{_escape_path(path)}', 'wb')")
+        self._mpy_comm.exec(f"f = open('{_escape_path(path)}', 'wb')", timeout=FLASH_IO_TIMEOUT)
         while data:
             chunk = data[:chunk_size]
             cmd, orig_size, enc_type = self._encode_chunk(chunk, compress)
@@ -527,10 +530,10 @@ def _mt_pfind(label):
             transferred += orig_size
             if progress_callback:
                 progress_callback(transferred, total_size)
-        self._mpy_comm.exec("f.close()")
+        self._mpy_comm.exec("f.close()", timeout=FLASH_IO_TIMEOUT)
         # Run garbage collection to free memory and allow flash to settle
         self.import_module('gc')
-        self._mpy_comm.exec("gc.collect()")
+        self._mpy_comm.exec("gc.collect()", timeout=FLASH_IO_TIMEOUT)
         return encodings_used, wire_bytes
 
     def platform(self):
@@ -540,15 +543,20 @@ def _mt_pfind(label):
             dict with keys:
                 'platform': platform name (e.g. 'esp32')
                 'version': MicroPython version string
-                'impl': implementation name (e.g. 'micropython')
+                'impl_name': implementation name (e.g. 'micropython')
+                'impl_version': implementation version tuple (e.g. (1, 24, 0))
                 'machine': machine description (or None)
+                'mpy_ver': mpy bytecode major version (e.g. 6) or None
+                'mpy_sub': mpy bytecode sub-version (e.g. 3) or None
         """
         self.import_module('sys')
         self.import_module('os')
 
         platform = self._mpy_comm.exec_eval("repr(sys.platform)")
         version = self._mpy_comm.exec_eval("repr(sys.version)")
-        impl = self._mpy_comm.exec_eval("repr(sys.implementation.name)")
+        impl_name = self._mpy_comm.exec_eval("repr(sys.implementation.name)")
+        impl_version = self._mpy_comm.exec_eval(
+            "tuple(sys.implementation.version)")
 
         try:
             uname = self._mpy_comm.exec_eval("tuple(os.uname())")
@@ -556,11 +564,25 @@ def _mt_pfind(label):
         except _mpy_comm.CmdError:
             machine = None
 
+        try:
+            mpy_int = self._mpy_comm.exec_eval("sys.implementation._mpy")
+            mpy_ver = mpy_int & 0xFF
+            mpy_sub = (mpy_int >> 8) & 3
+            mpy_arch = (mpy_int >> 10) & 0x0F
+        except (_mpy_comm.CmdError, AttributeError):
+            mpy_ver = None
+            mpy_sub = None
+            mpy_arch = 0
+
         return {
             'platform': platform,
             'version': version,
-            'impl': impl,
+            'impl_name': impl_name,
+            'impl_version': impl_version,
             'machine': machine,
+            'mpy_ver': mpy_ver,
+            'mpy_sub': mpy_sub,
+            'mpy_arch': mpy_arch,
         }
 
     def memory(self):

{mpytool-2.2.2 → mpytool-2.2.4}/mpytool/mpy_comm.py

@@ -174,7 +174,8 @@ class MpyComm():
 
         Arguments:
             command: command to execute
-            timeout: maximum waiting time for result
+            timeout: maximum waiting time for result,
+                0 = submit only (send code, don't wait for output)
 
         Returns:
             command STDOUT result
@@ -182,12 +183,16 @@ class MpyComm():
         Raises:
             CmdError when command return error
         """
+        send_timeout = 5 if timeout == 0 else timeout
         self.enter_raw_repl()
         if self._log:
             self._log.info("CMD: %s", command)
         self._conn.write(bytes(command, 'utf-8'))
         self._conn.write(CTRL_D)
-        self._conn.read_until(b'OK', timeout)
+        self._conn.read_until(b'OK', send_timeout)
+        if timeout == 0:
+            self._repl_mode = False
+            return b''
         result = self._conn.read_until(CTRL_D, timeout)
         if result:
             if self._log:
@@ -209,7 +214,8 @@ class MpyComm():
 
         Arguments:
             command: command to execute (str or bytes)
-            timeout: maximum waiting time for result
+            timeout: maximum waiting time for result,
+                0 = submit only (send code, don't wait for output)
 
         Returns:
             command STDOUT result
@@ -218,6 +224,7 @@ class MpyComm():
             CmdError when command returns error
             MpyError when raw-paste mode is not supported
         """
+        send_timeout = 5 if timeout == 0 else timeout
         self.enter_raw_repl()
 
         if isinstance(command, str):
@@ -229,7 +236,7 @@ class MpyComm():
         self._conn.write(RAW_PASTE_ENTER)
 
         # Read response: 'R' + status (0=not supported, 1=supported)
-        header, status = self._conn.read_bytes(2, timeout)
+        header, status = self._conn.read_bytes(2, send_timeout)
         if header != ord('R'):
             raise MpyError(f"Unexpected raw-paste header: {header!r}")
 
@@ -243,7 +250,7 @@ class MpyComm():
         self._raw_paste_supported = True
 
         # Read window size (16-bit little-endian)
-        window_bytes = self._conn.read_bytes(2, timeout)
+        window_bytes = self._conn.read_bytes(2, send_timeout)
         window_size = int.from_bytes(window_bytes, 'little')
         if self._log:
             self._log.info("Raw-paste window size: %d", window_size)
@@ -255,7 +262,7 @@ class MpyComm():
         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)
+                flow_byte = self._conn.read_bytes(1, send_timeout)
                 if flow_byte == RAW_PASTE_ACK:
                     remaining_window += window_size
                 elif flow_byte == CTRL_D:
@@ -274,10 +281,14 @@ class MpyComm():
 
         # Consume remaining ACKs and wait for CTRL_D echo
         while True:
-            byte = self._conn.read_bytes(1, timeout)
+            byte = self._conn.read_bytes(1, send_timeout)
             if byte == CTRL_D:
                 break
 
+        if timeout == 0:
+            self._repl_mode = False
+            return b''
+
         result = self._conn.read_until(CTRL_D, timeout)
         if result and self._log:
             self._log.info('RES: %s', bytes(result))