Merge branch 'update/nvs_example' into 'master'

refactor(nvs_examples): refactor nvs storage examples and add nvs_console example

See merge request espressif/esp-idf!37978

Author: pacucha42

docs/en/api-guides/bootloader.rst

@@ -186,6 +186,6 @@ The current bootloader implementation allows a project to extend it or modify it
 
 In the bootloader space, you cannot use the drivers and functions from other components unless they explicitly support run in bootloader. If necessary, then the required functionality should be placed in the project's `bootloader_components` directory (note that this will increase its size). Examples of components that can be used in the bootloader are:
 
-* :example:`storage/nvs_bootloader`
+* :example:`storage/nvs/nvs_bootloader`
 
 If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by default. Increase the :ref:`partition table offset <CONFIG_PARTITION_TABLE_OFFSET>` value to place the partition table later in the flash. This increases the space available for the bootloader.

docs/en/api-guides/file-system-considerations.rst

@@ -181,8 +181,8 @@ Points to keep in mind when developing NVS related code:
 
 **Examples:**
 
-- :example:`storage/nvs_rw_value` demonstrates how to use NVS to write and read a single integer value.
-- :example:`storage/nvs_rw_blob` demonstrates how to use NVS to write and read a blob.
+- :example:`storage/nvs/nvs_rw_value` demonstrates how to use NVS to write and read a single integer value.
+- :example:`storage/nvs/nvs_rw_blob` demonstrates how to use NVS to write and read a blob.
 - :example:`security/nvs_encryption_hmac` demonstrates NVS encryption using the HMAC peripheral, where the encryption keys are derived from the HMAC key burnt in eFuse.
 - :example:`security/flash_encryption` demonstrates the flash encryption workflow including NVS partition creation and usage.
 

docs/en/api-reference/storage/index.rst

@@ -47,16 +47,18 @@ Examples
 
     * - **Code Example**
       - **Description**
-    * - :example:`nvs_rw_blob <storage/nvs_rw_blob>`
+    * - :example:`nvs_rw_blob <storage/nvs/nvs_rw_blob>`
       - Shows the use of the C-style API to read and write blob data types in NVS flash.
-    * - :example:`nvs_rw_value <storage/nvs_rw_value>`
+    * - :example:`nvs_rw_value <storage/nvs/nvs_rw_value>`
       - Shows the use of the C-style API to read and write integer data types in NVS flash.
-    * - :example:`nvs_rw_value_cxx <storage/nvs_rw_value_cxx>`
+    * - :example:`nvs_rw_value_cxx <storage/nvs/nvs_rw_value_cxx>`
       - Shows the use of the C++-style API to read and write integer data types in NVS flash.
-    * - :example:`nvs_bootloader <storage/nvs_bootloader>`
+    * - :example:`nvs_bootloader <storage/nvs/nvs_bootloader>`
       - Shows the use of the API available to the bootloader code to read NVS data.
-    * - :example:`nvsgen <storage/nvsgen>`
+    * - :example:`nvsgen <storage/nvs/nvsgen>`
       - Demonstrates how to use the Python-based NVS image generation tool to create an NVS partition image from the contents of a CSV file.
+    * - :example:`nvs_console <storage/nvs/nvs_console>`
+      - Demonstrates how to use NVS through an interactive console interface.
 
 .. list-table:: Common Filesystem API
     :widths: 25 75

docs/en/api-reference/storage/nvs_bootloader.rst

@@ -37,7 +37,7 @@ Applications are expected to follow the steps below in order to enable decryptio
 Application Example
 -------------------
 
-You can find code examples in :example:`storage/nvs_bootloader` (in the :example:`storage` directory of ESP-IDF examples).
+You can find code examples in :example:`storage/nvs/nvs_bootloader` (in the :example:`storage/nvs` directory of ESP-IDF examples).
 
 This section demonstrates how to prepare data in the input-output structure for various data types, namespaces, and keys. It includes an example of reading string data from NVS.
 

docs/en/api-reference/storage/nvs_flash.rst

@@ -154,17 +154,17 @@ If ``FLASH_IN_PROJECT`` is not specified, the image will still be generated, but
 Application Example
 -------------------
 
-You can find code examples in the :example:`storage` directory of ESP-IDF examples:
+You can find code examples in the :example:`storage/nvs` directory of ESP-IDF examples:
 
