Enhancements for the esp32_flash task

CHANGELOG.md

@@ -21,13 +21,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added dialyzer task to simplify running dialyzer on AtomVM applications.
 - Added support for rp2350 devices to allow for default detection of the device mount path.
 - Added configuration paramenter for setting the path to picotool for the pico_flash task.
+- Added `app_partition` parameter to `esp32_flash` task. This is only needed to be provided for
+custom partition tables that do not use `main.avm` for the beam application partition name, or to
+flash to a custom alternate partition.
 
 ### Changed
 - The `uf2create` task now creates `universal` format uf2 files by default, suitable for both
 rp2040 or rp2350 devices.
 - The `pico_flash` task now checks that a device is an RP2 platform before resetting to `BOOTSEL`
 mode, preventing interference with other MCUs that may be attached to the host system.
 - The `pico_flash` task now aborts on all errors rather than trying to continue after a failure.
+- The `offset` used by the `esp32_flash` task is now read from the partition table of the device.
+When this parameter is provided it will be used to verify the offset of the application partition on
+flash matches the expected value.
+- The `esp32_flash` task now uses auto discovery for the `port` by default.
+- Stacktraces are not shown by default if the `esp32_flash` fails, instead a descriptive error
+message is displayed. To view the stacktrace use diagnostic mode.
+
+### Fixed
+- The `esp32_flash` task aborts when an error occurs, rather than attempt to continue after a step
+has failed.
 
 ## [0.7.5] (2025.05.27)
 

Makefile

@@ -14,7 +14,7 @@ doc:
 	rebar3 as doc ex_doc
 
 etest:
-	cd test && ./run.sh
+	cd test && TEST=1 ./run.sh
 
 clean:
 	rm -rf _build

README.md

@@ -260,24 +260,32 @@ Running this AVM file will boot the `myapp` application automatically, without h
 
 You may use the `esp32_flash` task to flash the generated AtomVM packbeam application to the flash storage on an ESP32 device connected over a serial connection.
 
-    shell$ rebar3 help atomvm esp32_flash
-
-    Use this plugin to flash an AtomVM packbeam file to an ESP32 device.
-
-    Usage: rebar3 atomvm esp32_flash [-e <esptool>] [-c <chip>] [-p <port>]
-                                    [-b <baud>] [-o <offset>]
-
-    -e, --esptool  Path to esptool.py
-    -c, --chip     ESP chip (default auto)
-    -p, --port     Device port (default /dev/ttyUSB0)
-    -b, --baud     Baud rate (default 115200)
-    -o, --offset   Offset (default 0x210000)
+```shell
+shell$ rebar3 help atomvm esp32_flash
+
+Use this plugin to flash an AtomVM packbeam file to an ESP32 device.
+
+Usage: rebar3 atomvm esp32_flash [-e <esptool>] [-c <chip>] [-p <port>]
+                                 [-b <baud>] [-o <offset>]
+                                 [-a <app_partition>]
+
+  -e, --esptool        Path to esptool.py
+  -c, --chip           ESP chip (default auto)
+  -p, --port           Device port (default auto discovery)
+  -b, --baud           Baud rate (default 115200)
+  -o, --offset         Offset (default read from device) *deprecated, use
+                       app_partition. When given, a warning will be issued
+                       if the partition name does not match the expected
+                       name, as long as the offset aligns with a valid
+                       application partition.
+  -a, --app_partition  Application partition name (default main.avm)
+```
 
 The `esp32_flash` task will use the `esptool.py` command to flash the ESP32 device.  This tool is available via the <a href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32/">IDF SDK</a>, or directly via <a href="https://github.com/espressif/esptool">github</a>.  The `esptool.py` command is also available via many package managers (e.g., MacOS Homebrew).
 
-By default, the `esp32_flash` task will assume the `esptool.py` command is available on the user's executable path.  Alternatively, you may specify the full path to the `esptool.py` command via the `-e` (or `--esptool`) option
+By default, the `esp32_flash` task will assume the `esptool.py` command is available on the user's executable path.  Alternatively, you may specify the full path to the `esptool.py` command via the `-e` (or `--esptool`) option.
 
