idftool 0.1.0__tar.gz → 0.2.0__tar.gz

{idftool-0.1.0 → idftool-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.1.0
+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
@@ -9,6 +9,7 @@ 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
@@ -39,9 +40,31 @@ especially when dealing with multiple devices/partition tables.
   partition binaries into a single ZIP; optionally flashing a partition
   table. `write-bundle` reflashes the lot in one command.
 
-> Pre-built binaries are published on the
-> [Releases](https://github.com/nebkat/idftool/releases) page.
-> See `CONTRIBUTING.md` for building from source.
+## Installation
+
+### pipx (recommended)
+
+[pipx](https://pipx.pypa.io) installs idftool into an isolated environment and
+puts it on your `PATH` automatically:
+
+```bash
+pipx install idftool
+```
+
+Install pipx first if you don't have it:
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install pipx` |
+| Windows | `winget install python.pipx` |
+| Linux / other | `pip install pipx` |
+
+### Binary
+
+If you don't have Python, download the pre-built binary from the
+[Releases](https://github.com/nebkat/idftool/releases) page. Prefer the `-dir`
+archive over the single-file download — it starts instantly rather than extracting
+itself on each run.
 
 ## At a glance
 
@@ -72,50 +95,41 @@ $ idftool set-boot ota_1
 Setting boot partition to 'ota_1'...
 ```
 
-## Global options
-
-These flags apply to every subcommand and go **before** the command name:
-
-| Flag | Purpose |
-|------|---------|
-| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
-| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
-| `--no-reset` | Skip the hard reset that normally happens after a command. |
-| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
-| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
-| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
-| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
-| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
-
-The commands `list`, `merge-bin`, and `create-bundle` will work **without**
-a device when you supply `--partition-table-file`; everything else needs a
-connected ESP.
-
-## Partition addressing
-
-Wherever a command takes a `partition` argument you can pass:
-
-- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
-- A **numeric address** that matches an existing partition's start
-  offset exactly — equivalent to looking the partition up by name, just
-  keyed on its address.
-- An **offset into a partition**: `name[offset]`. Negative values count
-  from the end. Sets the starting point for the operation. Accepted by
-  `write` and `merge-bin`.
-- A **slice of a partition**: `name[start:stop]`. Negative values count
-  from the end, and a `+N` stop is a length relative to `start`.
-  Accepted by `read`, `erase`, and `view`. Examples:
-  - `nvs[0:0x100]` — first 256 bytes of `nvs`
-  - `storage[-0x1000:]` — last 4 KiB of `storage`
-  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
-
-All numeric values in addresses, offsets, and sizes accept either
-decimal (`4096`) or hex (`0x1000`).
-
 ---
 
 ## Command reference
 
+| Command | Description |
+|---------|-------------|
+| **Discovery** | |
+| [`devices`](#devices) | List serial ports with hardware IDs |
+| [`list`](#list) | Print the partition table |
+| **Partition I/O** | |
+| [`read`](#read) | Read a partition (or slice) into a file |
+| [`write`](#write) | Write one or more files to named partitions |
+| [`erase`](#erase) | Erase a partition (or slice) |
+| [`view`](#view) | Pretty-print a partition's contents |
+| **Firmware** | |
+| [`ota`](#ota) | Push an app to the next OTA slot and switch to it |
+| [`factory`](#factory) | Flash an app to the factory partition |
+| **Boot selection** | |
+| [`get-boot`](#get-boot) | Show the currently-active OTA slot |
+| [`set-boot`](#set-boot) | Force the next boot to a specific OTA partition |
+| [`clear-boot`](#clear-boot) | Erase otadata and let the bootloader fall back |
+| **Images** | |
+| [`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 |
+| **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 |
+| **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 |
+| **Misc** | |
+| [`enter-bootloader`](#enter-bootloader) | Drop the chip into ROM bootloader mode |
+
 ### Discovery
 
 #### `devices`
@@ -278,6 +292,37 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+### NVS
+
+idftool can generate a binary NVS (Non-Volatile Storage) partition image
+from a CSV file, using the same format as ESP-IDF's
+[`nvs_partition_gen.py`](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_partition_gen.html).
+
+Example CSV:
+```csv
+key,type,encoding,value
+storage,namespace,,
+device_name,data,string,My Device
+device_id,data,u32,12345
+api_key,data,string,abc123def456
+```
+
+#### `create-nvs`
+Generate an NVS partition image from a CSV file, offline. Requires either
+`--size` (explicit partition size) or `--partition` (look up the size from
+the partition table — needs `--partition-table-file` or a device).
+```text
+idftool create-nvs nvs.csv -o nvs.bin --size 0x6000
+idftool --partition-table-file partitions.csv create-nvs nvs.csv -o nvs.bin --partition nvs
+```
+
+#### `write-nvs`
+Generate an NVS partition image from a CSV file and flash it to the named
+partition on the device.
+```text
+idftool write-nvs nvs nvs.csv
+```
+
 ### Misc
 
 #### `enter-bootloader`
@@ -291,3 +336,45 @@ isn't fully settled) are retried silently.
 idftool -p /dev/cu.usbmodem1101 enter-bootloader
 ```
 Requires `-p`/`--port`.
+
+--
+
+## Global options
+
+These flags apply to every subcommand and go **before** the command name:
+
+| Flag | Purpose |
+|------|---------|
+| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
+| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
+| `--no-reset` | Skip the hard reset that normally happens after a command. |
+| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
+| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
+| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
+| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
+| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
+
+The commands `list`, `merge-bin`, and `create-bundle` will work **without**
+a device when you supply `--partition-table-file`; everything else needs a
+connected ESP.
+
+## Partition addressing
+
+Wherever a command takes a `partition` argument you can pass:
+
+- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
+- A **numeric address** that matches an existing partition's start
+  offset exactly — equivalent to looking the partition up by name, just
+  keyed on its address.
+- An **offset into a partition**: `name[offset]`. Negative values count
+  from the end. Sets the starting point for the operation. Accepted by
+  `write` and `merge-bin`.
+- A **slice of a partition**: `name[start:stop]`. Negative values count
+  from the end, and a `+N` stop is a length relative to `start`.
+  Accepted by `read`, `erase`, and `view`. Examples:
+  - `nvs[0:0x100]` — first 256 bytes of `nvs`
+  - `storage[-0x1000:]` — last 4 KiB of `storage`
+  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
+
+All numeric values in addresses, offsets, and sizes accept either
+decimal (`4096`) or hex (`0x1000`).

{idftool-0.1.0 → idftool-0.2.0}/README.md

@@ -26,9 +26,31 @@ especially when dealing with multiple devices/partition tables.
   partition binaries into a single ZIP; optionally flashing a partition
   table. `write-bundle` reflashes the lot in one command.
 
-> Pre-built binaries are published on the
-> [Releases](https://github.com/nebkat/idftool/releases) page.
-> See `CONTRIBUTING.md` for building from source.
+## Installation
+
+### pipx (recommended)
+
+[pipx](https://pipx.pypa.io) installs idftool into an isolated environment and
+puts it on your `PATH` automatically:
+
+```bash
+pipx install idftool
+```
+
+Install pipx first if you don't have it:
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install pipx` |
+| Windows | `winget install python.pipx` |
+| Linux / other | `pip install pipx` |
+
+### Binary
+
+If you don't have Python, download the pre-built binary from the
+[Releases](https://github.com/nebkat/idftool/releases) page. Prefer the `-dir`
+archive over the single-file download — it starts instantly rather than extracting
+itself on each run.
 
 ## At a glance
 
@@ -59,50 +81,41 @@ $ idftool set-boot ota_1
 Setting boot partition to 'ota_1'...
 ```
 
-## Global options
-
-These flags apply to every subcommand and go **before** the command name:
-
-| Flag | Purpose |
-|------|---------|
-| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
-| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
-| `--no-reset` | Skip the hard reset that normally happens after a command. |
-| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
-| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
-| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
-| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
-| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
-
-The commands `list`, `merge-bin`, and `create-bundle` will work **without**
-a device when you supply `--partition-table-file`; everything else needs a
-connected ESP.
-
-## Partition addressing
-
-Wherever a command takes a `partition` argument you can pass:
-
-- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
-- A **numeric address** that matches an existing partition's start
-  offset exactly — equivalent to looking the partition up by name, just
-  keyed on its address.
-- An **offset into a partition**: `name[offset]`. Negative values count
-  from the end. Sets the starting point for the operation. Accepted by
-  `write` and `merge-bin`.
-- A **slice of a partition**: `name[start:stop]`. Negative values count
-  from the end, and a `+N` stop is a length relative to `start`.
-  Accepted by `read`, `erase`, and `view`. Examples:
-  - `nvs[0:0x100]` — first 256 bytes of `nvs`
-  - `storage[-0x1000:]` — last 4 KiB of `storage`
-  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
-
-All numeric values in addresses, offsets, and sizes accept either
-decimal (`4096`) or hex (`0x1000`).
-
 ---
 
 ## Command reference
 
+| Command | Description |
+|---------|-------------|
+| **Discovery** | |
+| [`devices`](#devices) | List serial ports with hardware IDs |
+| [`list`](#list) | Print the partition table |
+| **Partition I/O** | |
+| [`read`](#read) | Read a partition (or slice) into a file |
+| [`write`](#write) | Write one or more files to named partitions |
+| [`erase`](#erase) | Erase a partition (or slice) |
+| [`view`](#view) | Pretty-print a partition's contents |
+| **Firmware** | |
+| [`ota`](#ota) | Push an app to the next OTA slot and switch to it |
+| [`factory`](#factory) | Flash an app to the factory partition |
+| **Boot selection** | |
+| [`get-boot`](#get-boot) | Show the currently-active OTA slot |
+| [`set-boot`](#set-boot) | Force the next boot to a specific OTA partition |
+| [`clear-boot`](#clear-boot) | Erase otadata and let the bootloader fall back |
+| **Images** | |
+| [`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 |
+| **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 |
+| **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 |
+| **Misc** | |
+| [`enter-bootloader`](#enter-bootloader) | Drop the chip into ROM bootloader mode |
+
 ### Discovery
 
 #### `devices`
@@ -265,6 +278,37 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+### NVS
+
+idftool can generate a binary NVS (Non-Volatile Storage) partition image
+from a CSV file, using the same format as ESP-IDF's
+[`nvs_partition_gen.py`](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_partition_gen.html).
+
+Example CSV:
+```csv
+key,type,encoding,value
+storage,namespace,,
+device_name,data,string,My Device
+device_id,data,u32,12345
+api_key,data,string,abc123def456
+```
+
+#### `create-nvs`
+Generate an NVS partition image from a CSV file, offline. Requires either
+`--size` (explicit partition size) or `--partition` (look up the size from
+the partition table — needs `--partition-table-file` or a device).
+```text
+idftool create-nvs nvs.csv -o nvs.bin --size 0x6000
+idftool --partition-table-file partitions.csv create-nvs nvs.csv -o nvs.bin --partition nvs
+```
+
+#### `write-nvs`
+Generate an NVS partition image from a CSV file and flash it to the named
+partition on the device.
+```text
+idftool write-nvs nvs nvs.csv
+```
+
 ### Misc
 
 #### `enter-bootloader`
@@ -278,3 +322,45 @@ isn't fully settled) are retried silently.
 idftool -p /dev/cu.usbmodem1101 enter-bootloader
 ```
 Requires `-p`/`--port`.
+
+--
+
+## Global options
+
+These flags apply to every subcommand and go **before** the command name:
+
+| Flag | Purpose |
+|------|---------|
+| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
+| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
+| `--no-reset` | Skip the hard reset that normally happens after a command. |
+| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
+| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
+| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
+| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
+| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
+
+The commands `list`, `merge-bin`, and `create-bundle` will work **without**
+a device when you supply `--partition-table-file`; everything else needs a
+connected ESP.
+
+## Partition addressing
+
+Wherever a command takes a `partition` argument you can pass:
+
+- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
+- A **numeric address** that matches an existing partition's start
+  offset exactly — equivalent to looking the partition up by name, just
+  keyed on its address.
+- An **offset into a partition**: `name[offset]`. Negative values count
+  from the end. Sets the starting point for the operation. Accepted by
+  `write` and `merge-bin`.
+- A **slice of a partition**: `name[start:stop]`. Negative values count
+  from the end, and a `+N` stop is a length relative to `start`.
+  Accepted by `read`, `erase`, and `view`. Examples:
+  - `nvs[0:0x100]` — first 256 bytes of `nvs`
+  - `storage[-0x1000:]` — last 4 KiB of `storage`
+  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
+
+All numeric values in addresses, offsets, and sizes accept either
+decimal (`4096`) or hex (`0x1000`).

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

@@ -11,6 +11,8 @@ from serial import SerialException
 from serial.tools import list_ports
 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.partitions import PARTITION_TABLE_SIZE, PARTITION_TABLE_OFFSET, PartitionTable, print_partition_table, \
@@ -523,6 +525,48 @@ def command_factory(esp: ESPLoader, partition_table: PartitionTable, app_binary_
         print("Erasing 'otadata' partition...")
         esp.erase_region(offset=otadata_partition.offset, size=otadata_partition.size)
 
+def generate_nvs_image(csv_file: str, size: int) -> bytes:
+    import tempfile
+    from esp_idf_nvs_partition_gen import nvs_partition_gen
+
+    with tempfile.NamedTemporaryFile(suffix='.bin', delete=False) as tmp:
+        tmp_path = tmp.name
+    try:
+        nvs_args = argparse.Namespace(
+            input=csv_file,
+            output=os.path.basename(tmp_path),
+            outdir=os.path.dirname(tmp_path),
+            size=f"{size:#x}",
+            version=2,
+        )
+        nvs_partition_gen.generate(nvs_args)
+        with open(tmp_path, 'rb') as f:
+            return f.read()
+    finally:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+
+def command_create_nvs(csv_file: str, size: int, output_file: str):
+    print(f"Generating NVS image from '{csv_file}' (size={size:#x})...")
+    image = generate_nvs_image(csv_file, size)
+    with open(output_file, 'wb') as f:
+        f.write(image)
+    print(f"Wrote {len(image):#x} bytes to '{output_file}'")
+
+def command_write_nvs(
+        esp: ESPLoader,
+        partition_table: PartitionTable,
+        partition_table_entry: PartitionDefinition,
+        bootloader_entry: Optional[PartitionDefinition],
+        csv_file: str,
+        partition_name: str
+):
+    partition = get_partition(partition_table, partition_table_entry, bootloader_entry, partition_name)
+    print(f"Generating NVS image from '{csv_file}' for partition '{partition.name}' (size={partition.size:#x})...")
+    image = generate_nvs_image(csv_file, partition.size)
+    print(f"Writing NVS image to partition '{partition.name}' (offset={partition.offset:#x}, size={partition.size:#x})")
+    write_flash(esp=esp, addr_data=[(partition.offset, image)], flash_size='detect')
+
 def command_app_info(app_binary_file: str):
     app_binary = open(app_binary_file, 'rb').read()
     try:
@@ -640,8 +684,13 @@ def main(args):
         command_enter_bootloader(port=args.port, baud=args.baud)
         return
 
+    # create-nvs with explicit --size needs neither device nor partition table
+    if args.command == 'create-nvs' and args.size is not None:
+        command_create_nvs(args.csv_file, args.size, args.output)
+        return
+
     # Connect to ESP device if required
-    requires_esp = args.command not in ['list', 'create-image', 'create-bundle'] or not args.partition_table_file
+    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
     if not args.primary_bootloader_offset and esp:
         args.primary_bootloader_offset = esp.BOOTLOADER_FLASH_OFFSET
@@ -794,12 +843,25 @@ def main(args):
         command_factory(esp=esp, partition_table=partition_table, app_binary_file=args.app_binary_file)
     elif args.command == 'write-image':
         command_write_image(esp=esp, bootloader_entry=bootloader_entry, image_file_path=args.image_file)
+    elif args.command == 'create-nvs':
+        partition = get_partition(partition_table, partition_table_entry, bootloader_entry, args.partition)
+        command_create_nvs(args.csv_file, partition.size, args.output)
+    elif args.command == 'write-nvs':
+        command_write_nvs(
+            esp=esp,
+            partition_table=partition_table,
+            partition_table_entry=partition_table_entry,
+            bootloader_entry=bootloader_entry,
+            csv_file=args.csv_file,
+            partition_name=args.partition
+        )
     else:
         print(f"Unknown command: {args.command}", file=sys.stderr)
 
     if esp and not args.no_reset: esp.hard_reset()
 
 def _main():
+    install_excepthook()
     parser = argparse.ArgumentParser()
 
     parser.add_argument('-p', '--port', help='Serial port device')
@@ -888,6 +950,19 @@ 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')
 
+    # 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')
+    create_nvs_parser.add_argument('-o', '--output', required=True, help='Output binary filename (.bin)')
+    create_nvs_size_group = create_nvs_parser.add_mutually_exclusive_group(required=True)
+    create_nvs_size_group.add_argument('--size', type=auto_int, help='Partition size in bytes (e.g. 0x6000)')
+    create_nvs_size_group.add_argument('--partition', help='Partition name to read size from partition table')
+
+    # Write NVS subcommand
+    write_nvs_parser = subparsers.add_parser('write-nvs', help='Generate NVS partition image from CSV and write to device')
+    write_nvs_parser.add_argument('partition', help='NVS partition name')
+    write_nvs_parser.add_argument('csv_file', help='Input NVS CSV file')
+
     # Factory subcommand
     factory_parser = subparsers.add_parser('factory', help='Perform factory flash and clear boot partition')
     factory_parser.add_argument('app_binary_file', help='Input file containing app binary')
@@ -914,7 +989,13 @@ def _main():
         args.command = 'write-image'
     if args.command == 'enter-bootloader' and not args.port:
         parser.error("enter-bootloader requires -p/--port")
-    main(args)
+    try:
+        main(args)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BaseException as e:
+        print_exception(e)
+        sys.exit(1)
 
 if __name__ == "__main__":
     _main()

idftool-0.2.0/idftool/traceback.py

@@ -0,0 +1,114 @@
+import os
+import sys
+import traceback as _tb
+from types import TracebackType
+from typing import Optional
+
+
+def _term_width(default: int = 80) -> int:
+    try:
+        return os.get_terminal_size().columns
+    except OSError:
+        return default
+
+
+def _box(lines: list[str], title: str, width: int) -> list[str]:
+    inner = max(width - 4, 4)
+
+    title_str = f"─ {title} "
+    if len(title_str) + 3 <= width:
+        top = '╭' + title_str + '─' * (width - 2 - len(title_str)) + '╮'
+    else:
+        top = '╭' + '─' * (width - 2) + '╮'
+
+    body = []
+    for line in lines:
+        line = line.expandtabs(4)
+        if len(line) > inner:
+            line = line[:inner - 1] + '…'
+        body.append('│ ' + line.ljust(inner) + ' │')
+
+    bottom = '╰' + '─' * (width - 2) + '╯'
+
+    return [top] + body + [bottom]
+
+
+def _walk_chain(exc: BaseException) -> list[tuple[BaseException, Optional[str]]]:
+    """Walk __cause__ / __context__ chain, return (exception, separator_after) oldest-first."""
+    chain: list[tuple[BaseException, Optional[str]]] = []
+    e: Optional[BaseException] = exc
+    # First build a list of (exc, link_type_to_previous) from newest to oldest
+    newest_to_oldest: list[tuple[BaseException, Optional[str]]] = []
+    while e is not None:
+        if e.__cause__ is not None:
+            link = "cause"
+            prev: Optional[BaseException] = e.__cause__
+        elif not e.__suppress_context__ and e.__context__ is not None:
+            link = "context"
+            prev = e.__context__
+        else:
+            link = None
+            prev = None
+        newest_to_oldest.append((e, link))
+        e = prev
+
+    # Reverse to oldest-first. The link recorded with each exception describes
+    # how the NEXT (newer) exception relates to this one — i.e. the separator
+    # we should print AFTER this exception.
+    oldest_to_newest = list(reversed(newest_to_oldest))
+    result: list[tuple[BaseException, Optional[str]]] = []
+    for i, (exc_i, _) in enumerate(oldest_to_newest):
+        if i + 1 < len(oldest_to_newest):
+            next_link = oldest_to_newest[i + 1][1]
+            if next_link == "cause":
+                sep: Optional[str] = "The above exception was the direct cause of the following exception:"
+            else:
+                sep = "During handling of the above exception, another exception occurred:"
+        else:
+            sep = None
+        result.append((exc_i, sep))
+    return result
+
+
+def _format_one(exc: BaseException, *, color: bool, width: int) -> list[str]:
+    frames = _tb.extract_tb(exc.__traceback__)
+    frame_lines = [f"in {f.name}:{f.lineno}  ({f.filename})" for f in frames]
+    if not frame_lines:
+        frame_lines = ["<no traceback available>"]
+
+    box_lines = _box(frame_lines, "Traceback (most recent call last)", width)
+    err_line = f"{type(exc).__name__}: {exc}"
+
+    if color:
+        box_lines = [f"\033[2m{l}\033[0m" for l in box_lines]
+        err_line = f"\033[1;31m{err_line}\033[0m"
+
+    return box_lines + [err_line]
+
+
+def print_exception(exc: BaseException) -> None:
+    """Print an exception (and its chain) in rich-style boxed format to stderr."""
+    color = sys.stderr.isatty()
+    width = min(_term_width(), 120)
+
+    chain = _walk_chain(exc)
+    for i, (e, sep) in enumerate(chain):
+        if i > 0:
+            print(file=sys.stderr)
+        for line in _format_one(e, color=color, width=width):
+            print(line, file=sys.stderr)
+        if sep is not None:
+            print(file=sys.stderr)
+            print(sep, file=sys.stderr)
+
+
+def _excepthook(exc_type: type, exc_value: BaseException, exc_tb: Optional[TracebackType]) -> None:
+    if issubclass(exc_type, KeyboardInterrupt):
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+        return
+    print_exception(exc_value)
+
+
+def install() -> None:
+    """Replace sys.excepthook with a rich-style boxed formatter."""
+    sys.excepthook = _excepthook

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 0.1.0
+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
@@ -9,6 +9,7 @@ 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
@@ -39,9 +40,31 @@ especially when dealing with multiple devices/partition tables.
   partition binaries into a single ZIP; optionally flashing a partition
   table. `write-bundle` reflashes the lot in one command.
 
-> Pre-built binaries are published on the
-> [Releases](https://github.com/nebkat/idftool/releases) page.
-> See `CONTRIBUTING.md` for building from source.
+## Installation
+
+### pipx (recommended)
+
+[pipx](https://pipx.pypa.io) installs idftool into an isolated environment and
+puts it on your `PATH` automatically:
+
+```bash
+pipx install idftool
+```
+
+Install pipx first if you don't have it:
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install pipx` |
+| Windows | `winget install python.pipx` |
+| Linux / other | `pip install pipx` |
+
+### Binary
+
+If you don't have Python, download the pre-built binary from the
+[Releases](https://github.com/nebkat/idftool/releases) page. Prefer the `-dir`
+archive over the single-file download — it starts instantly rather than extracting
+itself on each run.
 
 ## At a glance
 
@@ -72,50 +95,41 @@ $ idftool set-boot ota_1
 Setting boot partition to 'ota_1'...
 ```
 
-## Global options
-
-These flags apply to every subcommand and go **before** the command name:
-
-| Flag | Purpose |
-|------|---------|
-| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
-| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
-| `--no-reset` | Skip the hard reset that normally happens after a command. |
-| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
-| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
-| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
-| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
-| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
-
-The commands `list`, `merge-bin`, and `create-bundle` will work **without**
-a device when you supply `--partition-table-file`; everything else needs a
-connected ESP.
-
-## Partition addressing
-
-Wherever a command takes a `partition` argument you can pass:
-
-- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
-- A **numeric address** that matches an existing partition's start
-  offset exactly — equivalent to looking the partition up by name, just
-  keyed on its address.
-- An **offset into a partition**: `name[offset]`. Negative values count
-  from the end. Sets the starting point for the operation. Accepted by
-  `write` and `merge-bin`.
-- A **slice of a partition**: `name[start:stop]`. Negative values count
-  from the end, and a `+N` stop is a length relative to `start`.
-  Accepted by `read`, `erase`, and `view`. Examples:
-  - `nvs[0:0x100]` — first 256 bytes of `nvs`
-  - `storage[-0x1000:]` — last 4 KiB of `storage`
-  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
-
-All numeric values in addresses, offsets, and sizes accept either
-decimal (`4096`) or hex (`0x1000`).
-
 ---
 
 ## Command reference
 
+| Command | Description |
+|---------|-------------|
+| **Discovery** | |
+| [`devices`](#devices) | List serial ports with hardware IDs |
+| [`list`](#list) | Print the partition table |
+| **Partition I/O** | |
+| [`read`](#read) | Read a partition (or slice) into a file |
+| [`write`](#write) | Write one or more files to named partitions |
+| [`erase`](#erase) | Erase a partition (or slice) |
+| [`view`](#view) | Pretty-print a partition's contents |
+| **Firmware** | |
+| [`ota`](#ota) | Push an app to the next OTA slot and switch to it |
+| [`factory`](#factory) | Flash an app to the factory partition |
+| **Boot selection** | |
+| [`get-boot`](#get-boot) | Show the currently-active OTA slot |
+| [`set-boot`](#set-boot) | Force the next boot to a specific OTA partition |
+| [`clear-boot`](#clear-boot) | Erase otadata and let the bootloader fall back |
+| **Images** | |
+| [`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 |
+| **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 |
+| **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 |
+| **Misc** | |
+| [`enter-bootloader`](#enter-bootloader) | Drop the chip into ROM bootloader mode |
+
 ### Discovery
 
 #### `devices`
@@ -278,6 +292,37 @@ to match) instead of reading the table from flash.
 idftool write-bundle release.zip
 ```
 
+### NVS
+
+idftool can generate a binary NVS (Non-Volatile Storage) partition image
+from a CSV file, using the same format as ESP-IDF's
+[`nvs_partition_gen.py`](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_partition_gen.html).
+
+Example CSV:
+```csv
+key,type,encoding,value
+storage,namespace,,
+device_name,data,string,My Device
+device_id,data,u32,12345
+api_key,data,string,abc123def456
+```
+
+#### `create-nvs`
+Generate an NVS partition image from a CSV file, offline. Requires either
+`--size` (explicit partition size) or `--partition` (look up the size from
+the partition table — needs `--partition-table-file` or a device).
+```text
+idftool create-nvs nvs.csv -o nvs.bin --size 0x6000
+idftool --partition-table-file partitions.csv create-nvs nvs.csv -o nvs.bin --partition nvs
+```
+
+#### `write-nvs`
+Generate an NVS partition image from a CSV file and flash it to the named
+partition on the device.
+```text
+idftool write-nvs nvs nvs.csv
+```
+
 ### Misc
 
 #### `enter-bootloader`
@@ -291,3 +336,45 @@ isn't fully settled) are retried silently.
 idftool -p /dev/cu.usbmodem1101 enter-bootloader
 ```
 Requires `-p`/`--port`.
+
+--
+
+## Global options
+
+These flags apply to every subcommand and go **before** the command name:
+
+| Flag | Purpose |
+|------|---------|
+| `-p`, `--port PATH` | Serial port device. If omitted, idftool auto-picks one. |
+| `-b`, `--baud N` | Serial baud rate (defaults to esptool's ROM baud, 115200). |
+| `--no-reset` | Skip the hard reset that normally happens after a command. |
+| `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading it off the device. |
+| `--partition-table-offset OFFSET` | Where to expect the partition table in flash (default `0x8000`). |
+| `--partition-table-size SIZE` | Size of the partition table region (default `0x1000`). |
+| `--primary-bootloader-offset OFFSET` | Primary bootloader offset, or a chip name like `esp32s3` to pick a default. Only needed when addressing the `bootloader` partition by name in **offline** mode (`--partition-table-file` with no device); auto-detected from a connected chip otherwise. |
+| `--recovery-bootloader-offset OFFSET` | Recovery bootloader offset; same scope as `--primary-bootloader-offset`. |
+
+The commands `list`, `merge-bin`, and `create-bundle` will work **without**
+a device when you supply `--partition-table-file`; everything else needs a
+connected ESP.
+
+## Partition addressing
+
+Wherever a command takes a `partition` argument you can pass:
+
+- A **name** from the partition table (`nvs`, `ota_0`, `storage`, …).
+- A **numeric address** that matches an existing partition's start
+  offset exactly — equivalent to looking the partition up by name, just
+  keyed on its address.
+- An **offset into a partition**: `name[offset]`. Negative values count
+  from the end. Sets the starting point for the operation. Accepted by
+  `write` and `merge-bin`.
+- A **slice of a partition**: `name[start:stop]`. Negative values count
+  from the end, and a `+N` stop is a length relative to `start`.
+  Accepted by `read`, `erase`, and `view`. Examples:
+  - `nvs[0:0x100]` — first 256 bytes of `nvs`
+  - `storage[-0x1000:]` — last 4 KiB of `storage`
+  - `ota_0[0x1000:+0x800]` — 2 KiB starting 4 KiB into `ota_0`
+
+All numeric values in addresses, offsets, and sizes accept either
+decimal (`4096`) or hex (`0x1000`).

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

@@ -11,6 +11,7 @@ pyproject.toml
 .github/workflows/publish.yml
 idftool/__init__.py
 idftool/__main__.py
+idftool/traceback.py
 idftool.egg-info/PKG-INFO
 idftool.egg-info/SOURCES.txt
 idftool.egg-info/dependency_links.txt

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

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

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

@@ -12,6 +12,7 @@
     dependencies = [
         "esptool~=5.2.0",
         "esp-idf-defs~=0.1.0",
+        "esp-idf-nvs-partition-gen~=0.2.0",
     ]
 
 [project.scripts]