mpytool 2.2.4__tar.gz → 2.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.2.4
+Version: 2.3.1
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavel.revak@gmail.com>
 License-Expression: MIT
@@ -20,16 +20,31 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
 
 ## Features
 
-- **Fast file transfers** - optimized chunked transfer with automatic compression
-- **Skip unchanged files** - compares size + SHA256 hash, re-upload in <1s
-- **Auto-detect serial port** - no need to specify `-p` when only one device connected
-- **Robust REPL handling** - works reliably with USB-UART bridges (CP2102, CH340)
-- **Multiple reset options** - soft, MCU, hardware (RTS), bootloader entry
-- **General-purpose serial terminal** - `repl` and `monitor` work with any serial device
+- **Fast file transfers** - optimized chunked transfer with
+  automatic compression
+- **Skip unchanged files** - compares size + SHA256 hash,
+  re-upload in <1s
+- **Auto-detect serial port** - no need to specify `-p` when only
+  one device connected
+- **Robust REPL handling** - works reliably with USB-UART bridges
+  (CP2102, CH340)
+- **Multiple reset options** - soft, MCU, hardware (RTS),
+  bootloader entry
+- **General-purpose serial terminal** - `repl` and `monitor` work
+  with any serial device
+- **Mount local directory** - VFS mount (read-only or read-write)
+  for development without uploading to flash, with transparent
+  `.mpy` compilation and auto-remount after soft reset
+- **Virtual submounts** - `ln` links files/directories into
+  mounted VFS (PC-side only, no device changes)
 - **Python API** - suitable for IDE integration and automation
-- **Raw-paste mode** - flow-controlled code execution with reduced RAM usage (API)
+- **Raw-paste mode** - flow-controlled code execution with reduced
+  RAM usage (API)
 - **Shell completion** - ZSH and Bash with remote path completion
 - **Network support** - connect over TCP
+- **Full Unicode support** - handles Unicode in file names and content
+
+See [README_mpremote.md](README_mpremote.md) for detailed comparison with mpremote.
 
 ## Installation
 
@@ -83,13 +98,34 @@ $ mpytool --help
 
 ### List files
 ```
-$ mpytool -p /dev/ttyACM0 ls         # list CWD (default)
-$ mpytool -p /dev/ttyACM0 ls :/lib   # list /lib
+$ mpytool -p /dev/ttyACM0 ls         # Linux: list CWD (default)
+LS: /
+     215B boot.py
+    3.03K main.py
+          lib/
+
+$ mpytool ls :/lib                   # list /lib (auto-detect port)
+LS: /lib
+          uhttp/
+    23.1K wlan.py
+
+$ mpytool ls :/data                  # Unicode file names supported
+LS: /data
+       64B データ.csv
+       32B 🍅.py
+      128B súbor.txt
+      256B 配置.json
 ```
 
 ### Tree
 ```
-$ mpytool -p /dev/ttyACM0 tree       # tree of CWD (default)
+$ mpytool -p /dev/cu.usbmodem1101 tree    # macOS: tree of CWD
+TREE: /
+     142K ./
+    97.7K ├─ lib/
+    69.6K │  └─ uhttp/
+       23 ├─ boot.py
+    3.03K └─ main.py
 ```
 
 ### Copy files (: prefix = device path)
