mpytool 1.2.0__tar.gz → 2.0.0__tar.gz

mpytool-2.0.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: mpytool
+Version: 2.0.0
+Summary: MPY tool - manage files on devices running MicroPython
+Author-email: Pavel Revak <pavel.revak@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pavelrevak/mpytool
+Keywords: MPY,micropython
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.0
+Dynamic: license-file
+
+# mpytool
+
+MPY tool - manage files on devices running MicroPython
+
+It is an alternative to [ampy](https://github.com/scientifichackers/ampy)
+
+Target of this project is to make more clean code, faster, better verbose output...
+
+## Installation
+
+```
+pip3 install mpytool
+```
+
+## Examples:
+
+help:
+```
+$ mpytool --help
+```
+
+list files:
+```
+$ mpytool -p /dev/ttyACM0 ls
+$ mpytool -p /dev/ttyACM0 ls lib
+```
+
+tree files:
+```
+$ mpytool -p /dev/ttyACM0 tree
+```
+
+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
+$ mpytool cp myapp/ :/              # upload directory (creates /myapp/)
+$ mpytool cp myapp/ :/lib/          # upload directory into /lib/
+$ 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
+```
+
+Unchanged files are automatically skipped (compares size and SHA256 hash).
+Use `-f` or `--force` to upload all files regardless.
+
+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
+```
+
+legacy upload/download (still available):
+```
+$ mpytool put boot.py /
+$ mpytool get boot.py >> boot.py
+```
+
+make directory, delete files:
+```
+$ mpytool mkdir a/b/c/d xyz/abc   # create directories
+$ mpytool rm mydir                # delete directory and contents
+$ mpytool rm mydir/               # delete contents only, keep directory
+$ mpytool rm /                    # delete everything on device
+```
+
+reset only, reset and follow output, REPL mode:
+```
+$ mpytool -p /dev/ttyACM0 reset
+$ mpytool -p /dev/ttyACM0 reset follow
+$ mpytool -p /dev/ttyACM0 repl
+```
+
+execute Python code on device:
+```
+$ mpytool exec "print('Hello!')"
+$ mpytool exec "import sys; print(sys.version)"
+```
+
+show device information:
+```
+$ mpytool info
+Platform:    rp2
+Version:     3.4.0; MicroPython v1.27.0 on 2025-12-09
+Impl:        micropython
+Machine:     Raspberry Pi Pico with RP2040
+Memory:      36.4 KB / 240 KB (15.15%)
+Flash:       120 KB / 1.38 MB (8.52%)
+```
+
+multiple commands separated by `--`:
+```
+$ mpytool -p /dev/ttyACM0 put main.py / -- reset -- follow
+$ mpytool -p /dev/ttyACM0 delete old.py -- put new.py / -- reset
+```
+
+auto-detect serial port (if only one device is connected):
+```
+$ mpytool ls
+Using /dev/ttyACM0
+       215 boot.py
+      2938 net.py
+```
+
+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):
+```
+$ mpytool -p /dev/ttyACM0 -b 9600 ls
+```
+
+show version:
+```
+$ mpytool -V
+```
+
+command aliases:
+- `dir` = `ls`
+- `cat` = `get`
+- `del`, `rm` = `delete`
+
+## Examples using API from Python
+
+```
+>>> import mpytool
+>>> conn = mpytool.ConnSerial(port='/dev/ttyACM0', baudrate=115200)
+>>> mpy = mpytool.Mpy(conn)
+>>> mpy.ls()
+[('ehome', None), ('boot.py', 215), ('net.py', 2938), ('project.json', 6404)]
+>>> mpy.mkdir('a/b/c')
+>>> mpy.ls()
+[('a', None),
+ ('ehome', None),
+ ('boot.py', 215),
+ ('net.py', 2938),
+ ('project.json', 6404)]
+>>> mpy.get('boot.py')
+b"import time\nimport net\n\nwlan = net.Wlan()\nwlan.refresh_network()\n\nwhile wlan.ifconfig()[0] == '0.0.0.0':\n    time.sleep(.1)\n\nprint('IP: ' + wlan.ifconfig()[0])\n\nimport ehome.ehome\n\nehome.ehome.start('project.json')\n"
+>>> mpy.delete('a/b')
+```
+
+## Progress and verbose output
+
+Progress is shown by default during file transfers:
+```
+$ mpytool cp main.py lib.py :/lib/
+[1/2] 100%   1.2KB main.py -> :/lib/main.py
+[2/2] 100%   3.4KB lib.py  -> :/lib/lib.py
+```
+
+use `-v` or `--verbose` to also show commands being executed:
+```
+$ mpytool -v rm /old.py
+delete: /old.py
+```
+
+use `-q` or `--quiet` to disable all output:
+```
+$ mpytool -q cp main.py :/
+```
+
+## Debug output
+
+- `-d` print warnings (yellow)
+- `-dd` print info messages (purple)
+- `-ddd` print debug messages (blue)
+
+for reporting bugs, please provide in to issue also -ddd messages
+
+## MPYTOOL vs other tools
+
+Benchmark on RP2040 (Raspberry Pi Pico) over native USB, January 2025:
+
+| Test | mpytool | mpremote |
+|------|---------|----------|
+| 50 small files, 5 dirs (200KB) | **4.2s** | 9.4s |
+| 5 large files (260KB) | **8.0s** | 17.3s |
+| re-upload unchanged files | **1.3s** | 5.0s |
+
+mpytool is **2x faster** for uploads and **4x faster** for re-uploads (skips unchanged files).
+
+mpytool advantages:
+- Fastest file transfers (2x faster than mpremote)
+- Skip unchanged files (compares size + SHA256 hash)
+- Progress indicator with file counts (`[3/10] 50% file.py -> :/lib/`)
+- Single tool for all operations (no need to chain commands)
+- Clean verbose output (`-v`) for debugging
+
+## Requirements
+
+Working only with MicroPython boards, not with CircuitPython
+
+- python v3.10+
+- pyserial v3.0+
+
+### Running on:
+
+- Linux
+- MacOS
+- Windows (limited support - REPL mode is disabled)
+
+## Credits
+
+(c) 2022 by Pavel Revak
+
+### License
+
+MIT
+
+### Support
+
+- Basic support is free over GitHub issues.
+- Professional support is available over email: [Pavel Revak](mailto:pavel.revak@gmail.com?subject=[GitHub]%20mpytool).

