mpytool 2.4.0__tar.gz → 2.6.0__tar.gz

{mpytool-2.4.0 → mpytool-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mpytool
-Version: 2.4.0
+Version: 2.6.0
 Summary: MPY tool - manage files on devices running MicroPython
 Author-email: Pavel Revak <pavelrevak@gmail.com>
 License-Expression: MIT
@@ -33,6 +33,9 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
   bootloader entry
 - **Wipe device** - erase the whole filesystem and machine-reset
   for a clean slate (handy at the start of automated tests)
+- **Deploy projects** - `sync` uploads a whole project to the device
+  using a `.mpyproject` config file (deploy map, excludes, `.mpy`
+  compilation)
 - **General-purpose serial terminal** - `repl` and `monitor` work
   with any serial device
 - **Mount local directory** - VFS mount (read-only or read-write)
@@ -168,6 +171,47 @@ Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version dif
 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.
 
+### Deploy project (sync)
+
+`sync` uploads a whole project to the device based on a `.mpyproject`
+configuration file. It is the command-line counterpart of the deploy feature in
+the [Sublime Text plugin](https://github.com/cortexm/mpytool-sublime) and shares
+the same `.mpyproject` format. Unlike the plugin it is non-interactive: when more
+than one device is connected, pass `-p` to pick the port.
+
+```
+$ mpytool sync                  # deploy project in CWD (.mpyproject searched upward)
+$ mpytool sync ~/projects/blink # deploy a project in another directory
+$ mpytool -p /dev/ttyACM0 sync  # pick port explicitly (multiple devices)
+$ mpytool sync -- reset -- monitor   # deploy, then reset and watch output
+```
+
+The `.mpyproject` file (JSON, trailing commas tolerated) describes what to upload:
+
+```json
+{
+    "name": "blink",
+    "compile": true,
+    "deploy": {
+        "": ["./"],
+        "/lib/": ["../shared/utils.py"],
+        "/main.py": "src/main_dev.py"
+    },
+    "exclude": ["*.bak", "tests"]
+}
+```
+
+- `deploy` maps a device destination to its source(s), relative to the project
+  root. A key of `""` or one ending in `/` is a **directory** (value is a list of
+  sources); any other key is a **rename** (value is a single source file).
+  Defaults to `{"": ["./"]}` (whole project to root) when omitted.
+- `compile: true` compiles `.py` to `.mpy` (same as `cp -m`).
+- `exclude` adds ignore patterns on top of the defaults (`__pycache__`, `*.pyc`,
+  dotfiles). Combined with global `-e` patterns.
+
+The connection fields (`port`, `address`) used by the Sublime plugin are ignored
+by the CLI — use the global `-p` / `-a` options instead.
+
 ### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
@@ -342,6 +386,35 @@ RUN: script.py (128 bytes)
 Done!
 ```
 
+The script can also come from **STDIN** using the `-` convention (or simply by
+piping when no file is given), which is handy for generated code or one-off
+snippets:
+```
+$ cat script.py | mpytool run -          # explicit '-' = read STDIN
+$ mpytool run - <<< 'print("hi")'        # here-string (single line)
+$ my_codegen | mpytool run               # piped, no file argument
+$ cat boot.py | mpytool run - -- reset -- monitor   # run from STDIN, then chain
+```
+
+For **multi-line** code, feed a here-document straight into `run -` (no `cat`,
+no pipe needed - the here-doc *is* the standard input):
+```
+$ mpytool run - << 'EOF'
+import machine, time
+led = machine.Pin('LED', machine.Pin.OUT)
+for _ in range(3):
+    led.toggle()
+    time.sleep(0.2)
+print('done')
+EOF
+```
+Quote the delimiter (`'EOF'`) so the shell does not expand `$`, backticks or
+`{}` inside the Python code. The closing `EOF` must be on a line of its own.
+
+Because STDIN can be read only once, at most one command per invocation may
+consume it: combining a STDIN `run` with another STDIN `run` or with `repl`
+(which needs the terminal) is rejected up front with a clear error.
+
 ### Edit file on device
 ```
 $ mpytool edit :boot.py              # edit file (uses $VISUAL or $EDITOR)
@@ -484,10 +557,25 @@ Version:     3.4.0; MicroPython v1.27.0 on 2025-12-09
 Impl:        micropython
 Machine:     Raspberry Pi Pico with RP2040
 Serial:      e660123456789abc
-Memory:      36.4 KB / 240 KB (15.15%)
+GC heap:     36.4 KB / 240 KB (15.15%)
 Flash:       120 KB / 1.38 MB (8.52%)
 ```
 
+On ESP32 the physical memory regions are listed too (from the ESP-IDF
+allocator), which stays stable regardless of what the GC heap is doing:
+
+```
+SRAM:        412 KB / 640 KB (64.38%)
+PSRAM:       12.0 MB / 32.0 MB (37.50%)
+GC heap:     209 KB / 20.0 MB (1.02%)
+```
+
+`GC heap` is the heap MicroPython uses for Python objects - **not** the amount
+of RAM in the chip. On builds with PSRAM it grows and shrinks on demand, so its
+total changes over time: right after a reset it can claim nearly all free PSRAM,
+and it shrinks once drivers allocate PSRAM outside the GC heap (e.g. camera
+framebuffers). Use the `SRAM` / `PSRAM` lines to judge actual memory pressure.
+
 On devices with WiFi or Ethernet, MAC addresses are also shown:
 ```
 MAC WiFi:    aa:bb:cc:dd:ee:01
@@ -504,15 +592,18 @@ $ mpytool flash erase                 # quick erase (reset filesystem)
 $ mpytool flash erase --full          # full erase
 
 # ESP32 - partitions (by label)
-$ mpytool flash                       # list all partitions with filesystem info
-Label        Type     Subtype       Address       Size    Block Actual FS     Flags
-------------------------------------------------------------------------------------------
-factory      app      factory       0x10000      1.94M                        running
-nvs          data     nvs            0x9000      24.0K
-vfs          data     littlefs     0x200000      2.00M     4 KB littlefs2
-
-Boot partition: factory
-Next OTA:       (none)
+$ mpytool flash                       # list all partitions, sorted by address
+Label        Type     Subtype       Address       Size    Block Content        Flags
+--------------------------------------------------------------------------------------------
+nvs          data     nvs            0x9000      16.0K
+otadata      data     ota            0xd000      8.00K
+phy_init     data     phy            0xf000      4.00K
+ota_0        app      ota_0         0x10000      2.50M          app ESP32-P4   running, ota:valid
+ota_1        app      ota_1        0x290000      2.50M          app ESP32-P4   ota:valid
+vfs          data     fat          0x510000      10.9M    4.00K littlefs2
+
+Boot partition: ota_0
+Next OTA:       ota_1
 
 $ mpytool flash read vfs backup.bin        # backup partition to file
 $ mpytool flash write nvs nvs_backup.bin   # restore partition from file
@@ -520,11 +611,39 @@ $ mpytool flash erase vfs                  # quick erase partition
 $ mpytool flash erase vfs --full           # full erase partition
 ```
 
+`Content` shows what a partition actually holds - the detected filesystem for
+data partitions, the image type for app partitions (`app <CHIP>`, or
+`BOOTLOADER!` / `INVALID!` / `empty`). The `ota:` flags come from the `otadata`
+partition and describe the **rollback bookkeeping** of a slot, not the image
+stored in it: a slot can read `ota:valid` while holding an unbootable image.
+
 ### OTA firmware update (ESP32)
+
+OTA needs an **app-only** image (`micropython.bin`), not the combined
+`firmware.bin` (bootloader + partition table + app) that `esptool` writes.
+mpytool checks the image header before uploading, so a wrong file is rejected
+immediately instead of failing with `ESP_ERR_OTA_VALIDATE_FAILED` after the
+whole transfer. It also refuses an image built for a different chip.
+
+```
+$ mpytool flash ota micropython.bin                     # write to next OTA partition
+$ mpytool flash ota micropython.bin -- reset --machine  # write and reboot
+$ mpytool flash ota micropython.bin -- reset --machine -t 30   # ... with 30s timeout
+$ mpytool flash ota micropython.bin --force             # write despite failed validation
+
+$ mpytool flash ota confirm            # mark running app valid (cancel rollback)
+$ mpytool flash ota boot               # boot the other slot (manual rollback)
+$ mpytool flash ota boot ota_1         # boot a specific app partition
+```
+
+If the firmware enables rollback, a freshly booted OTA image stays in
+`pending-verify` and reverts on the next reset until it is confirmed - either by
+the app itself (`esp32.Partition(esp32.Partition.RUNNING).mark_app_valid_cancel_rollback()`)
+or from the host:
+
 ```
-$ 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
+$ mpytool flash ota micropython.bin -- reset --machine
+$ mpytool flash ota confirm
 ```
 
 ### Multiple commands separated by `--`

{mpytool-2.4.0 → mpytool-2.6.0}/README.md

@@ -18,6 +18,9 @@ It is an alternative to the official [mpremote](https://docs.micropython.org/en/
   bootloader entry
 - **Wipe device** - erase the whole filesystem and machine-reset
   for a clean slate (handy at the start of automated tests)
+- **Deploy projects** - `sync` uploads a whole project to the device
+  using a `.mpyproject` config file (deploy map, excludes, `.mpy`
+  compilation)
 - **General-purpose serial terminal** - `repl` and `monitor` work
   with any serial device
 - **Mount local directory** - VFS mount (read-only or read-write)
@@ -153,6 +156,47 @@ Requires `mpy-cross` in PATH (`pip install mpy-cross`). If mpy-cross version dif
 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.
 
+### Deploy project (sync)
+
+`sync` uploads a whole project to the device based on a `.mpyproject`
+configuration file. It is the command-line counterpart of the deploy feature in
+the [Sublime Text plugin](https://github.com/cortexm/mpytool-sublime) and shares
+the same `.mpyproject` format. Unlike the plugin it is non-interactive: when more
+than one device is connected, pass `-p` to pick the port.
+
+```
+$ mpytool sync                  # deploy project in CWD (.mpyproject searched upward)
+$ mpytool sync ~/projects/blink # deploy a project in another directory
+$ mpytool -p /dev/ttyACM0 sync  # pick port explicitly (multiple devices)
+$ mpytool sync -- reset -- monitor   # deploy, then reset and watch output
+```
+
+The `.mpyproject` file (JSON, trailing commas tolerated) describes what to upload:
+
+```json
+{
+    "name": "blink",
+    "compile": true,
+    "deploy": {
+        "": ["./"],
+        "/lib/": ["../shared/utils.py"],
+        "/main.py": "src/main_dev.py"
+    },
+    "exclude": ["*.bak", "tests"]
+}
+```
+
+- `deploy` maps a device destination to its source(s), relative to the project
+  root. A key of `""` or one ending in `/` is a **directory** (value is a list of
+  sources); any other key is a **rename** (value is a single source file).
+  Defaults to `{"": ["./"]}` (whole project to root) when omitted.
+- `compile: true` compiles `.py` to `.mpy` (same as `cp -m`).
+- `exclude` adds ignore patterns on top of the defaults (`__pycache__`, `*.pyc`,
+  dotfiles). Combined with global `-e` patterns.
+
+The connection fields (`port`, `address`) used by the Sublime plugin are ignored
+by the CLI — use the global `-p` / `-a` options instead.
+
 ### Move/rename on device
 ```
 $ mpytool mv :/old.py :/new.py      # rename file
@@ -327,6 +371,35 @@ RUN: script.py (128 bytes)
 Done!
 ```
 
+The script can also come from **STDIN** using the `-` convention (or simply by
+piping when no file is given), which is handy for generated code or one-off
+snippets:
+```
+$ cat script.py | mpytool run -          # explicit '-' = read STDIN
+$ mpytool run - <<< 'print("hi")'        # here-string (single line)
+$ my_codegen | mpytool run               # piped, no file argument
+$ cat boot.py | mpytool run - -- reset -- monitor   # run from STDIN, then chain
+```
+
+For **multi-line** code, feed a here-document straight into `run -` (no `cat`,
+no pipe needed - the here-doc *is* the standard input):
+```
+$ mpytool run - << 'EOF'
+import machine, time
+led = machine.Pin('LED', machine.Pin.OUT)
+for _ in range(3):
+    led.toggle()
+    time.sleep(0.2)
+print('done')
+EOF
+```
+Quote the delimiter (`'EOF'`) so the shell does not expand `$`, backticks or
+`{}` inside the Python code. The closing `EOF` must be on a line of its own.
+
+Because STDIN can be read only once, at most one command per invocation may
+consume it: combining a STDIN `run` with another STDIN `run` or with `repl`
+(which needs the terminal) is rejected up front with a clear error.
+
 ### Edit file on device
 ```
 $ mpytool edit :boot.py              # edit file (uses $VISUAL or $EDITOR)
@@ -469,10 +542,25 @@ Version:     3.4.0; MicroPython v1.27.0 on 2025-12-09
 Impl:        micropython
 Machine:     Raspberry Pi Pico with RP2040
 Serial:      e660123456789abc
-Memory:      36.4 KB / 240 KB (15.15%)
+GC heap:     36.4 KB / 240 KB (15.15%)
 Flash:       120 KB / 1.38 MB (8.52%)
 ```
 
+On ESP32 the physical memory regions are listed too (from the ESP-IDF
+allocator), which stays stable regardless of what the GC heap is doing:
+
+```
+SRAM:        412 KB / 640 KB (64.38%)
+PSRAM:       12.0 MB / 32.0 MB (37.50%)
+GC heap:     209 KB / 20.0 MB (1.02%)
+```
+
+`GC heap` is the heap MicroPython uses for Python objects - **not** the amount
+of RAM in the chip. On builds with PSRAM it grows and shrinks on demand, so its
+total changes over time: right after a reset it can claim nearly all free PSRAM,
+and it shrinks once drivers allocate PSRAM outside the GC heap (e.g. camera
+framebuffers). Use the `SRAM` / `PSRAM` lines to judge actual memory pressure.
+
 On devices with WiFi or Ethernet, MAC addresses are also shown:
 ```
 MAC WiFi:    aa:bb:cc:dd:ee:01
@@ -489,15 +577,18 @@ $ mpytool flash erase                 # quick erase (reset filesystem)
 $ mpytool flash erase --full          # full erase
 
 # ESP32 - partitions (by label)
-$ mpytool flash                       # list all partitions with filesystem info
-Label        Type     Subtype       Address       Size    Block Actual FS     Flags
-------------------------------------------------------------------------------------------
-factory      app      factory       0x10000      1.94M                        running
-nvs          data     nvs            0x9000      24.0K
-vfs          data     littlefs     0x200000      2.00M     4 KB littlefs2
-
-Boot partition: factory
-Next OTA:       (none)
+$ mpytool flash                       # list all partitions, sorted by address
+Label        Type     Subtype       Address       Size    Block Content        Flags
+--------------------------------------------------------------------------------------------
+nvs          data     nvs            0x9000      16.0K
+otadata      data     ota            0xd000      8.00K
+phy_init     data     phy            0xf000      4.00K
+ota_0        app      ota_0         0x10000      2.50M          app ESP32-P4   running, ota:valid
+ota_1        app      ota_1        0x290000      2.50M          app ESP32-P4   ota:valid
+vfs          data     fat          0x510000      10.9M    4.00K littlefs2
+
+Boot partition: ota_0
+Next OTA:       ota_1
 
 $ mpytool flash read vfs backup.bin        # backup partition to file
 $ mpytool flash write nvs nvs_backup.bin   # restore partition from file
@@ -505,11 +596,39 @@ $ mpytool flash erase vfs                  # quick erase partition
 $ mpytool flash erase vfs --full           # full erase partition
 ```
 
+`Content` shows what a partition actually holds - the detected filesystem for
+data partitions, the image type for app partitions (`app <CHIP>`, or
+`BOOTLOADER!` / `INVALID!` / `empty`). The `ota:` flags come from the `otadata`
+partition and describe the **rollback bookkeeping** of a slot, not the image
+stored in it: a slot can read `ota:valid` while holding an unbootable image.
+
 ### OTA firmware update (ESP32)
+
+OTA needs an **app-only** image (`micropython.bin`), not the combined
+`firmware.bin` (bootloader + partition table + app) that `esptool` writes.
+mpytool checks the image header before uploading, so a wrong file is rejected
+immediately instead of failing with `ESP_ERR_OTA_VALIDATE_FAILED` after the
+whole transfer. It also refuses an image built for a different chip.
+
+```
+$ mpytool flash ota micropython.bin                     # write to next OTA partition
+$ mpytool flash ota micropython.bin -- reset --machine  # write and reboot
+$ mpytool flash ota micropython.bin -- reset --machine -t 30   # ... with 30s timeout
+$ mpytool flash ota micropython.bin --force             # write despite failed validation
+
+$ mpytool flash ota confirm            # mark running app valid (cancel rollback)
+$ mpytool flash ota boot               # boot the other slot (manual rollback)
+$ mpytool flash ota boot ota_1         # boot a specific app partition
+```
+
+If the firmware enables rollback, a freshly booted OTA image stays in
+`pending-verify` and reverts on the next reset until it is confirmed - either by
+the app itself (`esp32.Partition(esp32.Partition.RUNNING).mark_app_valid_cancel_rollback()`)
+or from the host:
+
 ```
-$ 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
+$ mpytool flash ota micropython.bin -- reset --machine
+$ mpytool flash ota confirm
 ```
 
 ### Multiple commands separated by `--`

{mpytool-2.4.0 → mpytool-2.6.0}/README_API.md

@@ -681,14 +681,45 @@ mpy.unique_id()
 
 #### memory()
 
-Get memory usage.
+Get MicroPython **GC heap** usage - the heap available to Python objects, not
+physical RAM. On ESP32 builds with PSRAM the GC heap grows and shrinks on
+demand, so `total` changes over time: right after a reset it can claim nearly
+all free PSRAM, and it shrinks again once drivers allocate PSRAM outside the GC
+heap (e.g. camera framebuffers via `heap_caps_malloc`). Use
+[`esp_ram()`](#esp_ram) for the physical memory regions.
 
 ```python
 mpy.memory()
 ```
 
 **Returns:**
-- `dict`: `{'alloc': bytes_used, 'free': bytes_free, 'total': total_bytes}`
+- `dict`: `{'alloc': bytes_used, 'free': bytes_free, 'total': gc_heap_bytes}`
+
+#### esp_ram()
+
+Get physical RAM usage per region (ESP32 only), read via
+`esp32.idf_heap_info()`. Unlike `memory()` this is stable, since it reflects the
+actual silicon rather than the floating GC heap.
+
+```python
+mpy.esp_ram()
+```
+
+**Returns:**
+- `dict` with `'sram'` and, when PSRAM is fitted, `'psram'`; each is
+  `{'total': bytes, 'free': bytes, 'used': bytes}`. Empty dict on non-ESP32
+  devices or builds without `esp32.idf_heap_info`.
+
+**Note:** totals cover memory registered with the ESP-IDF allocator, so they
+exclude static `.data`/`.bss` and code in IRAM - they are the heap-available
+portion of each region, not the raw chip capacity.
+
+**Example:**
+```python
+>>> mpy.esp_ram()
+{'sram': {'total': 640000, 'free': 140000, 'used': 500000},
+ 'psram': {'total': 33554432, 'free': 20971520, 'used': 12582912}}
+```
 
 ### Mount
 
@@ -953,9 +984,14 @@ Get partition table information (ESP32 only).
 mpy.partitions()
 ```
 
+Partitions are sorted by flash offset.
+
 **Returns:**
 - `dict` with keys:
-  - `'partitions'`: List of partition dicts with keys: `label`, `type`, `type_name`, `subtype`, `subtype_name`, `offset`, `size`, `encrypted`, `running`, `filesystem`, `fs_block_size`
+  - `'partitions'`: List of partition dicts with keys: `label`, `type`, `type_name`, `subtype`, `subtype_name`, `offset`, `size`, `encrypted`, `running`, `filesystem`, `fs_block_size`, plus for OTA app partitions:
+    - `'ota_state'`: rollback state recorded in `otadata` - `'new'`, `'pending-verify'`, `'valid'`, `'invalid'`, `'aborted'` or `'undefined'`. This is bookkeeping for the *slot*; it says nothing about the image currently stored there.
+    - `'ota_boot'`: `True` for the slot the bootloader will start
+    - `'image'`: what the partition actually holds, as returned by [`parse_esp_image()`](#parse_esp_imagedata)
   - `'boot'`: Boot partition label or None
   - `'next_ota'`: Next OTA partition label or None
   - `'next_ota_size'`: Next OTA partition size or None
@@ -1068,24 +1104,146 @@ mpy.flash_erase(label=None, full=False, progress_callback=None)
 >>> mpy.flash_erase(label='nvs', full=True)
 ```
 
-#### ota_write(data, progress_callback=None, compress=None)
+#### ota_write(data, progress_callback=None, compress=None, validate=True, force=False)
 
 Write firmware to next OTA partition and set it as boot partition.
 
+The image must be an **app-only** build (`micropython.bin`), not the combined
+`firmware.bin` that also contains the bootloader and partition table.
+
 ```python
-mpy.ota_write(data, progress_callback=None, compress=None)
+mpy.ota_write(data, progress_callback=None, compress=None,
+              validate=True, force=False)
 ```
 
 **Parameters:**
 - `data` (bytes): Firmware content (.app-bin file)
 - `progress_callback` (callable, optional): Callback `(transferred, total, wire_bytes)`
 - `compress` (bool, optional): Enable/disable compression
+- `validate` (bool): Check the image header first; set `False` only if `check_ota_image()` was already called on this data
+- `force` (bool): With `validate`, warn instead of refusing a bad image
 
 **Returns:**
 - `dict`: `{'target': label, 'offset': partition_offset, 'size': fw_size, 'wire_bytes': bytes_sent, 'compressed': bool}`
 
 **Raises:**
-- `MpyError`: If OTA not available or firmware too large
+- `MpyError`: If OTA not available, firmware too large, or the image fails validation
+
+#### ota_confirm()
+
+Mark the running app valid, cancelling a pending OTA rollback (wraps
+`esp32.Partition.mark_app_valid_cancel_rollback()`). After a fresh OTA boot the
+image is in `pending-verify` and reverts on the next reset until confirmed.
+
+```python
+mpy.ota_confirm()
+```
+
+**Returns:**
+- `str`: Label of the running partition
+
+**Raises:**
+- `MpyError`: On non-ESP32 devices, without OTA partitions, or if rollback is unsupported
+
+#### ota_set_boot(label=None)
+
+Switch the boot partition for the next reset.
+
+```python
+mpy.ota_set_boot(label=None)
+```
+
+**Parameters:**
+- `label` (str, optional): Target app partition (e.g. `'ota_1'`). If `None`, the passive slot from `get_next_update()` is used - a manual rollback.
+
+**Returns:**
+- `str`: Label of the partition set as boot
+
+**Raises:**
+- `MpyError`: On non-ESP32 devices, no OTA layout, or unknown label
+
+**Example:**
+```python
+>>> mpy.ota_set_boot()          # boot the other image
+'ota_1'
+>>> mpy.machine_reset()
+```
+
+#### check_ota_image(data, force=False)
+
+Validate firmware before an OTA upload. Rejects bootloader/combined images,
+empty or corrupt data, and images built for a different chip - turning a long
+upload followed by `ESP_ERR_OTA_VALIDATE_FAILED` into an immediate error.
+
+```python
+mpy.check_ota_image(data, force=False)
+```
+
+**Parameters:**
+- `data` (bytes): Firmware image
+- `force` (bool): Report problems as warnings and continue instead of raising
+
+**Raises:**
+- `MpyError`: If the data is not an application image for this chip (unless `force`)
+
+#### running_chip_id()
+
+Chip id of the currently running application, read from its image header. The
+bootloader validates `chip_id` against the real silicon before booting, so a
+running image proves its id matches the actual chip - and the header layout is
+stable across IDF/MicroPython versions.
+
+```python
+mpy.running_chip_id()
+```
+
+The value is cached; `reset_state()` clears it.
+
+**Returns:**
+- `int`: Chip id (see `mpytool.mpy.ESP_CHIP_IDS`), or `None` if undetermined
+
+### Module Functions
+
+#### esp_chip_name(chip_id)
+
+Display name for an `esp_chip_id_t` value.
+
+```python
+from mpytool import esp_chip_name
+```
+
+**Parameters:**
+- `chip_id` (int or None): Chip id, e.g. from `running_chip_id()`
+
+**Returns:**
+- `str`: Name such as `'ESP32-P4'`, or `'0x0099'` for a chip not in `ESP_CHIP_IDS` (the table is display-only, so newer chips still work); `None` if `chip_id` is `None`
+
+#### parse_esp_image(data)
+
+Parse the header of an ESP32 flash image. Distinguishes an application image
+(what OTA requires) from a bootloader or combined flash image.
+
+```python
+from mpytool import parse_esp_image
+```
+
+**Parameters:**
+- `data` (bytes): At least the first ~176 bytes of the image
+
+**Returns:**
+- `dict` with `'kind'` (`'app'`, `'bootloader'`, `'empty'` or `'invalid'`), plus:
+  - `'chip_id'`, `'chip_name'`, `'segments'` (app/bootloader)
+  - `'idf_ver'`, `'date'`, `'time'`, `'version'`, `'project'` (app only; MicroPython leaves version/project empty)
+  - `'app_offset'` - where the app starts inside a combined image (bootloader only)
+
+**Example:**
+```python
+>>> parse_esp_image(open('micropython.bin', 'rb').read())
+{'segments': 8, 'chip_id': 18, 'chip_name': 'ESP32-P4', 'kind': 'app', ...}
+>>> parse_esp_image(open('firmware.bin', 'rb').read())
+{'segments': 3, 'chip_id': 18, 'chip_name': 'ESP32-P4', 'kind': 'bootloader',
+ 'app_offset': 57344}
+```
 
 ## MpyComm Class
 

{mpytool-2.4.0 → mpytool-2.6.0}/completions/_mpytool

@@ -269,16 +269,24 @@ _mpytool() {
                         fi
                     fi
                     ;;
+                sync)
+                    # Optional local project directory, -- anytime
+                    if [[ $pos -eq 2 ]]; then
+                        _files -/
+                    fi
+                    compadd -- '--'
+                    ;;
                 exec)
                     # 1 code string, -- after it
                     [[ $nargs -ge 1 ]] && compadd -- '--'
                     ;;
                 run)
-                    # 1 local .py file, -- after it
+                    # optional local .py file or '-' for STDIN, -- after it
                     if [[ $pos -eq 2 ]]; then
                         _files -g '*.py'
+                        compadd -- '-'
                     fi
-                    [[ $nargs -ge 1 ]] && compadd -- '--'
+                    compadd -- '--'
                     ;;
                 edit)
                     # --editor CMD + 1 remote file, -- after file
@@ -323,10 +331,23 @@ _mpytool() {
                         )
                         _describe -t subcmds 'flash subcommand' subcmds
                     elif [[ "$flash_subcmd" == "ota" ]]; then
-                        # ota: 1 firmware file, -- after it
+                        # ota: <firmware.bin> | confirm | boot [label]
+                        local ota_action="${words[cmd_start+2]}"
                         if [[ $pos -eq 3 ]]; then
+                            local -a otacmds=(
+                                'confirm:mark running app valid (cancel rollback)'
+                                'boot:switch boot partition'
+                            )
+                            _describe -t otacmds 'ota action' otacmds
                             _files -g "*.bin"
+                            compadd -- '--force'
+                        elif [[ "$ota_action" == "boot" && $pos -eq 4 ]]; then
+                            # partition label (device-specific, no completion)
+                            compadd -- '--'
+                        elif [[ "$ota_action" == "confirm" ]]; then
+                            compadd -- '--'
                         else
+                            compadd -- '--force'
                             compadd -- '--'
                         fi
                     elif [[ $pos -eq 3 && "$flash_subcmd" == "erase" ]]; then
@@ -344,9 +365,9 @@ _mpytool() {
                     # -- after complete subcommand
                     if [[ "$flash_subcmd" == "erase" && $pos -ge 3 ]]; then
                         :  # already handled above
-                    elif [[ "$flash_subcmd" == "ota" && $pos -ge 4 ]]; then
-                        compadd -- '--'
-                    elif [[ "$flash_subcmd" != "erase" && "$flash_subcmd" != "ota" && $pos -ge 5 ]]; then
+                    elif [[ "$flash_subcmd" == "ota" ]]; then
+                        :  # already handled above
+                    elif [[ "$flash_subcmd" != "erase" && $pos -ge 5 ]]; then
                         compadd -- '--'
                     fi
                     ;;