@@ -139,66 +175,255 @@ $ mpytool mv :/a.py :/b.py :/lib/   # move multiple files to directory
 ### View file contents
 ```
 $ mpytool cat :boot.py            # print file from CWD
+CAT: /boot.py
+import machine
+...
+
 $ mpytool cat :/lib/module.py     # print file with absolute path
+CAT: /lib/module.py
+def hello():
+    print("Hello!")
 ```
 
 ### Make directory, delete files (: prefix = device path)
 ```
 $ mpytool mkdir :lib :data        # create directories in CWD
+MKDIR: /lib
+MKDIR: /data
+
 $ mpytool mkdir :/lib/subdir      # create with absolute path
+MKDIR: /lib/subdir
+
 $ mpytool rm :old.py              # delete file in CWD
+RM: /old.py
+
 $ mpytool rm :mydir               # delete directory and contents
+RM: /mydir
+
 $ mpytool rm :mydir/              # delete contents only, keep directory
-$ mpytool rm :                    # delete everything in CWD
-$ mpytool rm :/                   # delete everything on device (root)
+RM contents: /mydir
 ```
 
 ### Current working directory
 ```
 $ mpytool pwd                     # print current directory
+PWD
 /
+
 $ mpytool cd :/lib                # change to /lib
+CD: /lib
+
 $ mpytool cd :subdir              # change to relative path (from CWD)
-$ mpytool cd :..                  # change to parent directory
+CD: /lib/subdir
+
 $ mpytool cd :/lib -- ls          # change directory and list files
+CD: /lib
+LS: /lib
+          uhttp/
+    23.1K wlan.py
+```
+
+### Module search path (sys.path)
+```
+$ mpytool path                    # show current sys.path
+: :/lib
+
+$ mpytool path : :/lib            # replace entire sys.path
+PATH set to 2 entries
+
+$ mpytool path -f :/custom        # prepend to sys.path (remove duplicates)
+PATH prepended 1 entries
+
+$ mpytool path -a :/sdcard/lib    # append to sys.path (remove duplicates)
+PATH appended 1 entries
+
+$ mpytool path -d :/custom        # delete from sys.path
+PATH removed 1 entries
 ```
 
-### Reset and REPL
+Path semantics: `:` = empty string (CWD) in sys.path, `:/` = root directory. The `-f` and `-a` flags automatically remove duplicates (move existing paths to new position).
+
+### Stop, reset and REPL
 ```
+$ mpytool stop               # stop running program (Ctrl-C)
+STOP
+
 $ mpytool reset              # soft reset (Ctrl-D, runs boot.py/main.py)
-$ mpytool reset --raw        # soft reset in raw REPL (clears RAM only)
+RESET soft
+
 $ mpytool reset --machine    # MCU reset (machine.reset, auto-reconnect)
-$ mpytool reset --machine -t 30  # MCU reset with 30s reconnect timeout
-$ mpytool reset --rts        # hardware reset via RTS signal (serial only)
-$ mpytool reset --boot       # enter bootloader (machine.bootloader)
-$ mpytool reset --dtr-boot   # enter bootloader via DTR/RTS (ESP32 only)
+RESET machine
+
 $ mpytool reset -- monitor   # reset and monitor output
+RESET soft
+MONITOR (Ctrl+C to stop)
+
 $ mpytool repl               # enter REPL mode
+REPL (Ctrl+] to exit)
+
 $ mpytool sleep 2            # sleep for 2 seconds (useful between commands)
+SLEEP 2.0s
 ```
 
 ### Serial terminal and monitor (general purpose)
 ```
 $ mpytool repl                       # auto-detect port, 115200 baud
+REPL (Ctrl+] to exit)
+
+$ mpytool -v repl                    # verbose: shows CWD and sys.path before REPL
+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
 ```
 
+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.
+
 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
 ```
 $ mpytool exec "print('Hello!')"
+EXEC: print('Hello!')
+Hello!
+
 $ mpytool exec "import sys; print(sys.version)"
+EXEC: import sys; print(sys.version)
+3.4.0; MicroPython v1.24.0
 ```
 
 ### Run local Python file on device
 ```
 $ mpytool run script.py                  # run script (fire-and-forget)
+RUN: script.py (128 bytes)
+
 $ mpytool run script.py -- monitor       # run script and capture output
+RUN: script.py (128 bytes)
+MONITOR (Ctrl+C to stop)
+Hello from script!
 ```
 