mpytool-2.0.0/README.md

@@ -0,0 +1,219 @@
+# mpytool
+
+MPY tool - manage files on devices running MicroPython
+
+It is an alternative to [ampy](https://github.com/scientifichackers/ampy)
+
+Target of this project is to make more clean code, faster, better verbose output...
+
+## Installation
+
+```
+pip3 install mpytool
+```
+
+## Examples:
+
+help:
+```
+$ mpytool --help
+```
+
+list files:
+```
+$ mpytool -p /dev/ttyACM0 ls
+$ mpytool -p /dev/ttyACM0 ls lib
+```
+
+tree files:
+```
+$ mpytool -p /dev/ttyACM0 tree
+```
+
+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
+$ mpytool cp myapp/ :/              # upload directory (creates /myapp/)
+$ mpytool cp myapp/ :/lib/          # upload directory into /lib/
+$ 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
+```
+
+Unchanged files are automatically skipped (compares size and SHA256 hash).
+Use `-f` or `--force` to upload all files regardless.
+
+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
+```
+
+legacy upload/download (still available):
+```
+$ mpytool put boot.py /
+$ mpytool get boot.py >> boot.py
+```
+
+make directory, delete files:
+```
+$ mpytool mkdir a/b/c/d xyz/abc   # create directories
+$ mpytool rm mydir                # delete directory and contents
+$ mpytool rm mydir/               # delete contents only, keep directory
+$ mpytool rm /                    # delete everything on device
+```
+
+reset only, reset and follow output, REPL mode:
+```
+$ mpytool -p /dev/ttyACM0 reset
+$ mpytool -p /dev/ttyACM0 reset follow
+$ mpytool -p /dev/ttyACM0 repl
+```
+
+execute Python code on device:
+```
+$ mpytool exec "print('Hello!')"
+$ mpytool exec "import sys; print(sys.version)"
+```
+
+show device information:
+```
+$ mpytool info
+Platform:    rp2
+Version:     3.4.0; MicroPython v1.27.0 on 2025-12-09
+Impl:        micropython
+Machine:     Raspberry Pi Pico with RP2040
+Memory:      36.4 KB / 240 KB (15.15%)
+Flash:       120 KB / 1.38 MB (8.52%)
+```
+
+multiple commands separated by `--`:
+```
+$ mpytool -p /dev/ttyACM0 put main.py / -- reset -- follow
+$ mpytool -p /dev/ttyACM0 delete old.py -- put new.py / -- reset
+```
+
+auto-detect serial port (if only one device is connected):
+```
+$ mpytool ls
+Using /dev/ttyACM0
+       215 boot.py
+      2938 net.py
+```
+
+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):
+```
+$ mpytool -p /dev/ttyACM0 -b 9600 ls
+```
+
+show version:
+```
+$ mpytool -V
+```
+
+command aliases:
+- `dir` = `ls`
+- `cat` = `get`
+- `del`, `rm` = `delete`
+
+## Examples using API from Python
+
+```
+>>> import mpytool
+>>> conn = mpytool.ConnSerial(port='/dev/ttyACM0', baudrate=115200)
+>>> mpy = mpytool.Mpy(conn)
+>>> mpy.ls()
+[('ehome', None), ('boot.py', 215), ('net.py', 2938), ('project.json', 6404)]
+>>> mpy.mkdir('a/b/c')
+>>> mpy.ls()
+[('a', None),
+ ('ehome', None),
+ ('boot.py', 215),
+ ('net.py', 2938),
+ ('project.json', 6404)]
+>>> mpy.get('boot.py')
+b"import time\nimport net\n\nwlan = net.Wlan()\nwlan.refresh_network()\n\nwhile wlan.ifconfig()[0] == '0.0.0.0':\n    time.sleep(.1)\n\nprint('IP: ' + wlan.ifconfig()[0])\n\nimport ehome.ehome\n\nehome.ehome.start('project.json')\n"
+>>> mpy.delete('a/b')
+```
+
+## Progress and verbose output
+
+Progress is shown by default during file transfers:
+```
+$ mpytool cp main.py lib.py :/lib/
+[1/2] 100%   1.2KB main.py -> :/lib/main.py
+[2/2] 100%   3.4KB lib.py  -> :/lib/lib.py
+```
+
+use `-v` or `--verbose` to also show commands being executed:
+```
+$ mpytool -v rm /old.py
+delete: /old.py
+```
+
+use `-q` or `--quiet` to disable all output:
+```
+$ mpytool -q cp main.py :/
+```
+
+## Debug output
+
+- `-d` print warnings (yellow)
+- `-dd` print info messages (purple)
+- `-ddd` print debug messages (blue)
+
+for reporting bugs, please provide in to issue also -ddd messages
+
+## MPYTOOL vs other tools
+
+Benchmark on RP2040 (Raspberry Pi Pico) over native USB, January 2025:
+
+| Test | mpytool | mpremote |
+|------|---------|----------|
+| 50 small files, 5 dirs (200KB) | **4.2s** | 9.4s |
+| 5 large files (260KB) | **8.0s** | 17.3s |
+| re-upload unchanged files | **1.3s** | 5.0s |
+
+mpytool is **2x faster** for uploads and **4x faster** for re-uploads (skips unchanged files).
+
+mpytool advantages:
+- Fastest file transfers (2x faster than mpremote)
+- Skip unchanged files (compares size + SHA256 hash)
+- Progress indicator with file counts (`[3/10] 50% file.py -> :/lib/`)
+- Single tool for all operations (no need to chain commands)
+- Clean verbose output (`-v`) for debugging
+
+## Requirements
+
+Working only with MicroPython boards, not with CircuitPython
+
+- python v3.10+
+- pyserial v3.0+
+
+### Running on:
+
+- Linux
+- MacOS
+- Windows (limited support - REPL mode is disabled)
+
+## Credits
+
+(c) 2022 by Pavel Revak
+
+### License
+
+MIT
+
+### Support
+
+- Basic support is free over GitHub issues.
+- Professional support is available over email: [Pavel Revak](mailto:pavel.revak@gmail.com?subject=[GitHub]%20mpytool).

