esp32: Add basic support for Non-Volatile-Storage in esp32 module.

tve · dpgeorge · commit c10d431819f9 · 2021-02-19T15:05:19.000+11:00
This commit implements basic NVS support for the esp32. It follows the pattern of the esp32.Partition class and exposes an NVS object per NVS namespace. The initial support provided is only for signed 32-bit integers and binary blobs. It's easy (albeit a bit tedious) to add support for more types. See discussions in: adafruit#4436, adafruit#4707, adafruit#6780
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -269,3 +269,51 @@ Constants
           esp32.WAKEUP_ANY_HIGH
 
    Selects the wake level for pins.
+
+Non-Volatile Storage
+--------------------
+
+This class gives access to the Non-Volatile storage managed by ESP-IDF. The NVS is partitioned
+into namespaces and each namespace contains typed key-value pairs. The keys are strings and the
+values may be various integer types, strings, and binary blobs. The driver currently only
+supports 32-bit signed integers and blobs.
+
+.. warning::
+
+    Changes to NVS need to be committed to flash by calling the commit method. Failure
+    to call commit results in changes being lost at the next reset.
+
+.. class:: NVS(namespace)
+
+    Create an object providing access to a namespace (which is automatically created if not
+    present).
+
+.. method:: NVS.set_i32(key, value)
+
+    Sets a 32-bit signed integer value for the specified key. Remember to call *commit*!
+
+.. method:: NVS.get_i32(key)
+
+    Returns the signed integer value for the specified key. Raises an OSError if the key does not
+    exist or has a different type.
+
+.. method:: NVS.set_blob(key, value)
+
+    Sets a binary blob value for the specified key. The value passed in must support the buffer
+    protocol, e.g. bytes, bytearray, str. (Note that esp-idf distinguishes blobs and strings, this
+    method always writes a blob even if a string is passed in as value.)
+    Remember to call *commit*!
+
+.. method:: NVS.get_blob(key, buffer)
+
+    Reads the value of the blob for the specified key into the buffer, which must be a bytearray.
+    Returns the actual length read. Raises an OSError if the key does not exist, has a different
+    type, or if the buffer is too small.
+
+.. method:: NVS.erase_key(key)
+
+    Erases a key-value pair.
+
+.. method:: NVS.commit()
+
+    Commits changes made by *set_xxx* methods to flash.
diff --git a/ports/esp32/esp32_nvs.c b/ports/esp32/esp32_nvs.c
@@ -0,0 +1,151 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2021 by Thorsten von Eicken
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <string.h>
+
+#include "py/runtime.h"
+#include "py/mperrno.h"
+#include "mphalport.h"
+#include "modesp32.h"
+#include "nvs_flash.h"
+#include "nvs.h"
+
+// This file implements the NVS (Non-Volatile Storage) class in the esp32 module.
+// It provides simple access to the NVS feature provided by ESP-IDF.
+
+// NVS python object that represents an NVS namespace.
+typedef struct _esp32_nvs_obj_t {
+    mp_obj_base_t base;
+    nvs_handle_t namespace;
+} esp32_nvs_obj_t;
+
+// *esp32_nvs_new allocates a python NVS object given a handle to an esp-idf namespace C obj.
+STATIC esp32_nvs_obj_t *esp32_nvs_new(nvs_handle_t namespace) {
+    esp32_nvs_obj_t *self = m_new_obj(esp32_nvs_obj_t);
+    self->base.type = &esp32_nvs_type;
+    self->namespace = namespace;
+    return self;
+}
+
+// esp32_nvs_print prints an NVS object, unfortunately it doesn't seem possible to extract the
+// namespace string or anything else from the opaque handle provided by esp-idf.
+STATIC void esp32_nvs_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
+    // esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    mp_printf(print, "<NVS namespace>");
+}
+
+// esp32_nvs_make_new constructs a handle to an NVS namespace.
+STATIC mp_obj_t esp32_nvs_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
+    // Check args
+    mp_arg_check_num(n_args, n_kw, 1, 1, false);
+
+    // Get requested nvs namespace
+    const char *ns_name = mp_obj_str_get_str(all_args[0]);
+    nvs_handle_t namespace;
+    check_esp_err(nvs_open(ns_name, NVS_READWRITE, &namespace));
+    return MP_OBJ_FROM_PTR(esp32_nvs_new(namespace));
+}
+
+// esp32_nvs_set_i32 sets a 32-bit integer value
+STATIC mp_obj_t esp32_nvs_set_i32(mp_obj_t self_in, mp_obj_t key_in, mp_obj_t value_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const char *key = mp_obj_str_get_str(key_in);
+    int32_t value = mp_obj_get_int(value_in);
+    check_esp_err(nvs_set_i32(self->namespace, key, value));
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_3(esp32_nvs_set_i32_obj, esp32_nvs_set_i32);
+
+// esp32_nvs_get_i32 reads a 32-bit integer value
+STATIC mp_obj_t esp32_nvs_get_i32(mp_obj_t self_in, mp_obj_t key_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const char *key = mp_obj_str_get_str(key_in);
+    int32_t value;
+    check_esp_err(nvs_get_i32(self->namespace, key, &value));
+    return mp_obj_new_int(value);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_2(esp32_nvs_get_i32_obj, esp32_nvs_get_i32);
+
+// esp32_nvs_set_blob writes a buffer object into a binary blob value.
+STATIC mp_obj_t esp32_nvs_set_blob(mp_obj_t self_in, mp_obj_t key_in, mp_obj_t value_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const char *key = mp_obj_str_get_str(key_in);
+    mp_buffer_info_t value;
+    mp_get_buffer_raise(value_in, &value, MP_BUFFER_READ);
+    check_esp_err(nvs_set_blob(self->namespace, key, value.buf, value.len));
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_3(esp32_nvs_set_blob_obj, esp32_nvs_set_blob);
+
+// esp32_nvs_get_blob reads a binary blob value into a bytearray. Returns actual length.
+STATIC mp_obj_t esp32_nvs_get_blob(mp_obj_t self_in, mp_obj_t key_in, mp_obj_t value_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const char *key = mp_obj_str_get_str(key_in);
+    // get buffer to be filled
+    mp_buffer_info_t value;
+    mp_get_buffer_raise(value_in, &value, MP_BUFFER_WRITE);
+    size_t length = value.len;
+    // fill the buffer with the value, will raise an esp-idf error if the length of
+    // the provided buffer (bytearray) is too small
+    check_esp_err(nvs_get_blob(self->namespace, key, value.buf, &length));
+    return MP_OBJ_NEW_SMALL_INT(length);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_3(esp32_nvs_get_blob_obj, esp32_nvs_get_blob);
+
+// esp32_nvs_erase_key erases one key.
+STATIC mp_obj_t esp32_nvs_erase_key(mp_obj_t self_in, mp_obj_t key_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    const char *key = mp_obj_str_get_str(key_in);
+    check_esp_err(nvs_erase_key(self->namespace, key));
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_2(esp32_nvs_erase_key_obj, esp32_nvs_erase_key);
+
+// esp32_nvs_commit commits any changes to flash.
+STATIC mp_obj_t esp32_nvs_commit(mp_obj_t self_in) {
+    esp32_nvs_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    check_esp_err(nvs_commit(self->namespace));
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(esp32_nvs_commit_obj, esp32_nvs_commit);
+
+STATIC const mp_rom_map_elem_t esp32_nvs_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR_get_i32), MP_ROM_PTR(&esp32_nvs_get_i32_obj) },
+    { MP_ROM_QSTR(MP_QSTR_set_i32), MP_ROM_PTR(&esp32_nvs_set_i32_obj) },
+    { MP_ROM_QSTR(MP_QSTR_get_blob), MP_ROM_PTR(&esp32_nvs_get_blob_obj) },
+    { MP_ROM_QSTR(MP_QSTR_set_blob), MP_ROM_PTR(&esp32_nvs_set_blob_obj) },
+    { MP_ROM_QSTR(MP_QSTR_erase_key), MP_ROM_PTR(&esp32_nvs_erase_key_obj) },
+    { MP_ROM_QSTR(MP_QSTR_commit), MP_ROM_PTR(&esp32_nvs_commit_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(esp32_nvs_locals_dict, esp32_nvs_locals_dict_table);
+
+const mp_obj_type_t esp32_nvs_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_NVS,
+    .print = esp32_nvs_print,
+    .make_new = esp32_nvs_make_new,
+    .locals_dict = (mp_obj_dict_t *)&esp32_nvs_locals_dict,
+};
diff --git a/ports/esp32/main/CMakeLists.txt b/ports/esp32/main/CMakeLists.txt
@@ -55,6 +55,7 @@ set(MICROPY_SOURCE_PORT
     ${PROJECT_DIR}/mpnimbleport.c
     ${PROJECT_DIR}/modsocket.c
     ${PROJECT_DIR}/modesp.c
+    ${PROJECT_DIR}/esp32_nvs.c
     ${PROJECT_DIR}/esp32_partition.c
     ${PROJECT_DIR}/esp32_rmt.c
     ${PROJECT_DIR}/esp32_ulp.c
diff --git a/ports/esp32/modesp32.c b/ports/esp32/modesp32.c
@@ -186,6 +186,7 @@ STATIC const mp_rom_map_elem_t esp32_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_hall_sensor), MP_ROM_PTR(&esp32_hall_sensor_obj) },
     { MP_ROM_QSTR(MP_QSTR_idf_heap_info), MP_ROM_PTR(&esp32_idf_heap_info_obj) },
 
+    { MP_ROM_QSTR(MP_QSTR_NVS), MP_ROM_PTR(&esp32_nvs_type) },
     { MP_ROM_QSTR(MP_QSTR_Partition), MP_ROM_PTR(&esp32_partition_type) },
     { MP_ROM_QSTR(MP_QSTR_RMT), MP_ROM_PTR(&esp32_rmt_type) },
     { MP_ROM_QSTR(MP_QSTR_ULP), MP_ROM_PTR(&esp32_ulp_type) },
diff --git a/ports/esp32/modesp32.h b/ports/esp32/modesp32.h
@@ -26,6 +26,7 @@
 #define RTC_LAST_EXT_PIN 39
 #define RTC_IS_VALID_EXT_PIN(pin_id) ((1ll << (pin_id)) & RTC_VALID_EXT_PINS)
 
+extern const mp_obj_type_t esp32_nvs_type;
 extern const mp_obj_type_t esp32_partition_type;
 extern const mp_obj_type_t esp32_rmt_type;
 extern const mp_obj_type_t esp32_ulp_type;
diff --git a/tests/esp32/esp32_nvs.py b/tests/esp32/esp32_nvs.py
@@ -0,0 +1,67 @@
+# Test the esp32 NVS class - access to esp-idf's Non-Volatile-Storage
+
+from esp32 import NVS
+
+nvs = NVS("mp-test")
+
+# test setting and gettin an integer kv
+nvs.set_i32("key1", 1234)
+print(nvs.get_i32("key1"))
+nvs.set_i32("key2", -503)
+print(nvs.get_i32("key2"))
+print(nvs.get_i32("key1"))
+
+# test setting and getting a blob kv using a bytearray
+blob1 = "testing a string as a blob"
+nvs.set_blob("blob1", blob1)
+buf1 = bytearray(len(blob1))
+len1 = nvs.get_blob("blob1", buf1)
+print(buf1)
+print(len(blob1), len1)
+
+# test setting and getting a blob kv using a string
+blob2 = b"testing a bytearray"
+nvs.set_blob("blob2", blob2)
+buf2 = bytearray(len(blob2))
+len2 = nvs.get_blob("blob2", buf2)
+print(buf2)
+print(len(blob2), len2)
+
+# test raising of error exceptions
+nvs.erase_key("key1")
+try:
+    nvs.erase_key("key1")  # not found
+except OSError as e:
+    print(e)
+try:
+    nvs.get_i32("key1")  # not found
+except OSError as e:
+    print(e)
+try:
+    nvs.get_i32("blob1")  # not found (blob1 exists but diff type)
+except OSError as e:
+    print(e)
+try:
+    buf3 = bytearray(10)
+    nvs.get_blob("blob1", buf3)  # invalid length (too short)
+except OSError as e:
+    print(e)
+
+nvs.commit()  # we're not verifying that this does anything, just doesn't error
+
+# test using a second namespace and that it doesn't interfere with first
+nvs2 = NVS("mp-test2")
+try:
+    print(nvs2.get_i32("key2"))
+except OSError as e:
+    print(e)
+nvs2.set_i32("key2", 7654)
+print(nvs.get_i32("key2"))
+print(nvs2.get_i32("key2"))
+
+# clean-up (the namespaces will remain)
+nvs.erase_key("key2")
+nvs.erase_key("blob1")
+nvs.erase_key("blob2")
+nvs2.erase_key("key2")
+nvs.commit()
diff --git a/tests/esp32/esp32_nvs.py.exp b/tests/esp32/esp32_nvs.py.exp
@@ -0,0 +1,14 @@
+1234
+-503
+1234
+bytearray(b'testing a string as a blob')
+26 26
+bytearray(b'testing a bytearray')
+19 19
+(-4354, 'ESP_ERR_NVS_NOT_FOUND')
+(-4354, 'ESP_ERR_NVS_NOT_FOUND')
+(-4354, 'ESP_ERR_NVS_NOT_FOUND')
+(-4364, 'ESP_ERR_NVS_INVALID_LENGTH')
+(-4354, 'ESP_ERR_NVS_NOT_FOUND')
+-503
+7654