-By default, the `esp32_flash` task will write to port `/dev/ttyUSB0` at a baud rate of `115200`.  You may control the port and baud settings for connecting to your ESP device via the `-port` and `-baud` options to the `esp32_flash` task, e.g.,
+By default, the `esp32_flash` task uses port auto discovery at a baud rate of `115200`.  You may control the port and baud settings for connecting to your ESP device via the `--port` and `--baud` options to the `esp32_flash` task, e.g.,
 
     shell$ rebar3 atomvm esp32_flash --port /dev/tty.SLAB_USBtoUART --baud 921600
     ...
@@ -306,7 +314,8 @@ The following table enumerates the properties that may be defined in your projec
 | `chip` | `string()` | ESP32 chip type |
 | `port` | `string()` | Device port on which the ESP32 can be located |
 | `baud` | `integer()` | Device BAUD rate |
-| `offset` | `string()` | Offset into which to write AtomVM application |
+| `offset` | `string()` | Optionally verify offset on flash matches expected value. Original behavior deprecated: use `app_partition` for custom images or to target a different partition |
+| `app_partition` | `string()` | Name of application partition to write AtomVM application for custom partition tables |
 
 Example:
 
@@ -319,9 +328,24 @@ Alternatively, the following environment variables may be used to control the ab
 * `ATOMVM_REBAR3_PLUGIN_ESP32_FLASH_PORT`
 * `ATOMVM_REBAR3_PLUGIN_ESP32_FLASH_BAUD`
 * `ATOMVM_REBAR3_PLUGIN_ESP32_FLASH_OFFSET`
+* `ATOMVM_REBAR3_PLUGIN_ESP32_APP_PARTITION`
 
 Any setting specified on the command line take precedence over settings in `rebar.config`, which in turn take precedence over environment variable settings, which in turn take precedence over the default values specified above.
 
+```note
+The  behavior of the `offset` configuration option has changed, the correct offset for standard
+AtomVM builds are determined by the partition table flashed to the device. Elixir supported builds
+are recognized and the correct offset will be used. When using a custom partition table it is
+necessary to supply the `app_partition` name. If an offset is given it will be compared to the
+address of the discovered `app_partition` and an warning will be given if they do not match, but as
+long as the offset aligns to the beginning of a `data` partition with a valid subtype it will be
+used. Currently any subtype not reserved for another purpose (such as `fat`, `nvs`, or ESP-IDF
+defined subtypes) are considered valid. AtomVM release images use subtype `phy` for the `main.avm`
+BEAM application partition, but it is not necessary to supply the name when using a release image
+or one of the standard partition tables, or custom tables that use the name `main.avm` for the app
+partition.
+```
+
 The `esp32_flash` task depends on the `packbeam` task, so the packbeam file will get automatically built if any changes have been made to its dependencies.
 
 ### The `stm32_flash` task

UPDATING.md

@@ -6,6 +6,17 @@
 
 # `atomvm_rebar3_plugin` Update Instructions
 
+## (unreleased)
+
+- The `esp32_flash` task now reads the application `offset` from the partition table on the device.
+If you are using a custom partition table that does not use `main.avm` for the application partition
+name you should supply the name used with the `app_partition` parameter. An `offset` may optionally
+be supplied to assure the offset of the application partition matches the expected offset, this may
+be helpful to assure that specific applications are only flashed to devices with a custom build of
+AtomVM.
+- Pico 2 (RP2350) devices are recognized and now work with default parameters. Specifying device
+path and uf2 flavor for these chipsets is no longer necessary.
+
 ## 0.6.* -> 0.7.*
 
 - The `atomvm_rebar3_plugin` tasks have been moved into the `atomvm` namespace (from the [`rebar3`](https://rebar3.org) `default` namespace).  The "legacy" tasks in the `default` namespace are deprecated, and users will be issued a warning when used.  Be sure to use the `atomvm` namespace in any future usage of this plugin, as the deprecated tasks may be removed without warning.  E.g., `rebar3 atomvm packbeam ...`