{mpytool-1.2.0 → mpytool-2.0.0}/mpytool/__init__.py

@@ -2,5 +2,7 @@
 
 from mpytool.conn import ConnError, Timeout
 from mpytool.conn_serial import ConnSerial
+from mpytool.conn_socket import ConnSocket
 from mpytool.mpy_comm import MpyError, CmdError
 from mpytool.mpy import Mpy
+from mpytool.logger import SimpleColorLogger

mpytool-2.0.0/mpytool/conn.py

@@ -0,0 +1,100 @@
+"""MicroPython tool: abstract connector"""
+
+import time as _time
+import select as _select
+
+
+class ConnError(Exception):
+    """General connection error"""
+
+
+class Timeout(ConnError):
+    """Timeout"""
+
+
+class Conn():
+    def __init__(self, log=None):
+        self._log = log
+        self._buffer = bytearray(b'')
+
+    @property
+    def fd(self):
+        """Return file descriptor for select()"""
+        return None
+
+    def _has_data(self, timeout=0):
+        """Check if data is available to read using select()"""
+        fd = self.fd
+        if fd is None:
+            return False
+        readable, _, _ = _select.select([fd], [], [], timeout)
+        return bool(readable)
+
+    def _read_available(self):
+        """Read available data from device (must be implemented by subclass)"""
+        raise NotImplementedError
+
+    def _write_raw(self, data):
+        """Write data to device, return bytes written (must be implemented by subclass)"""
+        raise NotImplementedError
+
+    def _read_to_buffer(self, wait_timeout=0):
+        """Read available data into buffer
+
+        Arguments:
+            wait_timeout: how long to wait for data (0 = non-blocking)
+        """
+        if self._has_data(wait_timeout):
+            data = self._read_available()
+            if data:
+                self._buffer += data
+                return True
+        return False
+
+    def flush(self):
+        """Flush and return buffer contents"""
+        buffer = bytes(self._buffer)
+        del self._buffer[:]
+        return buffer
+
+    def read(self):
+        """Read available data from device"""
+        if self._has_data():
+            return self._read_available()
+        return None
+
+    def write(self, data):
+        """Write data to device"""
+        if self._log:
+            self._log.debug("wr: %s", bytes(data))
+        while data:
+            count = self._write_raw(data)
+            data = data[count:]
+
+    def read_until(self, end, timeout=1):
+        """Read until end marker is found"""
+        if self._log:
+            self._log.debug("wait for %s", end)
+        start_time = _time.time()
+        while True:
+            # Use select() with 1ms timeout instead of sleep - wakes immediately on data
+            if self._read_to_buffer(wait_timeout=0.001):
+                start_time = _time.time()  # reset timeout on data received
+            if end in self._buffer:
+                break
+            if timeout is not None and start_time + timeout < _time.time():
+                if self._buffer:
+                    raise Timeout(
+                        f"During timeout received: {bytes(self._buffer)}")
+                raise Timeout("No data received")
+        index = self._buffer.index(end)
+        data = self._buffer[:index]
+        del self._buffer[:index + len(end)]
+        if self._log:
+            self._log.debug("rd: %s", bytes(data + end))
+        return data
+
+    def read_line(self, timeout=None):
+        """Read single line"""
+        line = self.read_until(b'\n', timeout)
+        return line.strip(b'\r')

