Merge branch 'feat/nvs_iteration_statistics_examples' into 'master'

feat(examples/storage): add nvs statistics and iteration examples

Closes DOC-12742

See merge request espressif/esp-idf!42327

Author: pacucha42

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

@@ -190,6 +190,8 @@ Points to keep in mind when developing NVS related code:
 
 - :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:`storage/nvs/nvs_statistics` demonstrates how to obtain and interpret NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+- :example:`storage/nvs/nvs_iteration` demonstrates how to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
 - :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

@@ -53,6 +53,10 @@ Examples
       - 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/nvs_rw_value_cxx>`
       - Shows the use of the C++-style API to read and write integer data types in NVS flash.
+    * - :example:`nvs_statistics <storage/nvs/nvs_statistics>`
+      - Shows the use of the C-style API to obtain NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+    * - :example:`nvs_iteration <storage/nvs/nvs_iteration>`
+      - Shows the use of the C-style API to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
     * - :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/nvs/nvsgen>`

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

@@ -177,6 +177,22 @@ You can find code examples in the :example:`storage/nvs` directory of ESP-IDF ex
 
   This example does exactly the same as :example:`storage/nvs/nvs_rw_value`, except that it uses the C++ NVS handle class.
 
+:example:`storage/nvs/nvs_statistics`
+
+  This example demonstrates how to obtain and interpret NVS usage statistics: free/used/available/total number of entries and number of namespaces in given NVS partition.
+
+  Default NVS partition is erased for a clean run of this example. Then mock data string values are written.
+
+  Usage statistics are obtained prior to and post writing, with the differences being compared to expected values of newly used entries.
+
+:example:`storage/nvs/nvs_iteration`
+
+  This example demonstrates how to iterate over entries of specific (or any) NVS data type and how to obtain info about such entries.
+
+  Default NVS partition is erased for a clean run of this example. Then mock data consisting of different NVS integer data types are written.
+
+  After that, the example iterates over each individual data type as well as the generic ``NVS_TYPE_ANY`` type, and logs the information obtained from each iteration.
+
 Internals
 ---------
 

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

@@ -190,6 +190,8 @@ NVS 具有如下特性：
 
 - :example:`storage/nvs/nvs_rw_value` 演示了如何写入和读取一个整数值。
 - :example:`storage/nvs/nvs_rw_blob` 演示如何写入和读取一个 blob。
+- :example:`storage/nvs/nvs_statistics` 演示了如何获取并解读 NVS 使用情况统计信息：包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+- :example:`storage/nvs/nvs_iteration` 演示了如何遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
 - :example:`security/nvs_encryption_hmac` 演示了如何用 HMAC 外设进行 NVS 加密，并通过 efuse 中的 HMAC 密钥生成加密密钥。
 - :example:`security/flash_encryption` 演示了如何进行 flash 加密，包括创建和使用 NVS 分区。
 

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

@@ -53,6 +53,10 @@
       - 演示了如何在 NVS flash 中使用 C 语言 API 读写整数数据类型。
     * - :example:`nvs_rw_value <storage/nvs/nvs_rw_value_cxx>`
       - 演示了如何在 NVS flash 中使用 C++ 语言 API 读写整数数据类型。
+    * - :example:`nvs_statistics <storage/nvs/nvs_statistics>`
+      - 演示了如何使用 C 风格 API 获取 NVS 使用情况统计信息，包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+    * - :example:`nvs_iteration <storage/nvs/nvs_iteration>`
+      - 演示了如何使用 C 风格 API 遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
     * - :example:`nvs_bootloader <storage/nvs/nvs_bootloader>`
       - 演示了如何使用引导加载程序代码中可用的 API 来读取 NVS 数据。
     * - :example:`nvsgen <storage/nvs/nvsgen>`

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

@@ -177,6 +177,22 @@ ESP-IDF :example:`storage/nvs` 目录下提供了数个代码示例：
 
   这个例子与 :example:`storage/nvs/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类。
 
+:example:`storage/nvs/nvs_statistics`
+
+  该示例演示了如何获取并解读 NVS 使用情况统计信息：包括指定 NVS 分区中的空闲、已用、可用、总条目数、以及命名空间数量。
+
+  默认的 NVS 分区会在运行本示例前被擦除，以确保干净的运行环境。随后，会写入模拟的字符串类型数据。
+
+  在写入数据前后分别获取使用情况统计信息，并将两者的差异与新占用条目的预期值进行比较。
+
+:example:`storage/nvs/nvs_iteration`
+
+  该示例演示了如何遍历特定（或任意）NVS 数据类型的条目，以及如何获取这些条目的相关信息。
+
+  默认的 NVS 分区会在运行本示例前被擦除，以确保干净的运行环境。随后，会写入包含不同 NVS 整型数据类型的模拟数据。
+
+  之后，本示例会遍历各个数据类型以及通用的 ``NVS_TYPE_ANY`` 类型，并记录在每次遍历过程中获取到的信息。
+
 内部实现
 ---------
 

examples/storage/README.md

@@ -18,6 +18,8 @@ The examples are grouped into sub-directories by category. Each category directo
 * `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.
