idftool 1.0.0__tar.gz → 1.2.0__tar.gz

{idftool-1.0.0 → idftool-1.2.0}/CHANGELOG.md

@@ -4,6 +4,39 @@ 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/).
 
+## [v1.2.0] — 2026-10-01
+
+### Added
+- `IDFTOOL_PROBE=1` probes by default; `--no-probe` skips it.
+- `dump-bundle` includes the bootloader.
+- `write` and `write-bundle` check that apps and bootloaders are the right kind
+  of image for the chip. `--force` writes them anyway.
+- `print-image`, `print-bundle` and `app-info` show which chip the bootloader
+  is for.
+- Bundles take `@factory.bin` and `@ota.bin`, which flash like `factory` and
+  `ota`.
+- Bundles take an optional `manifest.json`: a name, the target chip, and ops
+  that set NVS keys, edit files, erase partitions and set the boot slot.
+- `--hmac-key` reads and writes NVS encrypted with the HMAC key protection
+  scheme.
+- `write-bundle` checks every partition name before writing, and writes the
+  partition table only if it differs. A manifest can ask first, or refuse a
+  device whose layout differs.
+
+### Changed
+- Partition names can't start with `@`.
+- Every write skips what's already in flash and rewrites only the sectors that
+  changed, not just `ota` and `factory`. `write-image` is unchanged.
+
+## [v1.1.0] — 2026-09-30
+
+### Added
+- `idf.py`, `esptool` and `espefuse` run Espressif's tools on the selected device.
+- Plugins define how devices are named, from custom probing (e.g. eFuse, NVS).
+
+### Changed
+- `monitor` and `idf.py` use `-b` when it's given.
+
 ## [v1.0.0] — 2026-09-29
 
 ### Added