mpytool-2.0.0/mpytool/conn_serial.py

@@ -0,0 +1,34 @@
+"""MicroPython tool: serial connector"""
+
+import serial as _serial
+import mpytool.conn as _conn
+
+
+class ConnSerial(_conn.Conn):
+    def __init__(self, log=None, **serial_config):
+        super().__init__(log)
+        try:
+            self._serial = _serial.Serial(**serial_config)
+        except _serial.serialutil.SerialException as err:
+            self._serial = None
+            raise _conn.ConnError(
+                f"Error opening serial port {serial_config['port']}") from err
+
+    def __del__(self):
+        if self._serial:
+            self._serial.close()
+
+    @property
+    def fd(self):
+        return self._serial.fd if self._serial else None
+
+    def _read_available(self):
+        """Read available data from serial port"""
+        in_waiting = self._serial.in_waiting
+        if in_waiting > 0:
+            return self._serial.read(in_waiting)
+        return None
+
+    def _write_raw(self, data):
+        """Write data to serial port"""
+        return self._serial.write(data)

mpytool-2.0.0/mpytool/conn_socket.py

@@ -0,0 +1,53 @@
+"""MicroPython tool: socket connector"""
+
+import socket as _socket
+import mpytool.conn as _conn
+
+
+class ConnSocket(_conn.Conn):
+    def __init__(self, address, log=None):
+        super().__init__(log)
+        self._socket = None
+        sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
+        sock.settimeout(5)
+        if ':' in address:
+            host, port = address.split(':')
+            port = int(port)
+        else:
+            host = address
+            port = 23
+        if log:
+            log.info(f"Connecting to: {host}:{port}")
+        try:
+            sock.connect((host, port))
+        except _socket.timeout as err:
+            raise _conn.ConnError(f"Timeout connecting to {host}:{port}") from err
+        except _socket.error as err:
+            raise _conn.ConnError(f"Cannot connect to {host}:{port}: {err}") from err
+        sock.settimeout(None)
+        sock.setblocking(False)
+        self._socket = sock
+        if log:
+            log.info("connected")
+
+    def __del__(self):
+        if self._socket:
+            self._socket.close()
+
+    @property
+    def fd(self):
+        return self._socket.fileno() if self._socket else None
+
+    def _read_available(self):
+        """Read available data from socket"""
+        try:
+            data = self._socket.recv(4096)
+            if data:
+                return data
+        except BlockingIOError:
+            pass
+        return None
+
+    def _write_raw(self, data):
+        """Write data to socket"""
+        return self._socket.send(data)