+### Edit file on device
+```
+$ mpytool edit :boot.py              # edit file (uses $VISUAL or $EDITOR)
+EDIT: /boot.py
+
+$ mpytool edit :/lib/config.py       # absolute path
+EDIT: /lib/config.py
+
+$ mpytool edit :newfile.py           # create new file if doesn't exist
+EDIT: /newfile.py (new file)
+```
+
+Downloads file to a temp file, opens in editor, uploads back if changed.
+Editor priority: `--editor` > `$VISUAL` > `$EDITOR` > error.
+
+### Device RTC (real-time clock)
+```
+$ mpytool rtc                        # display current RTC
+RTC
+2026-02-21 15:30:45
+
+$ mpytool rtc --set                  # set RTC to local PC time
+RTC set to 2026-02-21 15:30:45 (local)
+
+$ mpytool rtc --utc                  # set RTC to UTC time
+RTC set to 2026-02-21 14:30:45 (UTC)
+
+$ mpytool rtc "2026-02-21 14:30:00"  # set RTC to specific datetime
+RTC set to 2026-02-21 14:30:00
+```
+
+Flags: `-s`/`--set` and `-l`/`--local` both set local time, `-u`/`--utc` sets UTC.
+Manual datetime format: `YYYY-MM-DD HH:MM:SS`.
+
+### Mount local directory on device
+```
+$ mpytool mount ./src                       # mount ./src as /remote, auto-start REPL
+Mounted ./src on /remote (readonly)
+Changed CWD to /remote
+REPL (Ctrl+] to exit)
+
+$ mpytool -v mount ./src :/app              # mount as /app instead of /remote (verbose)
+Mounted ./src on /app (readonly)
+Changed CWD to /app
+REPL (Ctrl+] to exit)  CWD: /app  PATH: : :.frozen :/lib
+
+$ mpytool mount -m ./src :/app              # mount with automatic .mpy compilation
+Mounted ./src on /app (readonly, .mpy compilation)
+Changed CWD to /app
+>>> import foo                              # imports /app/foo.mpy (compiled from ./src/foo.py)
+
+$ mpytool mount -w ./workspace :/work       # mount as read-write (can create/modify/delete files)
+Mounted ./workspace on /work (read-write)
+Changed CWD to /work
+>>> f = open('/work/test.txt', 'w'); f.write('hello'); f.close()  # creates local file
+>>> import os; os.mkdir('/work/newdir')     # creates local directory
+
+$ mpytool mount ./src -- exec "import main" # mount and run code
+$ mpytool mount ./src -- monitor            # mount and monitor output
+$ mpytool mount ./app :/app -- mount ./lib :/lib -- repl  # multiple mounts (CWD = /app)
+Mounted ./app on /app (readonly)
+Changed CWD to /app
+Mounted ./lib on /lib (readonly)
+```
+
+Mounts a local directory on the device as a VFS. The device can read,
+import and execute files from the local directory without uploading
+them to flash. Changes to local files are immediately visible on
+the device.
+
+**Memory overhead:** The VFS agent uses ~4.2KB of RAM on the device
+(154 lines of MicroPython code injected during mount).
+
+**By default, mounts are read-only.** Use `-w` / `--writable` flag
+to enable write support — the device can create, modify and delete
+files in the mounted directory. All changes are written directly to
+the local filesystem.
+
+**`-m` / `--mpy` flag:** Enables transparent `.mpy` compilation.
+When the device imports a module, the `.py` file is automatically
+compiled to `.mpy` bytecode on-demand and served from cache
+(`__pycache__/`). Benefits: faster imports, less RAM usage, support
+for `@native`/`@viper` code with `-march`. Boot files (`boot.py`,
+`main.py`) and empty files remain as `.py`. If compilation fails,
+automatically falls back to `.py`. Prebuilt `.mpy` files have
+priority over cache.
+
+The first mount automatically changes CWD to the mount point (mpremote
+compatibility). Subsequent mounts do not change CWD. Use `cd` command
+to change working directory manually if needed. Multiple independent
+(non-nested) mounts are supported.
+
+After mount, mpytool automatically enters REPL (unless `monitor` or
+`repl` follows). In REPL you can import modules from the mounted
+directory, Ctrl+D triggers soft reset with automatic re-mount and CWD
+restoration to the mount point.
+
+**Best for:** Development, testing, prototyping, debugging. For bulk
+file transfers (uploading/downloading many files), use `cp` command
+instead — it's optimized for throughput.
+
+**Security:** Paths are validated to prevent traversal outside mount
+root. Symlinks are followed and checked. Write operations require
+explicit `-w` flag.
+
+See [Mount VFS Comparison](README_mpremote.md#mount-vfs-comparison) for detailed comparison with mpremote.
+
+### Link files into mounted VFS
+```
+$ mpytool mount ./app :/ -- ln ./drivers :/lib/ -- repl       # mount app, link drivers into /lib/
+$ mpytool mount ./app :/ -- ln ./extra.py :/lib/ -- repl      # link single file into /lib/
+$ mpytool mount ./app :/ -- ln ./pkg :/lib/pkg -- repl        # link as specific name
+$ mpytool mount ./app :/ -- ln ./pkg/ :/lib/ -- repl          # link package contents into /lib/
+$ mpytool mount ./app :/ -- ln ./a.py ./b.py :/lib/ -- repl   # link multiple sources
+```
+
+Links local files or directories into an already mounted VFS as virtual submounts. Works entirely on the PC side — no changes needed on the device. Useful for composing a virtual filesystem from multiple local directories without copying.
+
+Path semantics follow the same trailing `/` rules as `cp`: `ln dir :/lib/` creates `:/lib/dir/...`, `ln dir/ :/lib/` copies contents into `:/lib/...`. Destination must be an absolute device path with `:` prefix.
+
 ### Serial link speed test
 ```
 $ mpytool speedtest
@@ -214,7 +439,8 @@ SPEEDTEST
 
 ### Show device information
 ```
-$ mpytool info
+$ mpytool -p COM3 info               # Windows
+INFO
 Platform:    rp2
 Version:     3.4.0; MicroPython v1.27.0 on 2025-12-09
 Impl:        micropython
@@ -258,9 +484,9 @@ $ mpytool flash erase vfs --full           # full erase partition
 
 ### 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
+$ mpytool flash ota firmware.app-bin                    # flash to next OTA partition
+$ mpytool flash ota firmware.app-bin -- reset --machine          # flash and reboot
+$ mpytool flash ota firmware.app-bin -- reset --machine -t 30    # flash and reboot with 30s timeout
 ```
 
 ### Multiple commands separated by `--`
@@ -271,28 +497,30 @@ $ mpytool rm :old.py -- cp new.py : -- reset
 
 ### Auto-detect serial port (if only one device is connected)
 ```
-$ mpytool ls lib/
+$ mpytool ls :/lib
+LS: /lib
           uhttp/
-  23.2 KB wlan.py
-  4.95 KB wlan_http.py
+    23.1K wlan.py
+    4.95K wlan_http.py
 ```
 
 ### Tree view
 ```
 $ mpytool tree
-   142 KB ./
-  41.3 KB ├─ html/
-    587 B │  ├─ index.html
-  40.8 KB │  └─ wlan.html
-  97.7 KB ├─ lib/
-  69.6 KB │  ├─ uhttp/
-     93 B │  │  ├─ __init__.py
-  26.3 KB │  │  ├─ client.py
-  43.2 KB │  │  └─ server.py
-  23.2 KB │  ├─ wlan.py
-  4.95 KB │  └─ wlan_http.py
-     23 B ├─ boot.py
-  3.03 KB └─ main.py
+TREE: /
+     142K ./
+    41.3K ├─ html/
+      587 │  ├─ index.html
+    40.8K │  └─ wlan.html
+    97.7K ├─ lib/
+    69.6K │  ├─ uhttp/
+       93 │  │  ├─ __init__.py
+    26.3K │  │  ├─ client.py
+    43.2K │  │  └─ server.py
+    23.1K │  ├─ wlan.py
+    4.95K │  └─ wlan_http.py
+       23 ├─ boot.py
+    3.03K └─ main.py
 ```
 
 ### Connect over network (TCP, default port 23)
@@ -388,7 +616,7 @@ For reporting bugs, please include `-ddd` output in the issue.
 
 ## Performance
 
-`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_BENCH.md](README_BENCH.md) for detailed benchmarks.
+`mpytool` uses optimized chunked transfer with automatic compression, which allows copying files very quickly. See [README_bench.md](README_bench.md) for detailed benchmarks.
 
 ### Summary