Allow provisioning ESP32 nvs partition when building

Adds the option to provision nvs partition data at build time for the esp32 platform. If the file
`nvs_partition.csv` is found in the AtomVM/src/platforms/esp32 directory when building; the nvs
partition will be created and added to the `idf.py flash` task as well as to the configuration for
the mkimage.sh script in the build directory. An example file is provided and `nvs_partition.csv`
is added to `.gitignore` to prevent accidentally pushing secrets to remote repositories.

Signed-off-by: Winford <[email protected]>

Author: UncleGrumpy

CHANGELOG.md

@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `binary:match/2` and `binary:match/3`
 - Added `supervisor:which_children/1`
 - Added ESP32 `-DATOMVM_ELIXIR_SUPPORT=on` configuration option
+- Added support for ESP32 development builds to include NVS partition data at build time
 
 ### Changed
 

doc/src/build-instructions.md

@@ -304,6 +304,71 @@ partitions and the flash partitions layout see [Flash Layout](#flash-layout) bel
 
 To build a single binary image file see [Building a Release Image](#building-a-release-image), below.
 
+#### NVS Partition Provisioning
+
+For streamlining deployment of images for an environment developers may pre-provision NVS partition
+data. This is done by creating a file in the AtomVM/src/platforms/esp32 directory named
+`nvs_partition.csv`, an example called `nvs_partition.csv-example` is provided in the same
+directory. If this file exists it will be included by the mkimage.sh script in the build directory.
+The partition is not included in the `idf.py flash` task so that settings made by applications can
+be retained. To update changes or restore to the defaults defined in `nvs_partition.csv` delete the
+generated `build/nvs.bin` file (if present) and execute the command `idf.py nvs-flash`.
+
+This is a more detailed example, with explanations of the structure:
+
+```{csv}
+key,type,encoding,value
+network,namespace,,
+ssid,data,binary,"NETWORK_NAME"
+psk,data,binary,"PASSWORD"
+settings,namespace,,
+feature0,data,binary,"1"
+extra_feature,data,binary,"0"
+token,file,binary,/path/to/file
+```
+
+Let's break this down line by line:
+
+```csv
+key,type,encoding,value
+```
+This is the header describing the columns. It is important that there is no whitespace at the end of each line
+and none separating the commas (`,`) throughout this file.
+
+```csv
+network,namespace,,
+```
+The first entry should have a "key" name and have type "namespace". The namespaces are the same
+used to look up the keys with
+[esp:nvs_get_binary/2 (or /3)](./apidocs/erlang/eavmlib/esp.md#nvs_get_binary2). Note that the
+`encoding` and `value` are empty.
+
+```csv
+ssid,data,binary,"NETWORK_NAME"
+...
+```
+The keys must use encoding type `binary` as this is the only type currently supported by AtomVM.
+
+```csv
+settings,namespace,,
+...
+```
+Multiple namespaces may be used for separation, followed by their keys.
+
+```csv
+token,file,binary,/path/to/file
+```
+External file contents may be included
+
+The initial values flashed to the `nvs` partition may be changed by applications using
+[esp:nvs_put_binary/3](./apidocs/erlang/eavmlib/esp.md#nvs_put_binary3). If you wish to make
+changes to the partition data and re-flash without rebuilding and flashing the entire AtomVM build
+you may delete the generated `build/nvs.bin` file and run `idf.py nvs-flash`, this will regenerate
+and flash the `nvs` partition.
+
+For more information about the format of this file see Espressif's
+[documentation for the NVS generator file format](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_partition_gen.html#csv-file-format).
+
 ### Running tests for ESP32
 
 Tests for ESP32 are run on the desktop (or CI) using qemu.

src/platforms/esp32/.gitignore

@@ -5,3 +5,4 @@
 
 sdkconfig.defaults
 sdkconfig.old
+nvs_partition.csv

src/platforms/esp32/CMakeLists.txt

@@ -95,3 +95,7 @@ if (NOT ("${BOOT_LIBS}" STREQUAL "NONE"))
     partition_table_get_partition_info(lib_offset "--partition-name boot.avm" "offset")
     esptool_py_flash_target_image(flash boot.avm "${lib_offset}" "${BOOT_LIB_PATH}")
 endif()
+
+if (EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/nvs_partition.csv)
+    nvs_create_partition_image(nvs ${CMAKE_CURRENT_SOURCE_DIR}/nvs_partition.csv)
+endif()

src/platforms/esp32/nvs_partition.csv-example

@@ -0,0 +1,4 @@
+key,type,encoding,value
+network,namespace,,
+ssid,data,string,"NETWORK_NAME"
+psk,data,string,"PASSWORD"

src/platforms/esp32/nvs_partition.csv-example.license

@@ -0,0 +1,2 @@
+SPDX-License-Identifier: Apache-2.0
+SPDX-FileCopyrightText: AtomVM Contributors

src/platforms/esp32/tools/CMakeLists.txt

@@ -57,7 +57,11 @@ endif()
 
 set(ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../")
 
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.config.in ${CMAKE_BINARY_DIR}/mkimage.config)
+if (EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/../nvs_partition.csv)
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage_nvs.config.in ${CMAKE_BINARY_DIR}/mkimage.config)
+else()
+    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.config.in ${CMAKE_BINARY_DIR}/mkimage.config)
+endif()
 
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/flash.sh.in ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/flash.sh @ONLY)
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/mkimage.erl ${CMAKE_BINARY_DIR}/mkimage.erl COPYONLY)

src/platforms/esp32/tools/mkimage_nvs.config.in

@@ -0,0 +1,50 @@
+%
+% This file is part of AtomVM.
+%
+% Copyright 2020-2021 Fred Dushin <[email protected]>
+% Copyright 2025 Winford (UncleGrumpy) <[email protected]>
+%
+% Licensed under the Apache License, Version 2.0 (the "License");
+% you may not use this file except in compliance with the License.
+% You may obtain a copy of the License at
+%
+%    http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS,
+% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+% See the License for the specific language governing permissions and
+% limitations under the License.
+%
+% SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+%
+
+#{
+    segments => [
+        #{
+            name => "bootloader",
+            offset => "${BOOTLOADER_OFFSET}",
+            path => ["${BUILD_DIR}/bootloader/bootloader.bin"]
+        },
+        #{
+            name => "partition-table",
+            offset => "0x8000",
+            path => ["${BUILD_DIR}/partition_table/partition-table.bin", "${BUILD_DIR}/partitions.bin"]
+        },
+        #{
+            name => "nvs",
+            offset => "0x9000",
+            path => ["${BUILD_DIR}/nvs.bin"]
+        },
+        #{
+            name => "AtomVM Virtual Machine",
+            offset => "0x10000",
+            path => ["${BUILD_DIR}/atomvm-esp32.bin", "${ROOT_DIR}/src/platforms/esp32/build/atomvm-esp32.bin"]
+        },
+        #{
+            name => "AtomVM Boot and Core BEAM Library",
+            offset =>  "0x1D0000",
+            path => ["${ROOT_DIR}/build/libs/esp32boot/${BOOT_LIBS}"]
+        }
+    ]
+}.