+* `nvs_statistics` example demonstrates how to obtain and interpret stats about used/available NVS storage entries in given NVS partition.
+* `nvs_iteration` example demonstrates iterating over entries of specific (or any) data type in given namespace, and the info to be obtained about the entries while doing so.
 * `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

@@ -17,6 +17,12 @@ examples/storage/nvs/nvs_console:
   disable_test:
     - if: IDF_TARGET not in ["esp32", "esp32c3"]
       reason: only one target per arch needed
+examples/storage/nvs/nvs_iteration:
+  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_blob:
   depends_components:
     - nvs_flash
@@ -38,6 +44,13 @@ examples/storage/nvs/nvs_rw_value_cxx:
     - if: IDF_TARGET not in ["esp32", "esp32c3"]
       reason: only one target per arch needed
 
+examples/storage/nvs/nvs_statistics:
+  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

examples/storage/nvs/nvs_iteration/CMakeLists.txt

@@ -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.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(nvs_iteration)

examples/storage/nvs/nvs_iteration/README.md

@@ -0,0 +1,69 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- |
+
+# Non-Volatile Storage (NVS) Iteration Example
+
+This example showcases how to iterate and obtain info about NVS entries of a specific (or any) NVS datatype.
+
+Default "nvs" partition is first erased to allow for clean example run, followed by writing 2 sets of key value pairs of different types to NVS storage.
+After that, iteration is performed over the individual data types, as well as the generic `NVS_TYPE_ANY`, and relevant entry info gained from iteration is verbosely logged.
+
+Iterator creation in this example is performed by [nvs_entry_find()](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html#_CPPv414nvs_entry_findPKcPKc10nvs_type_tP14nvs_iterator_t) and accessing entry info by [nvs_entry_info()](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html#_CPPv414nvs_entry_infoK14nvs_iterator_tP16nvs_entry_info_t).
+
+
+Detailed functional description of NVS and API is provided in [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/nvs_flash.html).
+
+## How to use example
+
+### Hardware required
+
+This example does not require any special hardware, and can be run on any common development board.
+
+### Build and flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+...
+I (265) nvs_iteration_example: Erasing the contents of the default NVS partition...
+I (595) nvs_iteration_example: Opening Non-Volatile Storage (NVS) handle for namespace '_mock_data'...
+I (605) nvs_iteration_example: Writing u32 mock data key-value pairs to NVS namespace '_mock_data'...
+I (605) nvs_iteration_example: Wrote 7 u32 mock data key-value pairs to NVS namespace '_mock_data'.
+I (615) nvs_iteration_example: Writing i8 mock data key-value pairs to NVS namespace '_mock_data'...
+I (625) nvs_iteration_example: Wrote 7 i8 mock data key-value pairs to NVS namespace '_mock_data'.
+I (625) nvs_iteration_example: Committing data in NVS namespace '_mock_data'...
+I (635) nvs_iteration_example: NVS handle for namespace '_mock_data' closed.
+I (645) nvs_iteration_example: Iterating over NVS_TYPE_U32 data in namespace '_mock_data'...
+I (655) nvs_iteration_example: Entry info: key 'system_startup' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (665) nvs_iteration_example: Entry info: key 'user_login' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (675) nvs_iteration_example: Entry info: key 'data_backup' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (685) nvs_iteration_example: Entry info: key 'sched_update' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (695) nvs_iteration_example: Entry info: key 'db_cleanup' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (705) nvs_iteration_example: Entry info: key 'security_scan' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (715) nvs_iteration_example: Entry info: key 'system_shutdown' for data type type NVS_TYPE_U32 in namespace '_mock_data'
+I (725) nvs_iteration_example: Iterated over 7 entries.
+I (725) nvs_iteration_example: Iterating over NVS_TYPE_I8 data in namespace '_mock_data'...
+I (735) nvs_iteration_example: Entry info: key 'temperature' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (745) nvs_iteration_example: Entry info: key 'humidity' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (755) nvs_iteration_example: Entry info: key 'light_level' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (765) nvs_iteration_example: Entry info: key 'motion_detected' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (775) nvs_iteration_example: Entry info: key 'battery_level' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (785) nvs_iteration_example: Entry info: key 'signal_strength' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (795) nvs_iteration_example: Entry info: key 'error_code' for data type type NVS_TYPE_I8 in namespace '_mock_data'
+I (805) nvs_iteration_example: Iterated over 7 entries.
+I (815) nvs_iteration_example: Iterating over NVS_TYPE_ANY data in namespace '_mock_data'...
+I (825) nvs_iteration_example: Iterated over 14 entries.
+I (825) nvs_iteration_example: Returning from app_main().
+I (835) main_task: Returned from app_main()
+...
+```