idftool 0.2.0__tar.gz → 0.2.2__tar.gz

idftool-0.2.2/CHANGELOG.md

@@ -0,0 +1,48 @@
+# 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: esptool~=5.2.0
-Requires-Dist: esp-idf-defs~=0.1.0
+Requires-Dist: esp-idf-defs~=0.1.3
 Requires-Dist: esp-idf-nvs-partition-gen~=0.2.0
 Dynamic: license-file
 
@@ -120,10 +120,12 @@ Setting boot partition to 'ota_1'...
 | [`create-image`](#create-image) | Merge partition binaries into a single flash image |
 | [`dump-image`](#dump-image) | Dump the entire flash to an image file |
 | [`write-image`](#write-image-alias-reflash) | Write a full flash image to the device |
+| [`print-image`](#print-image) | Print partition table and app info from a flash image file |
 | **Bundles** | |
 | [`create-bundle`](#create-bundle) | Pack partition images into a ZIP bundle |
 | [`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 |
 | **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 |
@@ -259,6 +261,15 @@ counterpart of `dump-image`.
 idftool write-image build/full-flash.img
 ```
 
+#### `print-image`
+Inspect a flash image file without touching a device: prints the
+partition table embedded in the image and, for each app partition that
+contains a valid app, the project name, version, IDF version, compile
+time, ELF SHA256, and target chip.
+```text
+idftool print-image build/full-flash.img
+```
+
 ### Bundles
 
 A bundle is a plain ZIP file containing one `*.bin` per partition (named
@@ -292,6 +303,15 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+#### `print-bundle`
+Inspect a bundle ZIP without touching a device: prints the partition
+table from the embedded `partition_table.csv` and, for each app
+partition whose `.bin` is present in the bundle, the project name,
+version, IDF version, compile time, ELF SHA256, and target chip.
+```text
+idftool print-bundle release.zip
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

idftool-0.2.0/PKG-INFO → idftool-0.2.2/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: idftool
-Version: 0.2.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
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE.md
-Requires-Dist: esptool~=5.2.0
-Requires-Dist: esp-idf-defs~=0.1.0
-Requires-Dist: esp-idf-nvs-partition-gen~=0.2.0
-Dynamic: license-file
-
 # idftool
 
 A CLI tool built on top of [`esptool`](https://github.com/espressif/esptool)
@@ -120,10 +106,12 @@ Setting boot partition to 'ota_1'...
 | [`create-image`](#create-image) | Merge partition binaries into a single flash image |
 | [`dump-image`](#dump-image) | Dump the entire flash to an image file |
 | [`write-image`](#write-image-alias-reflash) | Write a full flash image to the device |
+| [`print-image`](#print-image) | Print partition table and app info from a flash image file |
 | **Bundles** | |
 | [`create-bundle`](#create-bundle) | Pack partition images into a ZIP bundle |
 | [`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 |
 | **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 |
@@ -259,6 +247,15 @@ counterpart of `dump-image`.
 idftool write-image build/full-flash.img
 ```
 
+#### `print-image`
+Inspect a flash image file without touching a device: prints the
+partition table embedded in the image and, for each app partition that
+contains a valid app, the project name, version, IDF version, compile
+time, ELF SHA256, and target chip.
+```text
+idftool print-image build/full-flash.img
+```
+
 ### Bundles
 
 A bundle is a plain ZIP file containing one `*.bin` per partition (named
@@ -292,6 +289,15 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+#### `print-bundle`
+Inspect a bundle ZIP without touching a device: prints the partition
+table from the embedded `partition_table.csv` and, for each app
+partition whose `.bin` is present in the bundle, the project name,
+version, IDF version, compile time, ELF SHA256, and target chip.
+```text
+idftool print-bundle release.zip
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

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

@@ -3,7 +3,7 @@ import os.path
 import re
 import sys
 import time
-from typing import Optional, Literal
+from typing import Callable, Optional, Literal
 from zipfile import ZipFile
 
 from esptool import ESPLoader, CHIP_DEFS, flash_size_bytes
@@ -14,7 +14,7 @@ from serial.tools.list_ports_common import ListPortInfo
 from idftool.traceback import install as install_excepthook, print_exception
 
 from esp_idf_defs import ImageMetadata, ChipId
-from esp_idf_defs.otadata import OtaDataParameters, OtaDataSelectEntry
+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
@@ -451,7 +451,7 @@ def command_get_boot(esp: ESPLoader, partition_table: PartitionTable):
     if otadata.slot is None:
         print("OTA slot not set")
     else:
-        print(f"OTA slot 'ota_{otadata.slot}' (seq={otadata.otadata.seq}, state={otadata.otadata.ota_state})")
+        print(f"OTA slot 'ota_{otadata.slot}' (seq={otadata.otadata.seq}, state={otadata.otadata.ota_state.name})")
 
 def command_set_boot(esp: ESPLoader, partition_table: PartitionTable, label: str):
     otadata_partition, otadata = read_otadata(esp, partition_table)
@@ -465,6 +465,7 @@ def command_set_boot(esp: ESPLoader, partition_table: PartitionTable, label: str
 
     print(f"Setting boot partition to '{partition.name}'...")
     otadata = otadata.incremented_and_swapped(ota_slot)
+    otadata.otadata.ota_state = OtaImageState.VALID
     write_otadata(esp, otadata_partition, otadata)
 
 def command_clear_boot(esp: ESPLoader, partition_table: PartitionTable):
@@ -574,19 +575,7 @@ def command_app_info(app_binary_file: str):
     except ValueError as e:
         raise RuntimeError(f"Invalid application binary: {e}")
 
-    desc = image_metadata.app_description
-    header = image_metadata.header
-
-    print(f"Project name:     {desc.project_name}")
-    print(f"Version:          {desc.version}")
-    print(f"IDF version:      {desc.idf_version}")
-    print(f"Secure version:   {desc.secure_version}")
-    if desc.compiled:
-        print(f"Compiled:         {desc.compiled}")
-    print(f"ELF SHA256:       {desc.elf_sha256.hex()}")
-    max_rev = header.max_chip_rev_full if header.max_chip_rev_full != 0xFFFF else None
-    rev_range = f"rev {header.min_chip_rev_full} to {max_rev}" if max_rev else f"rev {header.min_chip_rev_full}+"
-    print(f"Chip:             {header.chip_id.name} ({rev_range})")
+    print_app_info(image_metadata.app_description, image_metadata.header)
 
 def command_write_image(esp: ESPLoader, bootloader_entry: PartitionDefinition, image_file_path: str):
     image_file = open(image_file_path, 'rb')
@@ -618,6 +607,130 @@ def command_write_image(esp: ESPLoader, bootloader_entry: PartitionDefinition, i
         flash_size='detect',
     )
 
+def print_app_info(desc, header, indent: str = ""):
+    print(f"{indent}Project name:     {desc.project_name}")
+    print(f"{indent}Version:          {desc.version}")
+    print(f"{indent}IDF version:      {desc.idf_version}")
+    print(f"{indent}Secure version:   {desc.secure_version}")
+    if desc.compiled:
+        print(f"{indent}Compiled:         {desc.compiled}")
+    print(f"{indent}ELF SHA256:       {desc.elf_sha256.hex()}")
+    max_rev = header.max_chip_rev_full if header.max_chip_rev_full != 0xFFFF else None
+    rev_range = f"rev {header.min_chip_rev_full} to {max_rev}" if max_rev else f"rev {header.min_chip_rev_full}+"
+    print(f"{indent}Chip:             {header.chip_id.name} ({rev_range})")
+
+def print_partition_table_and_apps(
+        partition_table: PartitionTable,
+        read: Callable[[int, int], bytes],
+):
+    print_partition_table(partition_table, read)
+
+    for part in partition_table:
+        if part.type != APP_TYPE:
+            continue
+        app_binary = read(part.offset, part.size)
+        try:
+            image_metadata = ImageMetadata.from_bytes(app_binary, app_required=True)
+        except (RuntimeError, ValueError):
+            continue
+        print()
+        print(f"Partition '{part.name}' (offset={part.offset:#x}):")
+        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)
+    with open(image_file_path, 'rb') as f:
+        f.seek(partition_table_offset)
+        partition_table_binary = f.read(partition_table_size)
+        try:
+            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
+
+        def read(offset: int, length: int) -> bytes:
+            if offset >= image_size:
+                return b"\xff" * length
+            f.seek(offset)
+            data = f.read(length)
+            if len(data) < length:
+                data += b"\xff" * (length - len(data))
+            return data
+
+        print(f"Image: {image_file_path} ({image_size:#x} bytes)")
+        print()
+        print_partition_table_and_apps(partition_table, read)
+
+def _extract_csv_bootloader_offsets(csv_text: str) -> tuple[Optional[int], Optional[int]]:
+    primary = recovery = None
+    for line in csv_text.splitlines():
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        parts = [p.strip() for p in line.split(',')]
+        if len(parts) < 4 or parts[1] != 'bootloader':
+            continue
+        try:
+            offset = int(parts[3], 0)
+        except ValueError:
+            continue
+        if parts[2] == 'primary' and primary is None:
+            primary = offset
+        elif parts[2] == 'recovery' and recovery is None:
+            recovery = offset
+    return primary, recovery
+
+def command_print_bundle(
+        bundle_file_path: str,
+        partition_table_offset: int,
+        primary_bootloader_offset: Optional[int],
+        recovery_bootloader_offset: Optional[int],
+):
+    bundle_size = os.path.getsize(bundle_file_path)
+    with ZipFile(bundle_file_path, 'r') 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')
+
+        # 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
+        # what the CSV says when the user didn't pass one.
+        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
+
+        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,
+        )
+
+        partition_data = {
+            name[:-4]: zf.read(name)
+            for name in names if name.endswith('.bin')
+        }
+
+        def read(offset: int, length: int) -> bytes:
+            for part in partition_table:
+                if part.offset <= offset < part.offset + part.size:
+                    local = offset - part.offset
+                    data = partition_data.get(part.name, b"")
+                    chunk = data[local:local + length]
+                    if len(chunk) < length:
+                        chunk += b"\xff" * (length - len(chunk))
+                    return chunk
+            return b"\xff" * length
+
+        included = sorted(partition_data.keys())
+        print(f"Bundle: {bundle_file_path} ({bundle_size:#x} bytes)")
+        print(f"Partitions included: {', '.join(included) if included else '(none)'}")
+        print()
+        print_partition_table_and_apps(partition_table, read)
+
 def command_dump_image(esp: ESPLoader, output_file: Optional[str]):
     flash_size = flash_size_bytes(detect_flash_size(esp))
 
@@ -689,6 +802,25 @@ def main(args):
         command_create_nvs(args.csv_file, args.size, args.output)
         return
 
+    # print-image inspects a local image file and needs neither device nor external partition table
+    if args.command == 'print-image':
+        command_print_image(
+            image_file_path=args.image_file,
+            partition_table_offset=args.partition_table_offset,
+            partition_table_size=args.partition_table_size,
+        )
+        return
+
+    # print-bundle inspects a local bundle ZIP and needs neither device nor external partition table
+    if args.command == 'print-bundle':
+        command_print_bundle(
+            bundle_file_path=args.bundle_file,
+            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
     esp = get_esp(port=args.port, baud=args.baud) if requires_esp else None
@@ -740,7 +872,7 @@ def main(args):
             pass
 
     # Print partition table
-    print_partition_table(partition_table, esp, otadata=otadata_params)
+    print_partition_table(partition_table, esp.read_flash if esp else None, otadata=otadata_params)
 
     if esp:
         flash_size_str = detect_flash_size(esp)
@@ -931,6 +1063,10 @@ def _main():
     write_image_parser = subparsers.add_parser('write-image', aliases=['reflash'], help='Write a full flash image to the device')
     write_image_parser.add_argument('image_file', help='Input file containing flash image')
 
+    # Print Image subcommand
+    print_image_parser = subparsers.add_parser('print-image', help='Print partition table and app info from a flash image file')
+    print_image_parser.add_argument('image_file', help='Input file containing flash image')
+
     # Create bundle subcommand
     create_bundle_parser = subparsers.add_parser('create-bundle', help='Create a ZIP bundle of partition binaries')
     create_bundle_parser.add_argument('-o', '--output', help='Output ZIP filename', dest='output_file', required=True)
@@ -950,6 +1086,10 @@ def _main():
     write_bundle_parser = subparsers.add_parser('write-bundle', help='Write a ZIP bundle of partition binaries')
     write_bundle_parser.add_argument('input_file', help='Input ZIP filename')
 
+    # Print Bundle subcommand
+    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')
+
     # 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')

idftool-0.2.0/README.md → idftool-0.2.2/idftool.egg-info/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.4
+Name: idftool
+Version: 0.2.2
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: esptool~=5.2.0
+Requires-Dist: esp-idf-defs~=0.1.3
+Requires-Dist: esp-idf-nvs-partition-gen~=0.2.0
+Dynamic: license-file
+
 # idftool
 
 A CLI tool built on top of [`esptool`](https://github.com/espressif/esptool)
@@ -106,10 +120,12 @@ Setting boot partition to 'ota_1'...
 | [`create-image`](#create-image) | Merge partition binaries into a single flash image |
 | [`dump-image`](#dump-image) | Dump the entire flash to an image file |
 | [`write-image`](#write-image-alias-reflash) | Write a full flash image to the device |
+| [`print-image`](#print-image) | Print partition table and app info from a flash image file |
 | **Bundles** | |
 | [`create-bundle`](#create-bundle) | Pack partition images into a ZIP bundle |
 | [`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 |
 | **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 |
@@ -245,6 +261,15 @@ counterpart of `dump-image`.
 idftool write-image build/full-flash.img
 ```
 
+#### `print-image`
+Inspect a flash image file without touching a device: prints the
+partition table embedded in the image and, for each app partition that
+contains a valid app, the project name, version, IDF version, compile
+time, ELF SHA256, and target chip.
+```text
+idftool print-image build/full-flash.img
+```
+
 ### Bundles
 
 A bundle is a plain ZIP file containing one `*.bin` per partition (named
@@ -278,6 +303,15 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+#### `print-bundle`
+Inspect a bundle ZIP without touching a device: prints the partition
+table from the embedded `partition_table.csv` and, for each app
+partition whose `.bin` is present in the bundle, the project name,
+version, IDF version, compile time, ELF SHA256, and target chip.
+```text
+idftool print-bundle release.zip
+```
+
 ### NVS
 
 idftool can generate a binary NVS (Non-Volatile Storage) partition image

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

@@ -1,4 +1,5 @@
 .gitignore
+CHANGELOG.md
 CONTRIBUTING.md
 LICENSE.md
 Makefile

{idftool-0.2.0 → idftool-0.2.2}/idftool.egg-info/requires.txt

@@ -1,3 +1,3 @@
 esptool~=5.2.0
-esp-idf-defs~=0.1.0
+esp-idf-defs~=0.1.3
 esp-idf-nvs-partition-gen~=0.2.0

{idftool-0.2.0 → idftool-0.2.2}/pyproject.toml

@@ -11,7 +11,7 @@
     dynamic = ["version"]
     dependencies = [
         "esptool~=5.2.0",
-        "esp-idf-defs~=0.1.0",
+        "esp-idf-defs~=0.1.3",
         "esp-idf-nvs-partition-gen~=0.2.0",
     ]