-:example:`storage/nvs_rw_value`
+:example:`storage/nvs/nvs_rw_value`
 
   Demonstrates how to read a single integer value from, and write it to NVS.
 
   The value checked in this example holds the number of the {IDF_TARGET_NAME} module restarts. The value's function as a counter is only possible due to its storing in NVS.
 
   The example also shows how to check if a read/write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way.
 
-:example:`storage/nvs_rw_blob`
+:example:`storage/nvs/nvs_rw_blob`
 
   Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between {IDF_TARGET_NAME} module restarts.
 
@@ -173,9 +173,9 @@ You can find code examples in the :example:`storage` directory of ESP-IDF exampl
 
   The example also shows how to implement the diagnostic procedure to check if the read/write operation was successful.
 
-:example:`storage/nvs_rw_value_cxx`
+:example:`storage/nvs/nvs_rw_value_cxx`
 
-  This example does exactly the same as :example:`storage/nvs_rw_value`, except that it uses the C++ NVS handle class.
+  This example does exactly the same as :example:`storage/nvs/nvs_rw_value`, except that it uses the C++ NVS handle class.
 
 Internals
 ---------

docs/zh_CN/api-guides/bootloader.rst

@@ -186,6 +186,6 @@ ESP-IDF 二级引导加载程序位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_O
 
 在引导加载程序的代码中，不能使用其他组件提供的驱动和函数，除非某个驱动或函数明确声明支持在引导加载程序中运行。如果确实需要，请将所需功能放在项目的 `bootloader_components` 目录中（注意，这会增加引导加载程序的大小）。以下是可以在引导加载程序中使用的组件示例：
 
-* :example:`storage/nvs_bootloader`
+* :example:`storage/nvs/nvs_bootloader`
 
 如果引导加载程序过大，则可能与内存中的分区表重叠，分区表默认烧录在偏移量 0x8000 处。增加 :ref:`分区表偏移量 <CONFIG_PARTITION_TABLE_OFFSET>` ，将分区表放在 flash 中靠后的区域，这样可以增加引导加载程序的可用空间。

docs/zh_CN/api-guides/file-system-considerations.rst

@@ -181,8 +181,8 @@ NVS 具有如下特性：
 
 **示例:**
 
-- :example:`storage/nvs_rw_value` 演示了如何写入和读取一个整数值。
-- :example:`storage/nvs_rw_blob` 演示如何写入和读取一个 blob。
+- :example:`storage/nvs/nvs_rw_value` 演示了如何写入和读取一个整数值。
+- :example:`storage/nvs/nvs_rw_blob` 演示如何写入和读取一个 blob。
 - :example:`security/nvs_encryption_hmac` 演示了如何用 HMAC 外设进行 NVS 加密，并通过 efuse 中的 HMAC 密钥生成加密密钥。
 - :example:`security/flash_encryption` 演示了如何进行 flash 加密，包括创建和使用 NVS 分区。
 

docs/zh_CN/api-reference/storage/index.rst

@@ -47,16 +47,18 @@
 
     * - **例程**
       - **描述**
-    * - :example:`nvs_rw_blob <storage/nvs_rw_blob>`
+    * - :example:`nvs_rw_blob <storage/nvs/nvs_rw_blob>`
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写 blob 数据类型。
-    * - :example:`nvs_rw_value <storage/nvs_rw_value>`
+    * - :example:`nvs_rw_value <storage/nvs/nvs_rw_value>`
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写整数数据类型。
-    * - :example:`nvs_rw_value <storage/nvs_rw_value>`
+    * - :example:`nvs_rw_value <storage/nvs/nvs_rw_value_cxx>`
       - 演示了如何在 NVS flash 中使用 C++ 语言 API 读写整数数据类型。
-    * - :example:`nvs_bootloader <storage/nvs_bootloader>`
+    * - :example:`nvs_bootloader <storage/nvs/nvs_bootloader>`
       - 演示了如何使用引导加载程序代码中可用的 API 来读取 NVS 数据。
-    * - :example:`nvsgen <storage/nvsgen>`
+    * - :example:`nvsgen <storage/nvs/nvsgen>`
       - 演示了如何使用基于 Python 的 NVS 镜像生成工具，根据 CSV 文件内容创建 NVS 分区镜像。
+    * - :example:`nvs_console <storage/nvs/nvs_console>`
+      - 演示了如何通过交互式控制台界面使用 NVS。
 
 .. list-table:: 常用文件系统 API
     :widths: 25 75

docs/zh_CN/api-reference/storage/nvs_bootloader.rst

@@ -37,7 +37,7 @@
 应用示例
 -----------
 