@@ -367,6 +400,8 @@ this project adheres to [Semantic Versioning](https://semver.org/).
 ### Added
 - Initial release.
 
+[v1.2.0]: https://github.com/nebkat/idftool/releases/tag/v1.2.0
+[v1.1.0]: https://github.com/nebkat/idftool/releases/tag/v1.1.0
 [v1.0.0]: https://github.com/nebkat/idftool/releases/tag/v1.0.0
 [v0.10.0]: https://github.com/nebkat/idftool/releases/tag/v0.10.0
 [v0.9.0]: https://github.com/nebkat/idftool/releases/tag/v0.9.0

{idftool-1.0.0/idftool.egg-info → idftool-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: idftool
-Version: 1.0.0
+Version: 1.2.0
 Summary: The ultimate CLI tool for interacting with Espressif devices
 License-Expression: Apache-2.0
 Project-URL: Source, https://github.com/nebkat/idftool
@@ -14,6 +14,7 @@ Requires-Dist: esptool<6,>=5.4
 Requires-Dist: esp-idf-defs~=0.1.5
 Requires-Dist: esp-pylib<2,>=1.1.4
 Requires-Dist: esp-idf-nvs-partition-gen<0.4,>=0.1.9
+Requires-Dist: cryptography>=3.1
 Requires-Dist: esp-idf-monitor<2,>=1.4
 Requires-Dist: pyfatfs~=1.1
 Requires-Dist: littlefs-python~=0.19
@@ -62,7 +63,7 @@ No more guessing which device is on which port. Run any command without `-p`
 and `idftool` lists the connected devices and asks which to use:
 
 ```console
-$ idftool ota build/app.bin
+$ idftool monitor
 ? Select device (↑↓ move · ↵ select · p probe · r refresh · k kill · q quit)
  » /dev/cu.usbmodem11401         ESP USB-Serial/JTAG   7c:2c:67:92:79:c0
    /dev/cu.usbmodem2101          ESP USB-Serial/JTAG   b8:f8:62:49:ea:14
@@ -76,15 +77,21 @@ Pick one, and it tells you how to skip the question next time:
 
 ```console
 Device: /dev/cu.usbmodem11401 — ESP USB-Serial/JTAG · 7c:2c:67:92:79:c0
-Re-run with: idftool -p /dev/cu.usbmodem11401 ota build/app.bin
-         or: idftool -m 7c:2c:67:92:79:c0 ota build/app.bin
-...
-Writing 'my-app v1.2.0' to partition 'ota_1'...
-Setting boot partition to 'ota_1'...
+Re-run with: idftool -p /dev/cu.usbmodem11401 monitor
+         or: idftool -m 7c:2c:67:92:79:c0 monitor
+--- esp-idf-monitor 1.10.0 on /dev/cu.usbmodem11401 115200
+--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H
 ```
 
 The `-m` form finds the board by its MAC address, wherever it's plugged in.
 
+It works with `idf.py` too. Alias it, and every `flash` or `monitor` asks which
+device to use:
+
+```bash
+alias idf.py='idftool idf.py'
+```
+
 ### Firmware flashing
 
 Flash to the default (factory) or next available (OTA) app partition, with no

{idftool-1.0.0 → idftool-1.2.0}/README.md

@@ -33,7 +33,7 @@ No more guessing which device is on which port. Run any command without `-p`
 and `idftool` lists the connected devices and asks which to use:
 
 ```console
-$ idftool ota build/app.bin
+$ idftool monitor
 ? Select device (↑↓ move · ↵ select · p probe · r refresh · k kill · q quit)
  » /dev/cu.usbmodem11401         ESP USB-Serial/JTAG   7c:2c:67:92:79:c0
    /dev/cu.usbmodem2101          ESP USB-Serial/JTAG   b8:f8:62:49:ea:14
@@ -47,15 +47,21 @@ Pick one, and it tells you how to skip the question next time:
 
 ```console
 Device: /dev/cu.usbmodem11401 — ESP USB-Serial/JTAG · 7c:2c:67:92:79:c0
-Re-run with: idftool -p /dev/cu.usbmodem11401 ota build/app.bin
-         or: idftool -m 7c:2c:67:92:79:c0 ota build/app.bin
-...
-Writing 'my-app v1.2.0' to partition 'ota_1'...
-Setting boot partition to 'ota_1'...
+Re-run with: idftool -p /dev/cu.usbmodem11401 monitor
+         or: idftool -m 7c:2c:67:92:79:c0 monitor
+--- esp-idf-monitor 1.10.0 on /dev/cu.usbmodem11401 115200
+--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H
 ```
 
 The `-m` form finds the board by its MAC address, wherever it's plugged in.
 
+It works with `idf.py` too. Alias it, and every `flash` or `monitor` asks which
+device to use:
+
+```bash
+alias idf.py='idftool idf.py'
+```
+
 ### Firmware flashing
 
 Flash to the default (factory) or next available (OTA) app partition, with no

{idftool-1.0.0 → idftool-1.2.0}/docs/guide/backups-and-releases.md

@@ -34,7 +34,8 @@ This reads the whole chip, which can take a long time on a large flash.
 idftool write-bundle esp32-s3-7c2c679279c0-20260929-143000.zip
 ```
 
-This writes every partition and the partition table from the bundle.
+This writes every partition, the bootloader and the partition table from the
+bundle, skipping what's already there.
 
 From an image:
 
@@ -71,6 +72,11 @@ idftool write-bundle release.zip
 `--flash-partition-table` includes the partition table, so a device with an
 older layout is updated to match.
 
+For a field update, name the app `@ota` instead of a partition, so it goes to
+whichever OTA slot is next. A [manifest](../reference/bundles.md#manifest) can
+also set NVS keys, edit files, and control when the partition table may
+change.
+
 ## Clone a device
 
 Back up one board and restore the bundle onto another:

{idftool-1.0.0 → idftool-1.2.0}/docs/guide/choosing-a-device.md

@@ -40,7 +40,8 @@ The list comes from USB alone, so no board is reset by looking at it:
 | ++q++ | Quit |
 
 `--probe` connects to every port up front instead, so the chip column is filled
-for all of them.
+for all of them. Set `IDFTOOL_PROBE=1` to make that the default, and pass
+`--no-probe` to skip it for one run.
 
 After you pick, `idftool` prints how to skip the picker next time:
 
@@ -87,3 +88,18 @@ On Windows, FTDI's driver adds a channel letter to the serial number
 
 For boards on their built-in USB port the serial number is the MAC, so `-m` and
 `--usb-serial` find the same port.
+
+## With `idf.py`
+
+[`idftool idf.py`](../reference/idf-py.md) runs ESP-IDF's `idf.py` and asks for
+a device when the actions need one:
+
+```bash
+idftool idf.py build flash monitor
+```
+
+Alias it to put every `idf.py` call through the device list:
+
+```bash
+alias idf.py='idftool idf.py'
+```

idftool-1.2.0/docs/guide/plugins.md

@@ -0,0 +1,57 @@
+# Plugins
+
+A plugin names devices your own way, for example from your eFuse fields or a
+config partition. It's an installed Python package that registers an
+`identify` function:
+
+```toml title="pyproject.toml"
+[project.entry-points."idftool.identify"]
+chip-description = "idftool_chip_description:identify"
+```
+
+```python title="idftool_chip_description.py"
+def identify(esp):
+    return esp.get_chip_description()
+```
+
+This is the full example in
+[`examples/identify-plugin`](https://github.com/nebkat/idftool/tree/main/examples/identify-plugin).
+Install it next to `idftool` and probe:
+
+```console
+$ pip install ./examples/identify-plugin
+$ idftool devices --probe
+Port                    Device                            Chip      MAC
+/dev/cu.usbmodem11201   ESP32-S3 (QFN56) (revision v0.2)  ESP32-S3  90:e5:b1:cd:47:bc
+```
+
+## When it runs
+
+`identify` is called with a connected `ESPLoader` whenever a board is probed:
+`--probe`, or ++p++ in the [picker](choosing-a-device.md#the-picker). It never
+runs otherwise, so installing a plugin resets no extra boards.
+
+The loader is esptool's ROM loader. It reads eFuses and registers, but on most
+chips not flash. For that, start the stub first:
+
+```python
+def identify(esp):
+    esp = esp if esp.IS_STUB else esp.run_stub()
+    data = esp.read_flash(0x9000, 0x1000)
+    ...
+```
+
+## What it returns
+
+A string naming the device, shown in place of the chip name. `None` means
+"not one of mine": the next plugin gets a turn, then the chip name is shown.
+
+Plugins run in order of entry point name, and the first one that isn't `None`
+wins. A plugin that fails to import or raises is shown as the device's error,
+unless another plugin names it.
+
+## Standalone binaries
+
+Plugins load from the Python environment `idftool` is installed in, so they
+don't reach the standalone binaries. Install `idftool` with `pip` or `pipx`
+(`pipx inject idftool ./my-plugin`) to use them.

{idftool-1.0.0 → idftool-1.2.0}/docs/index.md

@@ -102,7 +102,7 @@ with. `idftool` does that for you.
 Run any command without `-p`, and `idftool` asks which device to use:
 
 ```console
-$ idftool ota build/my-app.bin
+$ idftool monitor
 ? Select device (↑↓ move · ↵ select · p probe · r refresh · k kill · q quit)
  » /dev/cu.usbmodem11401         ESP USB-Serial/JTAG   7c:2c:67:92:79:c0
    /dev/cu.usbmodem2101          ESP USB-Serial/JTAG   b8:f8:62:49:ea:14

{idftool-1.0.0 → idftool-1.2.0}/docs/library.md

@@ -67,8 +67,11 @@ state.port = found["port"]
 ```
 
 `identify` needs a connection, so every port is probed (and reset) when it's
-given. If it raises, the device is still listed and usable, with the error
-next to it.
+given, unless `probe=False`: then it runs only on ports probed with `p`. If it
+raises, the device is still listed and usable, with the error next to it.
+
+`State(identify=...)` uses it in the picker the same way as the CLI uses
+[plugins](guide/plugins.md).
 
 ## Available functions
 

idftool-1.2.0/docs/reference/bundles.md

@@ -0,0 +1,145 @@
+# Bundles
+
+A bundle is a ZIP whose filenames say what to flash. Use them to hand a build
+from CI to whoever flashes it, or to archive exactly what shipped.
+
+| File | Flashing it |
+|------|-------------|
+| `partition_table.csv` or `.bin` | Replaces the partition table, if it differs. Written first. |
+| `bootloader.bin` | Writes the bootloader. |
+| `@factory.bin` | Flashes the app to the factory partition (or `ota_0`) and clears otadata, like [`factory`](firmware.md#factory). |
+| `@ota.bin` | Writes the app to the next OTA slot and boots it, like [`ota`](firmware.md#ota). |
+| `<name>.bin` | Writes the partition called `name`. |
+| `manifest.json` | Optional: a name, the target chip, table rules and extra ops. See [Manifest](#manifest). |
+
+```text
+release.zip
+├── partition_table.csv
+├── @ota.bin
+└── storage.bin
+```
+
+They're written in that order. A bundle can't have both `@factory.bin` and
+`@ota.bin`, or name a partition the role file may write. Partition names can't
+start with `@`. Files in subdirectories are only used by manifest ops.
+
+Before anything is written, every app and bootloader is checked against the
+chip, and every partition the bundle names must exist in the table it will
+meet: the bundle's own, else the device's.
+
+## Manifest
+
+```json
+{
+  "name": "MS5 v0.17.0",
+  "description": "Field update: new app, reset the channel",
+  "chip": "esp32s3",
+  "ops": [
+    {"op": "set-nvs", "partition": "nvs_cfg", "set": {"cfg:channel": "string:stable"}},
+    {"op": "edit-fs", "partition": "storage", "put": {"/config.json": "files/config.json"}},
+    {"op": "clear-boot"}
+  ]
+}
+```
+
+All fields are optional. `chip` is checked against the device. `ops` run in
+order after the files:
+
+| Op | Fields | Does |
+|----|--------|------|
+| `write` | `partition`, `file` | Write a file to a partition. |
+| `erase` | `partition` | Erase a partition. |
+| `write-fs` | `partition`, `file` | Write a filesystem image. |
+| `edit-fs` | `partition`, `put`, `delete` | Put files (path → file in the bundle) in the filesystem, and delete paths. |
+| `set-nvs` | `partition`, `set`, `delete` | Set keys (`ns:key` → `type:value`, or a bare value for a key that exists) and delete them. Without `partition`, the first NVS partition. |
+| `set-boot` | `partition` | Boot that OTA slot next. |
+| `clear-boot` | | Clear otadata so the factory app boots. |
+
+### Partition table rules
+
+A table that already matches the device's isn't written. `table` says what
+happens when it differs:
+
+- `update` (default): write it.
+- `ask`: show the differences and ask. `-y` answers yes.
+- `require`: never write it, and refuse the device.
+
+`tableMatch` says which differences count: `exact` (default) for any, or `used`
+for only the partitions the bundle writes, erases, edits or boots. With `used`,
+a device that differs elsewhere keeps its own table.
+
+## `create-bundle`
+
+Pack partition binaries into a bundle. `@factory` and `@ota` add a role file.
+`--flash-partition-table` includes the partition table CSV so
+[`write-bundle`](#write-bundle) flashes it too. `--manifest` adds a
+`manifest.json` and the files its ops name, relative to it.
+
+```bash
+idftool --partition-table-file partitions.csv create-bundle \
+  -o release.zip --flash-partition-table \
+  ota_0 build/app.bin storage build/spiffs.bin
+```
+
+## `dump-bundle`
+
+Read every partition off the device into a bundle, always with
+`bootloader.bin` and `partition_table.csv`. Without a filename it's named
+`{chip}-{mac}-{timestamp}.zip`.
+
+```bash
+idftool dump-bundle                 # auto-named
+idftool dump-bundle my-backup.zip
+```
+
+## `write-bundle`
+
+Flash a bundle. It prints the steps first, then checks everything against the
+device before the first write. `--hmac-key` is the key for an
+[encrypted NVS](nvs.md#encrypted-nvs) partition that a `set-nvs` op edits;
+bundles never carry keys.
+
+```bash
+idftool write-bundle release.zip
+```
+
+Takes the [write options](write-options.md).
+
+## `print-bundle`
+
+Inspect a bundle without a device: its manifest, the steps flashing it takes,
+its bootloader's chip, its partition table if it has one, and the app
+descriptions.
+
+```console
+$ idftool print-bundle -f release.zip
+Bundle: release.zip (0x2828d bytes)
+Partition table: partition_table.csv
+Steps:
+  1. Write the partition table (partition_table.csv) if it differs
+  2. Write ota_0.bin to partition 'ota_0'
+Partitions included: ota_0
+
+Bootloader: none
+
+╭──────────┬──────┬─────────┬─────────┬──────┬───────────────╮
+│ Name     │ Type │ Subtype │  Offset │ Size │ App           │
+├──────────┼──────┼─────────┼─────────┼──────┼───────────────┤
+│ nvs      │ data │ nvs     │  0x9000 │  24K │               │
+│ otadata  │ data │ ota     │  0xf000 │   8K │               │
+│ phy_init │ data │ phy     │ 0x11000 │   4K │               │
+│ factory  │ app  │ factory │ 0x20000 │ 192K │ empty         │
+│ ota_0    │ app  │ ota_0   │ 0x50000 │ 192K │ my-app 1.2.0  │
+│ ota_1    │ app  │ ota_1   │ 0x80000 │ 192K │ empty         │
+│ storage  │ data │ spiffs  │ 0xb0000 │  64K │               │
+╰──────────┴──────┴─────────┴─────────┴──────┴───────────────╯
+
+Partition 'ota_0' (offset=0x50000):
+  Project name:     my-app
+  Version:          1.2.0
+  IDF version:      v6.0.2
+  Secure version:   0
+  Compiled:         Sep 29 2026 14:30:00
+  ELF SHA256:       4fd8f31259d82483f0fc34d4422b1aefb6ead9da845395d5ea96a135ed32c78a
+  Chip:             ESP32S3 (rev 0 to 99)
+```

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/discovery.md

@@ -33,10 +33,12 @@ Location
 Piped, it prints plain space-separated columns instead of a box, for `awk` and
 friends.
 
-### `--probe`
+### `--probe`, `--no-probe`
 
 Connect to every port to add each board's chip and MAC, including boards behind
-a USB-serial adapter. This resets the boards.
+a USB-serial adapter. This resets the boards. With a
+[plugin](../guide/plugins.md) installed, a Device column shows what it names
+each board. Defaults to the global `--probe`, or `IDFTOOL_PROBE`.
 
 ```console
 $ idftool devices --probe

idftool-1.2.0/docs/reference/espefuse.md

@@ -0,0 +1,18 @@
+# espefuse
+
+## `espefuse`
+
+Run [`espefuse`](https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/)
+using `idftool`'s [device selection](../guide/choosing-a-device.md).
+
+```bash
+idftool espefuse summary
+idftool -m 9c:13:9e:1b:d4:6c espefuse summary --format json
+```
+
+Everything after `espefuse` goes to `espefuse`. A `-p` given there is used
+as-is, without the picker. `-b` and `--no-reset`, if given, are passed on as
+`--baud` and `--after no-reset`.
+
+`-y` only skips the picker. `espefuse` still asks before burning; pass it
+`--do-not-confirm` to skip that.

idftool-1.2.0/docs/reference/esptool.md

@@ -0,0 +1,17 @@
+# esptool
+
+## `esptool`
+
+Run [`esptool`](https://docs.espressif.com/projects/esptool/en/latest/esp32/)
+using `idftool`'s [device selection](../guide/choosing-a-device.md).
+Commands that don't need a device, like `merge-bin` or `image-info`, run
+straight away.
+
+```bash
+idftool esptool chip-id
+idftool -m 9c:13:9e:1b:d4:6c esptool read-flash 0 0x1000 boot.bin
+```
+
+Everything after `esptool` goes to `esptool`. A `-p` or `--port-filter` given
+there is used as-is, without the picker. `-b` and `--no-reset`, if given, are
+passed on as `--baud` and `--after no-reset`.

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/firmware.md

@@ -68,6 +68,7 @@ Print the app description of a bare application binary, without a device:
 project name, version, IDF version, compile time, ELF SHA-256, and target
 chip. The same block [`print-image`](images.md#print-image) and
 [`print-bundle`](bundles.md#print-bundle) print for each app partition.
+Given a bootloader, it prints which chip it's for.
 Alias: `print-app`.
 
 ```console

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/global-options.md

@@ -11,8 +11,8 @@ idftool -p /dev/cu.usbmodem1101 --no-reset get-boot
 | `-p`, `--port PATH` | Serial port. Without it, `idftool` asks; see [Choosing a device](../guide/choosing-a-device.md). |
 | `-m`, `--mac MAC` | Use the device with this MAC address. See [by MAC address](../guide/choosing-a-device.md#by-mac-address). |
 | `--usb-serial SERIAL` | Use the port with this USB serial number. See [by USB serial number](../guide/choosing-a-device.md#by-usb-serial-number). |
-| `-b`, `--baud N` | Serial baud rate for flashing. Default 115200, the ROM bootloader's rate. See [serial connection](https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/serial-connection.html). |
-| `--probe` | Connect to every port to identify its board. Resets them. |
+| `-b`, `--baud N` | Serial baud rate for flashing. Default 115200, the ROM bootloader's rate. See [serial connection](https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/serial-connection.html). If given, also passed to [`monitor`](monitor.md#monitor) and [`idf.py`](idf-py.md#idfpy). |
+| `--probe`, `--no-probe` | Connect to every port to identify its board. Resets them. Defaults to `IDFTOOL_PROBE` (`1` to probe). |
 | `-y`, `--yes` | Don't ask which device to use. |
 | `--no-reset` | Skip the [hard reset](https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/advanced-options.html#reset-after-operation-after) after a command. Also passed to [`monitor`](monitor.md#monitor). |
 | `--partition-table-file PATH` | Use a CSV or binary partition table from disk instead of reading the device's. |

idftool-1.2.0/docs/reference/idf-py.md

@@ -0,0 +1,21 @@
+# idf.py
+
+## `idf.py`
+
+Run [`idf.py`](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-py.html)
+using `idftool`'s [device selection](../guide/choosing-a-device.md).
+Actions that don't need a device, like `build` or `menuconfig`, run straight
+away.
+
+```bash
+idftool idf.py build flash monitor
+idftool -m 9c:13:9e:1b:d4:6c idf.py app-flash
+```
+
+`-b`, if given, is passed on as `idf.py -b`, the flashing baud rate.
+
+Alias it to run every `idf.py` through `idftool`:
+
+```bash
+alias idf.py='idftool idf.py'
+```

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/images.md

@@ -64,14 +64,16 @@ Takes the [write options](write-options.md).
 
 ## `print-image`
 
-Inspect a flash image without a device: the partition table inside it and, for
-each app partition holding a valid app, its project name, version, IDF version,
-compile time, ELF SHA-256, and target chip.
+Inspect a flash image without a device: which chip its bootloader is for, the
+partition table inside it and, for each app partition holding a valid app, its
+project name, version, IDF version, compile time, ELF SHA-256, and target chip.
 
 ```console
 $ idftool print-image -f build/full-flash.img
 Image: build/full-flash.img (0xc0000 bytes)
 
+Bootloader: ESP32S3 (offset=0x0)
+
 ╭──────────┬──────┬─────────┬─────────┬──────┬───────────────╮
 │ Name     │ Type │ Subtype │  Offset │ Size │ App           │
 ├──────────┼──────┼─────────┼─────────┼──────┼───────────────┤

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/index.md

@@ -15,8 +15,6 @@ options. The options shared by every command are under
 | [`set-boot`](firmware.md#set-boot) | Force the next boot to a specific OTA partition |
 | [`clear-boot`](firmware.md#clear-boot) | Erase otadata and let the bootloader fall back |
 | [`app-info`](firmware.md#app-info) | Print the app description from an application binary |
-| **[Monitor](monitor.md)** | |
-| [`monitor`](monitor.md#monitor) | Open [`esp-idf-monitor`](https://github.com/espressif/esp-idf-monitor) on the selected device |
 | **[Partition I/O](partition-io.md)** | |
 | [`read`](partition-io.md#read) | Read a partition (or slice) into a file |
 | [`write`](partition-io.md#write) | Write one or more files to named partitions |
@@ -30,8 +28,8 @@ options. The options shared by every command are under
 | **[Bundles](bundles.md)** | |
 | [`create-bundle`](bundles.md#create-bundle) | Pack partition images into a ZIP bundle |
 | [`dump-bundle`](bundles.md#dump-bundle) | Pack every partition from the device into a ZIP |
-| [`write-bundle`](bundles.md#write-bundle) | Flash every binary in a bundle ZIP |
-| [`print-bundle`](bundles.md#print-bundle) | Print partition table and app info from a bundle ZIP |
+| [`write-bundle`](bundles.md#write-bundle) | Flash a bundle ZIP |
+| [`print-bundle`](bundles.md#print-bundle) | Print what a bundle ZIP holds and what flashing it does |
 | **[Partition table](partition-table.md)** | |
 | [`print-table`](partition-table.md#print-table) | Print a partition table from a file or the device (alias `list`) |
 | [`create-table`](partition-table.md#create-table) | Convert a partition table between CSV and binary |
@@ -53,3 +51,12 @@ options. The options shared by every command are under
 | [`print-fs`](filesystems.md#print-fs) | List the contents of a filesystem partition or image |
 | **[Misc](misc.md)** | |
 | [`enter-bootloader`](misc.md#enter-bootloader) | Drop the chip into ROM bootloader mode |
+
+## Tools
+
+Espressif's tools, run on the selected device.
+
+- [`monitor`](monitor.md#monitor) (aliases `esp-idf-monitor`, `idf-monitor`)
+- [`idf.py`](idf-py.md#idfpy)
+- [`esptool`](esptool.md#esptool)
+- [`espefuse`](espefuse.md#espefuse)

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/monitor.md

@@ -1,9 +1,10 @@
-# Monitor
+# esp-idf-monitor
 
 ## `monitor`
 
-Run [`esp-idf-monitor`](https://github.com/espressif/esp-idf-monitor) on the
-device picked by `-p`, `-m`, or the [picker](../guide/choosing-a-device.md).
+Run [`esp-idf-monitor`](https://github.com/espressif/esp-idf-monitor)
+using `idftool`'s [device selection](../guide/choosing-a-device.md).
+Aliases: `esp-idf-monitor`, `idf-monitor`.
 
 ```bash
 idftool monitor
@@ -17,7 +18,7 @@ its options. A `-p` given there is used as-is, without the picker.
 `--no-reset` is passed through, so combined with the picker (which doesn't
 reset boards) you can attach to a running device without rebooting it.
 
-`idftool`'s `-b` is the flashing baud rate and isn't passed on. Give the
-monitor's own after `monitor`: `idftool monitor -b 460800`.
+`-b` sets the monitor's baud rate, the same as giving it after `monitor`:
+`idftool -b 460800 monitor`. Without it, the monitor uses its own default.
 
 Quit with ++ctrl+bracket-right++.

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/nvs.md

@@ -26,9 +26,20 @@ api_key,data,string,abc123def456
 Don't pad the columns with spaces: `nvs_partition_gen` doesn't accept them in
 the header.
 
-!!! note
-    Encrypted NVS isn't supported yet. Every command here works on plaintext
-    NVS only.
+## Encrypted NVS
+
+For NVS encrypted with the HMAC key protection scheme
+(`CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`), give every command `--hmac-key`: the
+key burned into the HMAC eFuse, as 64 hex digits or a file holding the raw 32
+bytes or the digits. Images are decrypted when read and encrypted when written.
+
+```bash
+idftool write-nvs nvs example.csv --hmac-key hmac_key.bin
+idftool get-nvs nvs storage:device_id --hmac-key hmac_key.bin
+```
+
+Without the key, an encrypted partition is refused rather than read as garbage.
+Flash encryption-based NVS keys aren't supported.
 
 ## `create-nvs`
 

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/partition-io.md

@@ -16,7 +16,9 @@ idftool read 'storage[-0x1000:]' tail.bin
 
 Write files to partitions. Arguments come in `PARTITION FILE` pairs; repeat
 them to flash several partitions in one go. Each file is checked to fit its
-partition before anything is written.
+partition before anything is written. A file for an app partition or the
+bootloader must be an app or a bootloader built for this chip; `--force` writes
+it anyway.
 
 ```bash
 idftool write ota_0 build/app.bin storage build/spiffs.bin

{idftool-1.0.0 → idftool-1.2.0}/docs/reference/write-options.md

@@ -22,9 +22,9 @@ idftool write storage build/spiffs.bin --diff --no-progress
 
 ## Skipping what's already there
 
-`ota` and `factory` turn on `--skip-flashed` and `--diff` by default, so
-reflashing the same build is nearly instant and a small change rewrites only
-the sectors it touched. Other commands leave both off unless asked.
+`--skip-flashed` and `--diff` are on by default for every command except
+`write-image`, so reflashing the same thing is nearly instant and a small
+change rewrites only the sectors it touched.
 
 `--skip-flashed`
 :   Hashes the partition on the device and compares it with the file, like
@@ -42,8 +42,8 @@ the sectors it touched. Other commands leave both off unless asked.
 `--skip-flashed` unless the erase is off: nothing can match a chip that was
 just wiped. See [`write-image`](images.md#write-image).
 
-`write-table` doesn't take these. Its `--force` already means "flash a table
-that failed verification".
+`write-table` doesn't take these, and always skips a table that's already in
+flash. Its `--force` already means "flash a table that failed verification".
 
 From Python, the same names work as keyword arguments. See
 [Python library](../library.md#write-options).