idftool 0.2.2__tar.gz → 0.5.0__tar.gz

idftool-0.5.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# 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.5.0] — 2026-07-17
+
+### Changed
+- The CLI is rebuilt on [click](https://click.palletsprojects.com/) and
+  [rich-click](https://github.com/ewels/rich-click) (like esptool): `--help`,
+  usage, and errors now render in boxed panels, and commands are grouped into
+  labelled sections. Command names, arguments, options, aliases (`reflash`,
+  `list`), and behaviour are unchanged — only the help/usage and error
+  formatting differ.
+
+### Added
+- `create-table` as an alias for `convert-table`.
+- `create-nvs` and `write-nvs` now accept a pre-built NVS binary image as
+  input (auto-detected), not only a CSV — it is validated against the
+  partition size and padded to it, instead of failing when parsed as CSV.
+- A test suite: an offline suite (no hardware) plus a real-device suite that
+  cycles every command against a connected ESP, with fixtures built from a
+  small ESP-IDF app (`make test-offline` / `make test-device`).
+
+### Fixed
+- `write-bundle` now reports a clear error when a bundle entry is larger than
+  its target partition, instead of crashing with an `AttributeError`.
+
+## [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.5.0]: https://github.com/nebkat/idftool/releases/tag/v0.5.0
+[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.5.0/Makefile

@@ -0,0 +1,62 @@
+.PHONY: build build-onefile test test-offline test-device test-device-full install install-onefile uninstall clean
+
+VENV         := .venv
+PYINSTALLER  := $(VENV)/bin/pyinstaller
+PREFIX       := $(HOME)/.local
+BINDIR       := $(PREFIX)/bin
+SHAREDIR     := $(PREFIX)/share/idftool
+
+# Device test config: `make test-device PORT=/dev/cu.usbmodem101 CHIP=esp32s3`
+PORT         :=
+CHIP         := esp32s3
+
+build: $(VENV)
+	$(PYINSTALLER) --noconfirm --distpath ./dist-onedir --workpath ./build-onedir idftool-onedir.spec
+
+build-onefile: $(VENV)
+	$(PYINSTALLER) --noconfirm --distpath ./dist --workpath ./build idftool.spec
+
+test: build
+	./dist-onedir/idftool/idftool --help >/dev/null
+
+# Offline test suite (no hardware).
+test-offline: $(VENV)
+	$(VENV)/bin/pip install -q -e ".[test]"
+	$(VENV)/bin/pytest test/test_offline.py
+
+# Real-device test suite (fast core: the quick per-command tests). Requires a connected board and
+# built fixtures (test/project/build_fixtures.sh). WILL ERASE THE DEVICE'S FLASH.
+test-device: $(VENV)
+	@test -n "$(PORT)" || { echo "Usage: make test-device PORT=/dev/... [CHIP=$(CHIP)]"; exit 2; }
+	$(VENV)/bin/pip install -q -e ".[test]"
+	$(VENV)/bin/pytest test/test_device.py --port $(PORT) --chip $(CHIP) -m "not slow"
+
+# Full device suite, including the slow full-flash dump-image / bundle round-trips. These move
+# megabytes and take many minutes (a full 16 MB dump-image is ~25 min on USB-Serial-JTAG boards).
+test-device-full: $(VENV)
+	@test -n "$(PORT)" || { echo "Usage: make test-device-full PORT=/dev/... [CHIP=$(CHIP)]"; exit 2; }
+	$(VENV)/bin/pip install -q -e ".[test]"
+	$(VENV)/bin/pytest test/test_device.py --port $(PORT) --chip $(CHIP)
+
+install: build
+	mkdir -p $(BINDIR)
+	rm -rf $(SHAREDIR)
+	mkdir -p $(dir $(SHAREDIR))
+	cp -R dist-onedir/idftool $(SHAREDIR)
+	ln -sf $(SHAREDIR)/idftool $(BINDIR)/idftool
+
+install-onefile: build-onefile
+	mkdir -p $(BINDIR)
+	cp dist/idftool $(BINDIR)/idftool
+
+uninstall:
+	rm -f $(BINDIR)/idftool
+	rm -rf $(SHAREDIR)
+
+clean:
+	rm -rf build build-onedir dist dist-onedir $(VENV)
+
+$(VENV):
+	python3 -m venv $(VENV)
+	$(VENV)/bin/pip install --upgrade pip
+	$(VENV)/bin/pip install -e . pyinstaller

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

@@ -1,15 +1,19 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.2.2
+Version: 0.5.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: click>=8.1
+Requires-Dist: rich-click>=1.8
 Requires-Dist: esptool~=5.2.0
 Requires-Dist: esp-idf-defs~=0.1.3
 Requires-Dist: esp-idf-nvs-partition-gen~=0.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
 Dynamic: license-file
 
 # idftool
@@ -103,7 +107,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 +130,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 +150,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 +310,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/PKG-INFO → idftool-0.5.0/README.md

@@ -1,17 +1,3 @@
-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)
@@ -103,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 |
@@ -126,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 |
@@ -141,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`
@@ -312,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