-代码示例请参阅 ESP-IDF 示例 :example:`storage` 目录下的 :example:`storage/nvs_bootloader`。
+代码示例请参阅 ESP-IDF 示例 :example:`storage/nvs` 目录下的 :example:`storage/nvs/nvs_bootloader`。
 
 本节演示了如何在输入/输出结构中准备数据，以支持不同的数据类型、命名空间和键。此外，还包含从 NVS 读取字符串数据的示例。
 

docs/zh_CN/api-reference/storage/nvs_flash.rst

@@ -154,17 +154,17 @@ NVS 分区生成程序帮助生成 NVS 分区二进制文件，可使用烧录
 应用示例
 -------------------
 
-ESP-IDF :example:`storage` 目录下提供了数个代码示例：
+ESP-IDF :example:`storage/nvs` 目录下提供了数个代码示例：
 
-:example:`storage/nvs_rw_value`
+:example:`storage/nvs/nvs_rw_value`
 
   演示如何读取及写入 NVS 单个整数值。
 
   此示例中的值表示 {IDF_TARGET_NAME} 模组重启次数。NVS 中数据不会因为模组重启而丢失，因此只有将这一值存储于 NVS 中，才能起到重启次数计数器的作用。
 
   该示例也演示了如何检测读取/写入操作是否成功，以及某个特定值是否在 NVS 中尚未初始化。诊断程序以纯文本形式提供，有助于追踪程序流程，及时发现问题。
 
-:example:`storage/nvs_rw_blob`
+:example:`storage/nvs/nvs_rw_blob`
 
   演示如何读取及写入 NVS 单个整数值和 BLOB（二进制大对象），并在 NVS 中存储这一数值，即便 {IDF_TARGET_NAME} 模组重启也不会消失。
 
@@ -173,9 +173,9 @@ ESP-IDF :example:`storage` 目录下提供了数个代码示例：
 
   该示例也演示了如何执行诊断程序以检测读取/写入操作是否成功。
 
-:example:`storage/nvs_rw_value_cxx`
+:example:`storage/nvs/nvs_rw_value_cxx`
 
-  这个例子与 :example:`storage/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类。
+  这个例子与 :example:`storage/nvs/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类。
 
 内部实现
 ---------

examples/storage/.build-test-rules.yml

@@ -16,44 +16,6 @@ examples/storage/emmc:
     - if: IDF_TARGET == "esp32s3"
       reason: only support on esp32s3
 
-examples/storage/nvs_bootloader:
-  depends_components:
-    - nvs_flash
-    - nvs_sec_provider
-  disable:
-    - if: CONFIG_NAME == "nvs_enc_flash_enc" and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)
-    - if: CONFIG_NAME == "nvs_enc_hmac" and (SOC_HMAC_SUPPORTED != 1 or (SOC_HMAC_SUPPORTED == 1 and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)))
-      reason: As of now in such cases, we do not have any way to perform AES operations in the bootloader build
-
-examples/storage/nvs_rw_blob:
-  depends_components:
-    - nvs_flash
-    - driver
-  disable_test:
-    - if: IDF_TARGET not in ["esp32", "esp32c3"]
-      reason: only one target per arch needed
-
-examples/storage/nvs_rw_value:
-  depends_components:
-    - nvs_flash
-  disable_test:
-    - if: IDF_TARGET not in ["esp32", "esp32c3"]
-      reason: only one target per arch needed
-
-examples/storage/nvs_rw_value_cxx:
-  depends_components:
-    - nvs_flash
-  disable_test:
-    - if: IDF_TARGET not in ["esp32", "esp32c3"]
-      reason: only one target per arch needed
-
-examples/storage/nvsgen:
-  depends_components:
-    - nvs_flash
-  disable_test:
-    - if: IDF_TARGET != "esp32"
-      reason: only one target needed
-
 examples/storage/partition_api/partition_find:
   depends_components:
     - esp_partition

examples/storage/README.md

@@ -17,6 +17,7 @@ The examples are grouped into sub-directories by category. Each category directo
 * `nvs_rw_blob` example demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP module restarts.
 * `nvs_rw_value` example demonstrates how to read and write a single integer value using NVS.
 * `nvs_rw_value_cxx` example demonstrates how to read and write a single integer value using NVS (it uses the C++ NVS handle API).
+* `nvs_console` example demonstrates how to use NVS through an interactive console interface.
 * `partition_api` examples demonstrate how to use different partition APIs.
 * `parttool` example demonstrates common operations the partitions tool allows the user to perform.
 * `sd_card` examples demonstrate how to use an SD card with an ESP device.

