idftool 0.2.2__tar.gz → 0.3.0__tar.gz

idftool-0.3.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [v0.3.0] — 2026-07-15
+
+### Added
+- Partition table file commands that make the table itself the subject
+  (a positional file), keeping the global `--partition-table-file`
+  option for its existing role of overriding the layout of other
+  commands:
+  - `convert-table <in> <out>` — convert a partition table between CSV
+    and binary, offline. Format is auto-detected on input and inferred
+    from the output extension (`.csv`/`.bin`) or `--format`.
+  - `print-table [file]` — pretty-print a partition table from a CSV or
+    binary file (offline), or from the device when no file is given.
+  - `dump-table [output]` — read the partition table from the device and
+    save it as CSV or binary (default filename
+    `{chip}-{mac}-{timestamp}-partition-table.csv`).
+  - `write-table <file>` — flash a partition table from a CSV or binary
+    file to the device. Requires an explicit file (so it can never read
+    the device's current table and write it back to itself), verifies
+    the table before flashing (override with `--force`), and warns that
+    only the map is replaced — existing partition data is not moved or
+    erased.
+
+### Changed
+- `list` is now an alias of `print-table` (both print the device's
+  partition table identically). Its `--partition-type`,
+  `--partition-subtype`, and `--partition-name` flags — which were never
+  implemented — have been removed.
+
+### Fixed
+- Working with empty or truncated input files now reports a clear error
+  instead of a confusing parser failure (e.g. "Partition table is
+  missing an end-of-table marker" for a zero-byte image). Empty images,
+  app binaries, and bundle ZIPs are rejected up front, as are images too
+  small to reach the partition table offset and corrupt (non-ZIP)
+  bundles.
+- A parsed-but-empty partition table (all-`0xFF` binary region,
+  comment-only CSV, etc.) is now rejected across all parse paths rather
+  than silently yielding a table with no partitions.
+- Loading a partition table CSV that contains bootloader rows (such as one
+  produced by `dump-table`) no longer requires re-specifying
+  `--primary-bootloader-offset`: the offset embedded in the CSV is
+  recovered from the file, so dumped tables round-trip through
+  `print-table`, `convert-table`, `write-table`, and `--partition-table-file`
+  without extra arguments. The flag still works as an explicit override.
+
+## [v0.2.2] — 2026-06-15
+
+### Added
+- `print-image` — inspect a flash image file offline: prints the
+  partition table and, for each app partition that contains a valid
+  app, the project name, version, IDF version, compile time, ELF
+  SHA256, and target chip.
+- `print-bundle` — same output for a partition bundle ZIP, driven by
+  the embedded `partition_table.csv` and the per-partition `.bin`
+  entries.
+
+### Changed
+- Bumped `esp-idf-defs` to `~=0.1.3`. `print_partition_table` now takes
+  a `(offset, length) -> bytes` accessor instead of an `ESPLoader`
+  instance, so the same printing path serves device, image, and bundle
+  inspection.
+
+## [v0.2.1] — 2026-06-10
+
+### Changed
+- Boot partition state now uses `OtaImageState` for clearer reporting.
+
+## [v0.2.0] — 2026-05-26
+
+### Added
+- `create-nvs` and `write-nvs` commands for generating NVS partition
+  images from CSV.
+- Rich-style boxed traceback formatter for friendlier error output.
+
+### Documentation
+- README installation section and command index table.
+- Recommend `pipx` over the standalone binary for installation.
+
+## [v0.1.0] — 2026-05-25
+
+### Added
+- Initial release.
+
+[v0.3.0]: https://github.com/nebkat/idftool/releases/tag/v0.3.0
+[v0.2.2]: https://github.com/nebkat/idftool/releases/tag/v0.2.2
+[v0.2.1]: https://github.com/nebkat/idftool/releases/tag/v0.2.1
+[v0.2.0]: https://github.com/nebkat/idftool/releases/tag/v0.2.0
+[v0.1.0]: https://github.com/nebkat/idftool/releases/tag/v0.1.0

{idftool-0.2.2 → idftool-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.2.2
+Version: 0.3.0
 Summary: Utility for flashing, provisioning, and interacting with Espressif SOCs running ESP-IDF
 License-Expression: Apache-2.0
 Project-URL: Source, https://github.com/nebkat/idftool
@@ -103,7 +103,7 @@ Setting boot partition to 'ota_1'...
 |---------|-------------|
 | **Discovery** | |
 | [`devices`](#devices) | List serial ports with hardware IDs |
-| [`list`](#list) | Print the partition table |
+| [`list`](#print-table) | Print the partition table (alias of `print-table`) |
 | **Partition I/O** | |
 | [`read`](#read) | Read a partition (or slice) into a file |
 | [`write`](#write) | Write one or more files to named partitions |
@@ -126,6 +126,11 @@ Setting boot partition to 'ota_1'...
 | [`dump-bundle`](#dump-bundle) | Pack every partition from the device into a ZIP |
 | [`write-bundle`](#write-bundle) | Flash every binary in a bundle ZIP |
 | [`print-bundle`](#print-bundle) | Print partition table and app info from a bundle ZIP |
+| **Partition table** | |
+| [`convert-table`](#convert-table) | Convert a partition table file between CSV and binary |
+| [`print-table`](#print-table) | Print a partition table from a CSV or binary file, or the device |
+| [`dump-table`](#dump-table) | Read the partition table from the device into a file |
+| [`write-table`](#write-table) | Flash a partition table from a CSV or binary file |
 | **NVS** | |
 | [`create-nvs`](#create-nvs) | Generate an NVS partition image from a CSV file |
 | [`write-nvs`](#write-nvs) | Generate an NVS image from CSV and flash it |
@@ -141,17 +146,6 @@ hardware IDs.
 idftool devices
 ```
 
-#### `list`
-Print the device's partition table. With a connected ESP, idftool also
-reads the application descriptor of every app partition (project name,
-version) and marks the currently-active OTA slot with a trailing `*`. The
-selected otadata copy is shown next to the otadata partition's subtype
-(`ota (A)`, `ota (B)`, or `ota (invalid)` when otadata is erased).
-```text
-idftool list
-idftool --partition-table-file partitions.csv list   # offline
-```
-
 ### Partition I/O
 
 #### `read`
@@ -312,6 +306,70 @@ version, IDF version, compile time, ELF SHA256, and target chip.
 idftool print-bundle release.zip
 ```
 
+### Partition table
+
+These commands work directly on a partition table as a file — the table
+is the subject, passed as a positional argument. This is distinct from the
+global `--partition-table-file` option, which overrides the layout *other*
+commands use to address partitions by name. Input format (CSV or binary)
+is auto-detected; output format is inferred from the file extension
+(`.csv`/`.bin`) or set with `--format`.
+
+When the input is a CSV that includes a bootloader row, pass
+`--primary-bootloader-offset` (an offset or a chip name, e.g. `esp32s3`)
+so the offset can be resolved.
+
+#### `convert-table`
+Convert a partition table between CSV and binary, offline. Handles both
+directions; the binary output includes the MD5 checksum and padding, so it
+is ready to flash or embed in an image.
+```text
+idftool convert-table partitions.csv partitions.bin
+idftool convert-table partitions.bin partitions.csv
+idftool --primary-bootloader-offset esp32s3 convert-table partitions.csv partitions.bin
+```
+
+#### `print-table`
+Pretty-print a partition table. Given a CSV or binary file it runs offline;
+with no file it reads the table from the device (or from
+`--partition-table-file`). With a connected ESP, idftool also reads the
+application descriptor of every app partition (project name, version) and
+marks the currently-active OTA slot with a trailing `*`; the selected otadata
+copy is shown next to the otadata partition's subtype (`ota (A)`, `ota (B)`,
+or `ota (invalid)` when otadata is erased).
+
+Aliased as `list`.
+```text
+idftool print-table partitions.bin        # from a file, offline
+idftool print-table                        # from the device
+idftool list                               # same thing
+idftool --partition-table-file partitions.csv print-table
+```
+
+#### `dump-table`
+Read the partition table from the connected device and save it. Defaults to
+CSV with an auto-generated filename; pass an output file or `--format` to
+choose otherwise.
+```text
+idftool dump-table                       # auto-named .csv
+idftool dump-table backup.bin
+idftool dump-table backup.csv --format csv
+```
+
+#### `write-table`
+Flash a partition table from a CSV or binary file to the device. The file is
+required, so this never reads the device's current table and writes it back
+to itself — use `dump-table` to pull the current table. The table is verified
+before flashing (override with `--force`).
+
+Only the partition map (at the partition table offset) is replaced; existing
+partition **data** on flash is not moved, resized, or erased, so a table that
+no longer matches the flash contents can make the device unbootable.
+```text
+idftool write-table partitions.csv
+idftool write-table partitions.bin --force
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

{idftool-0.2.2 → idftool-0.3.0}/README.md

@@ -89,7 +89,7 @@ Setting boot partition to 'ota_1'...
 |---------|-------------|
 | **Discovery** | |
 | [`devices`](#devices) | List serial ports with hardware IDs |
-| [`list`](#list) | Print the partition table |
+| [`list`](#print-table) | Print the partition table (alias of `print-table`) |
 | **Partition I/O** | |
 | [`read`](#read) | Read a partition (or slice) into a file |
 | [`write`](#write) | Write one or more files to named partitions |
@@ -112,6 +112,11 @@ Setting boot partition to 'ota_1'...
 | [`dump-bundle`](#dump-bundle) | Pack every partition from the device into a ZIP |
 | [`write-bundle`](#write-bundle) | Flash every binary in a bundle ZIP |
 | [`print-bundle`](#print-bundle) | Print partition table and app info from a bundle ZIP |
+| **Partition table** | |
+| [`convert-table`](#convert-table) | Convert a partition table file between CSV and binary |
+| [`print-table`](#print-table) | Print a partition table from a CSV or binary file, or the device |
+| [`dump-table`](#dump-table) | Read the partition table from the device into a file |
+| [`write-table`](#write-table) | Flash a partition table from a CSV or binary file |
 | **NVS** | |
 | [`create-nvs`](#create-nvs) | Generate an NVS partition image from a CSV file |
 | [`write-nvs`](#write-nvs) | Generate an NVS image from CSV and flash it |
@@ -127,17 +132,6 @@ hardware IDs.
 idftool devices
 ```
 
-#### `list`
-Print the device's partition table. With a connected ESP, idftool also
-reads the application descriptor of every app partition (project name,
-version) and marks the currently-active OTA slot with a trailing `*`. The
-selected otadata copy is shown next to the otadata partition's subtype
-(`ota (A)`, `ota (B)`, or `ota (invalid)` when otadata is erased).
-```text
-idftool list
-idftool --partition-table-file partitions.csv list   # offline
-```
-
 ### Partition I/O
 
 #### `read`
@@ -298,6 +292,70 @@ version, IDF version, compile time, ELF SHA256, and target chip.
 idftool print-bundle release.zip
 ```
 
+### Partition table
+
+These commands work directly on a partition table as a file — the table
+is the subject, passed as a positional argument. This is distinct from the
+global `--partition-table-file` option, which overrides the layout *other*
+commands use to address partitions by name. Input format (CSV or binary)
+is auto-detected; output format is inferred from the file extension
+(`.csv`/`.bin`) or set with `--format`.
+
+When the input is a CSV that includes a bootloader row, pass
+`--primary-bootloader-offset` (an offset or a chip name, e.g. `esp32s3`)
+so the offset can be resolved.
+
+#### `convert-table`
+Convert a partition table between CSV and binary, offline. Handles both
+directions; the binary output includes the MD5 checksum and padding, so it
+is ready to flash or embed in an image.
+```text
+idftool convert-table partitions.csv partitions.bin
+idftool convert-table partitions.bin partitions.csv
+idftool --primary-bootloader-offset esp32s3 convert-table partitions.csv partitions.bin
+```
+
+#### `print-table`
+Pretty-print a partition table. Given a CSV or binary file it runs offline;
+with no file it reads the table from the device (or from
+`--partition-table-file`). With a connected ESP, idftool also reads the
+application descriptor of every app partition (project name, version) and
+marks the currently-active OTA slot with a trailing `*`; the selected otadata
+copy is shown next to the otadata partition's subtype (`ota (A)`, `ota (B)`,
+or `ota (invalid)` when otadata is erased).
+
+Aliased as `list`.
+```text
+idftool print-table partitions.bin        # from a file, offline
+idftool print-table                        # from the device
+idftool list                               # same thing
+idftool --partition-table-file partitions.csv print-table
+```
+
+#### `dump-table`
+Read the partition table from the connected device and save it. Defaults to
+CSV with an auto-generated filename; pass an output file or `--format` to
+choose otherwise.
+```text
+idftool dump-table                       # auto-named .csv
+idftool dump-table backup.bin
+idftool dump-table backup.csv --format csv
+```
+
+#### `write-table`
+Flash a partition table from a CSV or binary file to the device. The file is
+required, so this never reads the device's current table and writes it back
+to itself — use `dump-table` to pull the current table. The table is verified
+before flashing (override with `--force`).
+
+Only the partition map (at the partition table offset) is replaced; existing
+partition **data** on flash is not moved, resized, or erased, so a table that
+no longer matches the flash contents can make the device unbootable.
+```text
+idftool write-table partitions.csv
+idftool write-table partitions.bin --force
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

{idftool-0.2.2 → idftool-0.3.0}/idftool/__main__.py

@@ -4,7 +4,7 @@ import re
 import sys
 import time
 from typing import Callable, Optional, Literal
-from zipfile import ZipFile
+from zipfile import BadZipFile, ZipFile
 
 from esptool import ESPLoader, CHIP_DEFS, flash_size_bytes
 from serial import SerialException
@@ -17,7 +17,7 @@ from esp_idf_defs import ImageMetadata, ChipId
 from esp_idf_defs.otadata import OtaDataParameters, OtaDataSelectEntry, OtaImageState
 from esp_idf_defs.partitions import PARTITION_TABLE_SIZE, PARTITION_TABLE_OFFSET, PartitionTable, print_partition_table, \
     PartitionDefinition, BOOTLOADER_TYPE, SUBTYPES, PARTITION_TABLE_TYPE, APP_TYPE, NUM_PARTITION_SUBTYPE_APP_OTA, \
-    DATA_TYPE
+    DATA_TYPE, get_encoding
 from esptool.cmds import detect_chip, read_flash, write_flash, erase_region, merge_bin, erase_flash, detect_flash_size
 
 PARTITION_SLICE_REGEX = re.compile(r"^(?P<partition>.+?)(?:\[(?:(?P<start>[-+]?(?:0x)?[0-9A-Fa-f]+)?(?::(?P<stop>[-+]?(?:0x)?[0-9A-Fa-f]+)?)?)?])?$")
@@ -239,6 +239,99 @@ def write_otadata(esp: ESPLoader, partition: PartitionDefinition, otadata: OtaDa
     esp.flash_block(data=otadata.otadata.to_bytes(), seq=0)
     esp.flash_finish()
 
+def check_image_file(path: str, partition_table_offset: int) -> int:
+    """Validate an image file is non-empty and large enough to contain a partition table.
+
+    Returns the image size in bytes.
+    """
+    image_size = os.path.getsize(path)
+    if image_size == 0:
+        raise RuntimeError(f"Image file '{path}' is empty")
+    if image_size <= partition_table_offset:
+        raise RuntimeError(
+            f"Image file '{path}' ({image_size:#x} bytes) is smaller than the partition table "
+            f"offset {partition_table_offset:#x}; it does not appear to contain a partition table")
+    return image_size
+
+def require_partitions(partition_table: PartitionTable, source: str) -> PartitionTable:
+    """Raise a clear error if a parsed partition table contains no partitions."""
+    if len(partition_table) == 0:
+        raise RuntimeError(f"Partition table from {source} is empty (no partitions defined)")
+    return partition_table
+
+def load_partition_table_file(
+        path: str,
+        partition_table_offset: int,
+        primary_bootloader_offset: Optional[int],
+        recovery_bootloader_offset: Optional[int],
+) -> PartitionTable:
+    """Load a partition table from a CSV or binary file (format auto-detected)."""
+    if os.path.getsize(path) == 0:
+        raise RuntimeError(f"Partition table file '{path}' is empty")
+    with open(path, 'rb') as f:
+        data = f.read()
+
+    if data[:2] == PartitionDefinition.MAGIC_BYTES:
+        partition_table = PartitionTable.from_binary(data)
+    else:
+        csv_text = data.decode(get_encoding(data))
+        # A CSV with bootloader rows can't be parsed without the bootloader offsets. idftool writes
+        # those offsets into the CSV as literal bootloader rows, so recover them from the file itself
+        # when the user didn't pass them — this lets a dumped table round-trip without re-specifying
+        # --primary-bootloader-offset. (print-bundle does the same for bundle CSVs.)
+        if primary_bootloader_offset is None or recovery_bootloader_offset is None:
+            csv_primary, csv_recovery = _extract_csv_bootloader_offsets(csv_text)
+            if primary_bootloader_offset is None:
+                primary_bootloader_offset = csv_primary
+            if recovery_bootloader_offset is None:
+                recovery_bootloader_offset = csv_recovery
+        try:
+            partition_table = PartitionTable.from_csv(
+                csv_text,
+                partition_table_offset=partition_table_offset,
+                primary_bootloader_offset=primary_bootloader_offset,
+                recovery_bootloader_offset=recovery_bootloader_offset,
+            )
+        except RuntimeError as e:
+            msg = str(e)
+            if 'bootloader offset is not provided' in msg.lower():
+                which = 'recovery' if 'recovery' in msg.lower() else 'primary'
+                flag = ('--primary-bootloader-offset (an address or a chip name, e.g. esp32s3)'
+                        if which == 'primary' else '--recovery-bootloader-offset')
+                line = re.search(r'line (\d+)', msg)
+                where = f" (line {line.group(1)})" if line else ""
+                raise RuntimeError(
+                    f"The {which} bootloader entry in '{path}'{where} has no offset. "
+                    f"Add the offset to the CSV, or pass {flag}."
+                ) from None
+            raise
+    return require_partitions(partition_table, f"file '{path}'")
+
+def resolve_partition_table_format(output_file: Optional[str], explicit: Optional[str]) -> Literal['csv', 'bin']:
+    """Pick the output format from an explicit flag, else the output file extension (default csv)."""
+    if explicit:
+        return explicit
+    if output_file:
+        ext = os.path.splitext(output_file)[1].lower()
+        if ext == '.csv':
+            return 'csv'
+        if ext in ('.bin', '.img'):
+            return 'bin'
+        raise RuntimeError(
+            f"Cannot infer partition table format from '{output_file}'; "
+            f"pass --format csv|bin or use a .csv/.bin extension")
+    return 'csv'
+
+def write_partition_table_file(partition_table: PartitionTable, output_file: str, output_format: Literal['csv', 'bin']):
+    """Serialise a partition table to CSV or binary and write it to output_file."""
+    if output_format == 'csv':
+        data = partition_table.to_csv().encode('utf-8')
+    else:
+        data = partition_table.to_binary()
+    with open(output_file, 'wb') as f:
+        f.write(data)
+    print(f"Wrote {output_format} partition table ({len(data):#x} bytes) to {output_file}")
+
 def validate_app_binary(esp: ESPLoader, app_binary: bytes) -> tuple[bytes, ImageMetadata]:
     try:
         image_metadata = ImageMetadata.from_bytes(app_binary, app_required=True)
@@ -256,6 +349,8 @@ def validate_app_binary(esp: ESPLoader, app_binary: bytes) -> tuple[bytes, Image
 
 def load_app_binary(esp: ESPLoader, app_binary_file: str, partition: PartitionDefinition) -> tuple[bytes, ImageMetadata]:
     app_binary_size = os.path.getsize(app_binary_file)
+    if app_binary_size == 0:
+        raise RuntimeError(f"Application binary '{app_binary_file}' is empty")
     if app_binary_size > partition.size:
         raise RuntimeError(
             f"Application binary size '{app_binary_size}' is greater than partition size {partition.size}")
@@ -404,7 +499,13 @@ def command_create_bundle(
             print(f"Adding partition table CSV to bundle")
 
 def check_write_bundle_has_partition_table(file: str) -> bool:
-    with ZipFile(file, 'r') as zf:
+    if os.path.getsize(file) == 0:
+        raise RuntimeError(f"Bundle '{file}' is empty")
+    try:
+        bundle_zip = ZipFile(file, 'r')
+    except BadZipFile as e:
+        raise RuntimeError(f"Bundle '{file}' is not a valid ZIP archive") from e
+    with bundle_zip as zf:
         return any(m == 'partition_table.csv' for m in zf.namelist())
 
 def command_write_bundle(
@@ -569,6 +670,8 @@ def command_write_nvs(
     write_flash(esp=esp, addr_data=[(partition.offset, image)], flash_size='detect')
 
 def command_app_info(app_binary_file: str):
+    if os.path.getsize(app_binary_file) == 0:
+        raise RuntimeError(f"Application binary '{app_binary_file}' is empty")
     app_binary = open(app_binary_file, 'rb').read()
     try:
         image_metadata = ImageMetadata.from_bytes(app_binary, app_required=True)
@@ -578,6 +681,8 @@ def command_app_info(app_binary_file: str):
     print_app_info(image_metadata.app_description, image_metadata.header)
 
 def command_write_image(esp: ESPLoader, bootloader_entry: PartitionDefinition, image_file_path: str):
+    if os.path.getsize(image_file_path) == 0:
+        raise RuntimeError(f"Image file '{image_file_path}' is empty")
     image_file = open(image_file_path, 'rb')
     image_file.seek(bootloader_entry.offset)
     bootloader_binary = image_file.read(bootloader_entry.size)
@@ -638,7 +743,7 @@ def print_partition_table_and_apps(
         print_app_info(image_metadata.app_description, image_metadata.header, indent="  ")
 
 def command_print_image(image_file_path: str, partition_table_offset: int, partition_table_size: int):
-    image_size = os.path.getsize(image_file_path)
+    image_size = check_image_file(image_file_path, partition_table_offset)
     with open(image_file_path, 'rb') as f:
         f.seek(partition_table_offset)
         partition_table_binary = f.read(partition_table_size)
@@ -646,6 +751,7 @@ def command_print_image(image_file_path: str, partition_table_offset: int, parti
             partition_table = PartitionTable.from_binary(partition_table_binary)
         except (RuntimeError, ValueError) as e:
             raise RuntimeError(f"Could not parse partition table at offset {partition_table_offset:#x}") from e
+        require_partitions(partition_table, f"image at offset {partition_table_offset:#x}")
 
         def read(offset: int, length: int) -> bytes:
             if offset >= image_size:
@@ -686,11 +792,19 @@ def command_print_bundle(
         recovery_bootloader_offset: Optional[int],
 ):
     bundle_size = os.path.getsize(bundle_file_path)
-    with ZipFile(bundle_file_path, 'r') as zf:
+    if bundle_size == 0:
+        raise RuntimeError(f"Bundle '{bundle_file_path}' is empty")
+    try:
+        bundle_zip = ZipFile(bundle_file_path, 'r')
+    except BadZipFile as e:
+        raise RuntimeError(f"Bundle '{bundle_file_path}' is not a valid ZIP archive") from e
+    with bundle_zip as zf:
         names = zf.namelist()
         if 'partition_table.csv' not in names:
             raise RuntimeError(f"Bundle {bundle_file_path} does not contain a partition_table.csv")
         csv_text = zf.read('partition_table.csv').decode('utf-8')
+        if not csv_text.strip():
+            raise RuntimeError(f"Bundle '{bundle_file_path}' contains an empty partition_table.csv")
 
         # idftool-generated bundles encode bootloader offsets in the CSV; PartitionTable.from_csv
         # ignores the literal for bootloader rows and requires an explicit offset, so fall back to
@@ -708,6 +822,7 @@ def command_print_bundle(
             primary_bootloader_offset=primary_bootloader_offset,
             recovery_bootloader_offset=recovery_bootloader_offset,
         )
+        require_partitions(partition_table, f"bundle '{bundle_file_path}'")
 
         partition_data = {
             name[:-4]: zf.read(name)
@@ -731,6 +846,80 @@ def command_print_bundle(
         print()
         print_partition_table_and_apps(partition_table, read)
 
+def command_print_table(
+        table_file_path: str,
+        partition_table_offset: int,
+        primary_bootloader_offset: Optional[int],
+        recovery_bootloader_offset: Optional[int],
+):
+    partition_table = load_partition_table_file(
+        table_file_path, partition_table_offset, primary_bootloader_offset, recovery_bootloader_offset)
+    print(f"Partition table: {table_file_path}")
+    print()
+    print_partition_table(partition_table)
+
+def command_convert_table(
+        input_file: str,
+        output_file: str,
+        output_format: Optional[str],
+        partition_table_offset: int,
+        primary_bootloader_offset: Optional[int],
+        recovery_bootloader_offset: Optional[int],
+):
+    partition_table = load_partition_table_file(
+        input_file, partition_table_offset, primary_bootloader_offset, recovery_bootloader_offset)
+    output_format = resolve_partition_table_format(output_file, output_format)
+    write_partition_table_file(partition_table, output_file, output_format)
+
+def command_dump_table(
+        esp: ESPLoader,
+        partition_table: PartitionTable,
+        output_file: Optional[str],
+        output_format: Optional[str],
+):
+    if not output_file:
+        chip = esp.CHIP_NAME.lower().replace(' ', '-')
+        try:
+            mac = esp.read_mac("BASE_MAC")
+            serial = ''.join(f"{b:02x}" for b in mac)
+        except Exception:
+            serial = "unknown"
+        timestamp = time.strftime("%Y%m%d-%H%M%S")
+        extension = 'bin' if output_format == 'bin' else 'csv'
+        output_file = f"{chip}-{serial}-{timestamp}-partition-table.{extension}"
+    output_format = resolve_partition_table_format(output_file, output_format)
+    write_partition_table_file(partition_table, output_file, output_format)
+
+def command_write_table(
+        esp: ESPLoader,
+        table_file_path: str,
+        partition_table_offset: int,
+        primary_bootloader_offset: Optional[int],
+        recovery_bootloader_offset: Optional[int],
+        force: bool = False,
+):
+    partition_table = load_partition_table_file(
+        table_file_path, partition_table_offset, primary_bootloader_offset, recovery_bootloader_offset)
+
+    try:
+        partition_table.verify(partition_table_offset=partition_table_offset)
+    except RuntimeError as e:
+        if not force:
+            raise RuntimeError(
+                f"Partition table failed verification: {e}. Re-run with --force to flash it anyway.") from e
+        print(f"Warning: partition table failed verification: {e} (continuing due to --force)")
+
+    partition_table.verify_size_fits(flash_size_bytes(detect_flash_size(esp)))
+
+    binary = partition_table.to_binary()
+    print_partition_table(partition_table)
+    print()
+    print(f"Writing partition table ({len(binary):#x} bytes) to offset {partition_table_offset:#x}...")
+    print("Note: this replaces only the partition map; existing partition data on flash is not moved, "
+          "resized, or erased. A table that no longer matches the flash contents can make the device unbootable.")
+    write_flash(esp=esp, addr_data=[(partition_table_offset, binary)], flash_size='detect')
+    print("Partition table written")
+
 def command_dump_image(esp: ESPLoader, output_file: Optional[str]):
     flash_size = flash_size_bytes(detect_flash_size(esp))
 
@@ -821,30 +1010,68 @@ def main(args):
         )
         return
 
+    # print-table and convert-table operate purely on a local partition table file. print-table
+    # with no file falls through to the shared loader, printing the device's table (or the one
+    # given via --partition-table-file).
+    if args.command == 'print-table' and args.table_file:
+        command_print_table(
+            table_file_path=args.table_file,
+            partition_table_offset=args.partition_table_offset,
+            primary_bootloader_offset=args.primary_bootloader_offset,
+            recovery_bootloader_offset=args.recovery_bootloader_offset,
+        )
+        return
+
+    if args.command == 'convert-table':
+        command_convert_table(
+            input_file=args.input_file,
+            output_file=args.output_file,
+            output_format=args.format,
+            partition_table_offset=args.partition_table_offset,
+            primary_bootloader_offset=args.primary_bootloader_offset,
+            recovery_bootloader_offset=args.recovery_bootloader_offset,
+        )
+        return
+
     # Connect to ESP device if required
-    requires_esp = args.command not in ['list', 'create-image', 'create-bundle', 'create-nvs'] or not args.partition_table_file
+    requires_esp = args.command not in ['create-image', 'create-bundle', 'create-nvs', 'print-table'] or not args.partition_table_file
     esp = get_esp(port=args.port, baud=args.baud) if requires_esp else None
-    if not args.primary_bootloader_offset and esp:
+    if args.primary_bootloader_offset is None and esp:
         args.primary_bootloader_offset = esp.BOOTLOADER_FLASH_OFFSET
 
+    # write-table flashes a partition table from its own positional file, bypassing the shared
+    # loader so it never reads the device's current table and writes it straight back to itself.
+    if args.command == 'write-table':
+        command_write_table(
+            esp=esp,
+            table_file_path=args.table_file,
+            partition_table_offset=args.partition_table_offset,
+            primary_bootloader_offset=args.primary_bootloader_offset,
+            recovery_bootloader_offset=args.recovery_bootloader_offset,
+            force=args.force,
+        )
+        if esp and not args.no_reset:
+            esp.hard_reset()
+        return
+
     if args.command == 'dump-image':
         command_dump_image(esp=esp, output_file=args.output_file)
         return
 
     # Load partition table
     if args.command == 'write-image':
+        check_image_file(args.image_file, args.partition_table_offset)
         with open(args.image_file, 'rb') as f:
             f.seek(args.partition_table_offset)
             partition_table_binary = f.read(args.partition_table_size)
             partition_table = PartitionTable.from_binary(partition_table_binary)
     elif args.partition_table_file:
-        with open(args.partition_table_file, 'rb') as f:
-            partition_table = PartitionTable.from_file(
-                f,
-                partition_table_offset=args.partition_table_offset,
-                primary_bootloader_offset=args.primary_bootloader_offset,
-                recovery_bootloader_offset=args.recovery_bootloader_offset
-            )[0]
+        partition_table = load_partition_table_file(
+            args.partition_table_file,
+            partition_table_offset=args.partition_table_offset,
+            primary_bootloader_offset=args.primary_bootloader_offset,
+            recovery_bootloader_offset=args.recovery_bootloader_offset,
+        )
     elif args.command == 'write-bundle' and check_write_bundle_has_partition_table(args.input_file):
         with ZipFile(args.input_file, 'r') as tar:
             partition_table_file = tar.read('partition_table.csv')
@@ -863,6 +1090,8 @@ def main(args):
         except RuntimeError as e:
             raise RuntimeError("Partition table could not be loaded") from e
 
+    require_partitions(partition_table, "the loaded source")
+
     # Read otadata so the printed table can mark the active app partition
     otadata_params: OtaDataParameters | None = None
     if esp:
@@ -897,7 +1126,8 @@ def main(args):
         ) if args.primary_bootloader_offset is not None else None
     )
 
-    if args.command == 'list':
+    if args.command == 'print-table':
+        # The shared path above already loaded and printed the table.
         pass
     elif args.command == 'read':
         command_read(
@@ -955,6 +1185,13 @@ def main(args):
         )
     elif args.command == 'dump-bundle':
         command_dump_bundle(esp=esp, partition_table=partition_table, output_file=args.output_file)
+    elif args.command == 'dump-table':
+        command_dump_table(
+            esp=esp,
+            partition_table=partition_table,
+            output_file=args.output_file,
+            output_format=args.format,
+        )
     elif args.command == 'write-bundle':
         command_write_bundle(
             esp=esp,
@@ -1012,12 +1249,6 @@ def _main():
     # Devices subcommand
     devices_parser = subparsers.add_parser('devices', help='Device list')
 
-    # List subcommand
-    list_parser = subparsers.add_parser('list', help='List partitions')
-    list_parser.add_argument('--partition-type', help='Filter by partition type')
-    list_parser.add_argument('--partition-subtype', help='Filter by partition subtype')
-    list_parser.add_argument('--partition-name', help='Filter by partition name')
-
     # Read subcommand
     read_parser = subparsers.add_parser('read', help='Read partition')
     read_parser.add_argument('partition', help='Name of the partition to read')
@@ -1090,6 +1321,26 @@ def _main():
     print_bundle_parser = subparsers.add_parser('print-bundle', help='Print partition table and app info from a partition bundle ZIP')
     print_bundle_parser.add_argument('bundle_file', help='Input ZIP bundle file')
 
+    # Print Table subcommand
+    print_table_parser = subparsers.add_parser('print-table', aliases=['list'], help='Print a partition table from a CSV or binary file, or from the device')
+    print_table_parser.add_argument('table_file', nargs='?', help='Partition table CSV or binary file (default: read from the device, or --partition-table-file)')
+
+    # Convert Table subcommand
+    convert_table_parser = subparsers.add_parser('convert-table', help='Convert a partition table file between CSV and binary')
+    convert_table_parser.add_argument('input_file', help='Input partition table CSV or binary file')
+    convert_table_parser.add_argument('output_file', help='Output partition table file (.csv or .bin)')
+    convert_table_parser.add_argument('-f', '--format', choices=['csv', 'bin'], help='Output format (default: inferred from output extension)')
+
+    # Dump Table subcommand
+    dump_table_parser = subparsers.add_parser('dump-table', help='Dump the partition table from the device to a file')
+    dump_table_parser.add_argument('output_file', nargs='?', help='Output file (default: {chip}-{mac}-{timestamp}-partition-table.csv)')
+    dump_table_parser.add_argument('-f', '--format', choices=['csv', 'bin'], help='Output format (default: inferred from output extension, else csv)')
+
+    # Write Table subcommand
+    write_table_parser = subparsers.add_parser('write-table', help='Write a partition table from a CSV or binary file to the device')
+    write_table_parser.add_argument('table_file', help='Partition table CSV or binary file to flash')
+    write_table_parser.add_argument('--force', action='store_true', help='Flash even if the partition table fails verification')
+
     # Create NVS subcommand
     create_nvs_parser = subparsers.add_parser('create-nvs', help='Generate NVS partition image from CSV')
     create_nvs_parser.add_argument('csv_file', help='Input NVS CSV file')
@@ -1127,6 +1378,8 @@ def _main():
     args = parser.parse_args()
     if args.command == 'reflash':
         args.command = 'write-image'
+    if args.command == 'list':
+        args.command = 'print-table'
     if args.command == 'enter-bootloader' and not args.port:
         parser.error("enter-bootloader requires -p/--port")
     try:

{idftool-0.2.2 → idftool-0.3.0}/idftool.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.2.2
+Version: 0.3.0
 Summary: Utility for flashing, provisioning, and interacting with Espressif SOCs running ESP-IDF
 License-Expression: Apache-2.0
 Project-URL: Source, https://github.com/nebkat/idftool
@@ -103,7 +103,7 @@ Setting boot partition to 'ota_1'...
 |---------|-------------|
 | **Discovery** | |
 | [`devices`](#devices) | List serial ports with hardware IDs |
-| [`list`](#list) | Print the partition table |
+| [`list`](#print-table) | Print the partition table (alias of `print-table`) |
 | **Partition I/O** | |
 | [`read`](#read) | Read a partition (or slice) into a file |
 | [`write`](#write) | Write one or more files to named partitions |
@@ -126,6 +126,11 @@ Setting boot partition to 'ota_1'...
 | [`dump-bundle`](#dump-bundle) | Pack every partition from the device into a ZIP |
 | [`write-bundle`](#write-bundle) | Flash every binary in a bundle ZIP |
 | [`print-bundle`](#print-bundle) | Print partition table and app info from a bundle ZIP |
+| **Partition table** | |
+| [`convert-table`](#convert-table) | Convert a partition table file between CSV and binary |
+| [`print-table`](#print-table) | Print a partition table from a CSV or binary file, or the device |
+| [`dump-table`](#dump-table) | Read the partition table from the device into a file |
+| [`write-table`](#write-table) | Flash a partition table from a CSV or binary file |
 | **NVS** | |
 | [`create-nvs`](#create-nvs) | Generate an NVS partition image from a CSV file |
 | [`write-nvs`](#write-nvs) | Generate an NVS image from CSV and flash it |
@@ -141,17 +146,6 @@ hardware IDs.
 idftool devices
 ```
 
-#### `list`
-Print the device's partition table. With a connected ESP, idftool also
-reads the application descriptor of every app partition (project name,
-version) and marks the currently-active OTA slot with a trailing `*`. The
-selected otadata copy is shown next to the otadata partition's subtype
-(`ota (A)`, `ota (B)`, or `ota (invalid)` when otadata is erased).
-```text
-idftool list
-idftool --partition-table-file partitions.csv list   # offline
-```
-
 ### Partition I/O
 
 #### `read`
@@ -312,6 +306,70 @@ version, IDF version, compile time, ELF SHA256, and target chip.
 idftool print-bundle release.zip
 ```
 
+### Partition table
+
+These commands work directly on a partition table as a file — the table
+is the subject, passed as a positional argument. This is distinct from the
+global `--partition-table-file` option, which overrides the layout *other*
+commands use to address partitions by name. Input format (CSV or binary)
+is auto-detected; output format is inferred from the file extension
+(`.csv`/`.bin`) or set with `--format`.
+
+When the input is a CSV that includes a bootloader row, pass
+`--primary-bootloader-offset` (an offset or a chip name, e.g. `esp32s3`)
+so the offset can be resolved.
+
+#### `convert-table`
+Convert a partition table between CSV and binary, offline. Handles both
+directions; the binary output includes the MD5 checksum and padding, so it
+is ready to flash or embed in an image.
+```text
+idftool convert-table partitions.csv partitions.bin
+idftool convert-table partitions.bin partitions.csv
+idftool --primary-bootloader-offset esp32s3 convert-table partitions.csv partitions.bin
+```
+
+#### `print-table`
+Pretty-print a partition table. Given a CSV or binary file it runs offline;
+with no file it reads the table from the device (or from
+`--partition-table-file`). With a connected ESP, idftool also reads the
+application descriptor of every app partition (project name, version) and
+marks the currently-active OTA slot with a trailing `*`; the selected otadata
+copy is shown next to the otadata partition's subtype (`ota (A)`, `ota (B)`,
+or `ota (invalid)` when otadata is erased).
+
+Aliased as `list`.
+```text
+idftool print-table partitions.bin        # from a file, offline
+idftool print-table                        # from the device
+idftool list                               # same thing
+idftool --partition-table-file partitions.csv print-table
+```
+
+#### `dump-table`
+Read the partition table from the connected device and save it. Defaults to
+CSV with an auto-generated filename; pass an output file or `--format` to
+choose otherwise.
+```text
+idftool dump-table                       # auto-named .csv
+idftool dump-table backup.bin
+idftool dump-table backup.csv --format csv
+```
+
+#### `write-table`
+Flash a partition table from a CSV or binary file to the device. The file is
+required, so this never reads the device's current table and writes it back
+to itself — use `dump-table` to pull the current table. The table is verified
+before flashing (override with `--force`).
+
+Only the partition map (at the partition table offset) is replaced; existing
+partition **data** on flash is not moved, resized, or erased, so a table that
+no longer matches the flash contents can make the device unbootable.
+```text
+idftool write-table partitions.csv
+idftool write-table partitions.bin --force
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

{idftool-0.2.2 → idftool-0.3.0}/idftool.egg-info/SOURCES.txt

@@ -18,4 +18,6 @@ idftool.egg-info/SOURCES.txt
 idftool.egg-info/dependency_links.txt
 idftool.egg-info/entry_points.txt
 idftool.egg-info/requires.txt
+idftool.egg-info/scm_file_list.json
+idftool.egg-info/scm_version.json
 idftool.egg-info/top_level.txt

idftool-0.3.0/idftool.egg-info/scm_file_list.json

@@ -0,0 +1,19 @@
+{
+  "files": [
+    "README.md",
+    "Makefile",
+    "idftool.spec",
+    "pyproject.toml",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE.md",
+    "idftool-onedir.spec",
+    ".gitignore",
+    "idftool.py",
+    "idftool/__init__.py",
+    "idftool/traceback.py",
+    "idftool/__main__.py",
+    ".github/workflows/build.yml",
+    ".github/workflows/publish.yml"
+  ]
+}

idftool-0.3.0/idftool.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.0",
+  "distance": 0,
+  "node": "gbf3a2f9bff2743367428ab9e8273189243b01ba5",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-15"
+}

idftool-0.2.2/CHANGELOG.md

@@ -1,48 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here. The format is
-based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
-this project adheres to [Semantic Versioning](https://semver.org/).
-
-## [v0.2.2] — 2026-06-15
-
-### Added
-- `print-image` — inspect a flash image file offline: prints the
-  partition table and, for each app partition that contains a valid
-  app, the project name, version, IDF version, compile time, ELF
-  SHA256, and target chip.
-- `print-bundle` — same output for a partition bundle ZIP, driven by
-  the embedded `partition_table.csv` and the per-partition `.bin`
-  entries.
-
-### Changed
-- Bumped `esp-idf-defs` to `~=0.1.3`. `print_partition_table` now takes
-  a `(offset, length) -> bytes` accessor instead of an `ESPLoader`
-  instance, so the same printing path serves device, image, and bundle
-  inspection.
-
-## [v0.2.1] — 2026-06-10
-
-### Changed
-- Boot partition state now uses `OtaImageState` for clearer reporting.
-
-## [v0.2.0] — 2026-05-26
-
-### Added
-- `create-nvs` and `write-nvs` commands for generating NVS partition
-  images from CSV.
-- Rich-style boxed traceback formatter for friendlier error output.
-
-### Documentation
-- README installation section and command index table.
-- Recommend `pipx` over the standalone binary for installation.
-
-## [v0.1.0] — 2026-05-25
-
-### Added
-- Initial release.
-
-[v0.2.2]: https://github.com/nebkat/idftool/releases/tag/v0.2.2
-[v0.2.1]: https://github.com/nebkat/idftool/releases/tag/v0.2.1
-[v0.2.0]: https://github.com/nebkat/idftool/releases/tag/v0.2.0
-[v0.1.0]: https://github.com/nebkat/idftool/releases/tag/v0.1.0