Merge branch 'feature/nvs_examples' into 'master'

NVS examples

Add two examples for working with NVS.

One is reading and writing an integer value, another is reading and writing a blob.


See merge request !194

examples/07_nvs_rw_value/Makefile

@@ -0,0 +1,9 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := nvs-rw-value
+
+include $(IDF_PATH)/make/project.mk
+

examples/07_nvs_rw_value/README.md

@@ -0,0 +1,13 @@
+# Non-Volatile Storage (NVS) Read and Write Example
+
+Demonstrates how to read and write a single integer value using NVS.
+
+The value holds the number of ESP32 module restarts. Since it is written to NVS, the value is preserved between restarts.
+
+Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
+
+Check another example *08_nvs_rw_blob*, that shows how to read and write variable length binary data (blob).
+
+Detailed functional description of NVS and API is provided in [documentation](http://esp-idf.readthedocs.io/en/latest/api/nvs_flash.html).
+
+See the README.md file in the upper level 'examples' directory for more information about examples.

examples/07_nvs_rw_value/main/component.mk

@@ -0,0 +1,2 @@
+
+include $(IDF_PATH)/make/component_common.mk

examples/07_nvs_rw_value/main/nvs_rw_value.c

@@ -0,0 +1,80 @@
+/* Non-Volatile Storage (NVS) Read and Write a Value - Example
+
+   For other examples please check:
+   https://github.com/espressif/esp-idf/tree/master/examples
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_system.h"
+#include "nvs_flash.h"
+#include "nvs.h"
+
+void app_main()
+{
+    nvs_flash_init();
+
+    nvs_handle my_handle;
+    esp_err_t err;
+
+    printf("\n");
+
+    // Open
+    printf("Opening Non-Volatile Storage (NVS) ... ");
+    err = nvs_open("storage", NVS_READWRITE, &my_handle);
+    if (err != ESP_OK) {
+        printf("Error (%d) opening NVS!\n", err);
+    } else {
+        printf("Done\n");
+
+        // Read
+        printf("Reading restart counter from NVS ... ");
+        int32_t restart_counter = 0; // value will default to 0, if not set yet in NVS
+        err = nvs_get_i32(my_handle, "restart_conter", &restart_counter);
+        switch (err) {
+            case ESP_OK:
+                printf("Done\n");
+                printf("Restart counter = %d\n", restart_counter);
+                break;
+            case ESP_ERR_NVS_NOT_FOUND:
+                printf("The value is not initialized yet!\n");
+                break;
+            default :
+                printf("Error (%d) reading!\n", err);
+        }
+
+        // Write
+        printf("Updating restart counter in NVS ... ");
+        restart_counter++;
+        err = nvs_set_i32(my_handle, "restart_conter", restart_counter);
+        printf((err != ESP_OK) ? "Failed!\n" : "Done\n");
+
+        // Commit written value.
+        // After setting any values, nvs_commit() must be called to ensure changes are written
+        // to flash storage. Implementations may write to storage at other times,
+        // but this is not guaranteed.
+        printf("Committing updates in NVS ... ");
+        err = nvs_commit(my_handle);
+        printf((err != ESP_OK) ? "Failed!\n" : "Done\n");
+
+        // Close
+        nvs_close(my_handle);
+    }
+
+    printf("\n");
+
+    // Restart module
+    for (int i = 10; i >= 0; i--) {
+        printf("Restarting in %d seconds...\n", i);
+        vTaskDelay(1000 / portTICK_RATE_MS);
+    }
+    printf("Restarting now.\n");
+    fflush(stdout);
+    system_restart();
+}

examples/08_nvs_rw_blob/Makefile

@@ -0,0 +1,9 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := nvs-rw-blob
+
+include $(IDF_PATH)/make/project.mk
+

examples/08_nvs_rw_blob/README.md

@@ -0,0 +1,14 @@
+# Non-Volatile Storage (NVS) Read and Write Example
+
+Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
+
+  * value - tracks number of ESP32 module soft and hard restarts.
+  * blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. New run time is added to the table on each manually triggered soft restart and written back to NVS. Triggering is done by pulling down GPIO0.
+
+Example also shows how to implement diagnostics if read / write operation was successful. 
+
+If not done already, consider checking simpler example *07_nvs_rw_value*, that has been used as a starting point for preparing this one. 
+
+Detailed functional description of NVS and API is provided in [documentation](http://esp-idf.readthedocs.io/en/latest/api/nvs_flash.html).
+
+See the README.md file in the upper level 'examples' directory for more information about examples.

examples/08_nvs_rw_blob/main/component.mk

@@ -0,0 +1,2 @@
+
+include $(IDF_PATH)/make/component_common.mk

examples/08_nvs_rw_blob/main/nvs_rw_blob.c

@@ -0,0 +1,178 @@
+/* Non-Volatile Storage (NVS) Read and Write a Blob - Example
+
+   For other examples please check:
+   https://github.com/espressif/esp-idf/tree/master/examples
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_system.h"
+#include "nvs_flash.h"
+#include "nvs.h"
+#include "driver/gpio.h"
+
+#define STORAGE_NAMESPACE "storage"
+
+/* Save the number of module restarts in NVS
+   by first reading and then incrementing
+   the number that has been saved previously.
+   Return an error if anything goes wrong
+   during this process.
+ */
+esp_err_t save_restart_counter(void)
+{
+    nvs_handle my_handle;
+    esp_err_t err;
+
+    // Open
+    err = nvs_open(STORAGE_NAMESPACE, NVS_READWRITE, &my_handle);
+    if (err != ESP_OK) return err;
+
+    // Read
+    int32_t restart_counter = 0; // value will default to 0, if not set yet in NVS
+    err = nvs_get_i32(my_handle, "restart_conter", &restart_counter);
+    if (err != ESP_OK && err != ESP_ERR_NVS_NOT_FOUND) return err;
+
+    // Write
+    restart_counter++;
+    err = nvs_set_i32(my_handle, "restart_conter", restart_counter);
+    if (err != ESP_OK) return err;
+
+    // Commit written value.
+    // After setting any values, nvs_commit() must be called to ensure changes are written
+    // to flash storage. Implementations may write to storage at other times,
+    // but this is not guaranteed.
+    err = nvs_commit(my_handle);
+    if (err != ESP_OK) return err;
+
+    // Close
+    nvs_close(my_handle);
+    return ESP_OK;
+}
+
+/* Save new run time value in NVS
+   by first reading a table of previously saved values
+   and then adding the new value at the end of the table.
+   Return an error if anything goes wrong
+   during this process.
+ */
+esp_err_t save_run_time(void)
+{
+    nvs_handle my_handle;
+    esp_err_t err;
+
+    // Open
+    err = nvs_open(STORAGE_NAMESPACE, NVS_READWRITE, &my_handle);
+    if (err != ESP_OK) return err;
+
+    // Read the size of memory space required for blob
+    size_t required_size = 0;  // value will default to 0, if not set yet in NVS
+    err = nvs_get_blob(my_handle, "run_time", NULL, &required_size);
+    if (err != ESP_OK && err != ESP_ERR_NVS_NOT_FOUND) return err;
+
+    // Read previously saved blob if available
+    uint32_t* run_time = malloc(required_size + sizeof(uint32_t));
+    if (required_size > 0) {
+        err = nvs_get_blob(my_handle, "run_time", run_time, &required_size);
+        if (err != ESP_OK) return err;
+    }
+
+    // Write value including previously saved blob if available
+    required_size += sizeof(uint32_t);
+    run_time[required_size / sizeof(uint32_t) - 1] = xTaskGetTickCount() * portTICK_PERIOD_MS;
+    err = nvs_set_blob(my_handle, "run_time", run_time, required_size);
+    if (err != ESP_OK) return err;
+
+    free(run_time);
+
+    // Commit
+    err = nvs_commit(my_handle);
+    if (err != ESP_OK) return err;
+
+    // Close
+    nvs_close(my_handle);
+    return ESP_OK;
+}
+
+/* Read from NVS and print restart counter
+   and the table with run times.
+   Return an error if anything goes wrong
+   during this process.
+ */
+esp_err_t print_what_saved(void)
+{
+    nvs_handle my_handle;
+    esp_err_t err;
+
+    // Open
+    err = nvs_open(STORAGE_NAMESPACE, NVS_READWRITE, &my_handle);
+    if (err != ESP_OK) return err;
+
+    // Read restart counter
+    int32_t restart_counter = 0; // value will default to 0, if not set yet in NVS
+    err = nvs_get_i32(my_handle, "restart_conter", &restart_counter);
+    if (err != ESP_OK && err != ESP_ERR_NVS_NOT_FOUND) return err;
+    printf("Restart counter = %d\n", restart_counter);
+
+    // Read run time blob
+    size_t required_size = 0;  // value will default to 0, if not set yet in NVS
+    // obtain required memory space to store blob being read from NVS
+    err = nvs_get_blob(my_handle, "run_time", NULL, &required_size);
+    if (err != ESP_OK && err != ESP_ERR_NVS_NOT_FOUND) return err;
+    printf("Run time:\n");
+    if (required_size == 0) {
+        printf("Nothing saved yet!\n");
+    } else {
+        uint32_t* run_time = malloc(required_size);
+        err = nvs_get_blob(my_handle, "run_time", run_time, &required_size);
+        if (err != ESP_OK) return err;
+        for (int i = 0; i < required_size / sizeof(uint32_t); i++) {
+            printf("%d: %d\n", i + 1, run_time[i]);
+        }
+        free(run_time);
+    }
+
+    // Close
+    nvs_close(my_handle);
+    return ESP_OK;
+}
+
+
+void app_main()
+{
+    nvs_flash_init();
+
+    esp_err_t err;
+
+    err = print_what_saved();
+    if (err != ESP_OK) printf("Error (%d) reading data from NVS!\n", err);
+
+    err = save_restart_counter();
+    if (err != ESP_OK) printf("Error (%d) saving restart counter to NVS!\n", err);
+
+    gpio_pad_select_gpio(GPIO_NUM_0);
+    gpio_set_direction(GPIO_NUM_0, GPIO_MODE_DEF_INPUT);
+
+    /* Read the status of GPIO0. If GPIO0 is LOW for longer than 1000 ms,
+       then save module's run time and restart it
+     */
+    while (1) {
+        if (gpio_get_level(GPIO_NUM_0) == 0) {
+            vTaskDelay(1000 / portTICK_RATE_MS);
+            if(gpio_get_level(GPIO_NUM_0) == 0) {
+                err = save_run_time();
+                if (err != ESP_OK) printf("Error (%d) saving run time blob to NVS!\n", err);
+                printf("Restarting...\n");
+                fflush(stdout);
+                system_restart();
+            }
+        }
+        vTaskDelay(200 / portTICK_RATE_MS);
+    }
+}