examples/storage/nvs/.build-test-rules.yml

@@ -0,0 +1,47 @@
+# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
+
+examples/storage/nvs/nvs_bootloader:
+  depends_components:
+    - nvs_flash
+    - nvs_sec_provider
+  disable:
+    - if: CONFIG_NAME == "nvs_enc_flash_enc" and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)
+    - if: CONFIG_NAME == "nvs_enc_hmac" and (SOC_HMAC_SUPPORTED != 1 or (SOC_HMAC_SUPPORTED == 1 and (SOC_AES_SUPPORTED != 1 and ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB != 1)))
+      reason: As of now in such cases, we do not have any way to perform AES operations in the bootloader build
+
+examples/storage/nvs/nvs_console:
+  depends_components:
+    - nvs_flash
+    - console
+    - vfs
+  disable_test:
+    - if: IDF_TARGET not in ["esp32", "esp32c3"]
+      reason: only one target per arch needed
+examples/storage/nvs/nvs_rw_blob:
+  depends_components:
+    - nvs_flash
+    - driver
+  disable_test:
+    - if: IDF_TARGET not in ["esp32", "esp32c3"]
+      reason: only one target per arch needed
+
+examples/storage/nvs/nvs_rw_value:
+  depends_components:
+    - nvs_flash
+  disable_test:
+    - if: IDF_TARGET not in ["esp32", "esp32c3"]
+      reason: only one target per arch needed
+
+examples/storage/nvs/nvs_rw_value_cxx:
+  depends_components:
+    - nvs_flash
+  disable_test:
+    - if: IDF_TARGET not in ["esp32", "esp32c3"]
+      reason: only one target per arch needed
+
+examples/storage/nvs/nvsgen:
+  depends_components:
+    - nvs_flash
+  disable_test:
+    - if: IDF_TARGET != "esp32"
+      reason: only one target needed

examples/storage/nvs_bootloader/CMakeLists.txt renamed to examples/storage/nvs/nvs_bootloader/CMakeLists.txt

@@ -137,7 +137,7 @@ Enable NVS encryption using your preferred scheme. Please find more details rega
 (Note: In case you select the `HMAC based NVS encryption scheme`, make sure that you burn the below mentioned [HMAC key](./main/nvs_enc_hmac_key.bin) in the efuses.)
 
 For generating the encrypted NVS partitions, we shall use [NVS partition generator](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_partition_gen.html#nvs-partition-generator-utility).
-We shall use the [nvs_partition_gen.py](../../../components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py) script for the operations.
+We shall use the [nvs_partition_gen.py](../../../../components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py) script for the operations.
 
 Along with the above mentioned file structure, the project folder also contains pre-generated encrypted partitions and the partition corresponding to the selected NVS encryption scheme is flashed along with the build artefacts using the `main/CMakeLists.txt`.
 
@@ -146,13 +146,13 @@ In case the data in `nvs_data.csv` is modified, these encrypted NVS partitions c
 1. NVS Encryption using the flash encryption scheme
 
 ```
-python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_encrypted.bin 0x6000 --inputkey $IDF_PATH/examples/storage/nvs_bootloader/main/encryption_keys.bin
+python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs/nvs_bootloader/main/nvs_encrypted.bin 0x6000 --inputkey $IDF_PATH/examples/storage/nvs/nvs_bootloader/main/encryption_keys.bin
 ```
 
 2. NVS Encryption using the HMAC scheme
 
 ```
-python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_encrypted_hmac.bin 0x6000 --keygen --key_protect_hmac --kp_hmac_inputkey $IDF_PATH/examples/storage/nvs_bootloader/main/nvs_enc_hmac_key.bin
+python nvs_partition_gen.py encrypt $IDF_PATH/examples/storage/nvs/nvs_bootloader/nvs_data.csv $IDF_PATH/examples/storage/nvs/nvs_bootloader/main/nvs_encrypted_hmac.bin 0x6000 --keygen --key_protect_hmac --kp_hmac_inputkey $IDF_PATH/examples/storage/nvs/nvs_bootloader/main/nvs_enc_hmac_key.bin
 ```
 
 Build the application using configurations corresponding to the NVS encryption scheme that you have selected:

examples/storage/nvs_bootloader/README.md renamed to examples/storage/nvs/nvs_bootloader/README.md

@@ -0,0 +1,8 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+list(APPEND EXTRA_COMPONENT_DIRS "$ENV{IDF_PATH}/examples/system/console/advanced/components")
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(nvs_console_example)