diff options
| -rw-r--r-- | docs/library/esp32.rst | 48 | ||||
| -rw-r--r-- | ports/esp32/esp32_nvs.c | 151 | ||||
| -rw-r--r-- | ports/esp32/main/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | ports/esp32/modesp32.c | 1 | ||||
| -rw-r--r-- | ports/esp32/modesp32.h | 1 | ||||
| -rw-r--r-- | tests/esp32/esp32_nvs.py | 67 | ||||
| -rw-r--r-- | tests/esp32/esp32_nvs.py.exp | 14 |
7 files changed, 283 insertions, 0 deletions
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst index c6777b8a7d..f179a31ef6 100644 --- 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 new file mode 100644 index 0000000000..d13151d3ce --- /dev/null +++ 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 index b6cf214bba..9fb48a9041 100644 --- 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 index d7c6bf0fa3..53ca7fdc60 100644 --- 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 index f4c0491f7c..18bd62ee41 100644 --- 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 new file mode 100644 index 0000000000..fd8b152ca7 --- /dev/null +++ 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 new file mode 100644 index 0000000000..33cdfd6df9 --- /dev/null +++ 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 |