Access ESP32 non-volatile storage using XOD

Introduction

Data written to the ESP32's non-volatile storage (NVS) will persist when the device is reset or powered off. This makes the NVS a useful place to permanently store configuration or calibration data. This tutorial provides a guide to accessing the NVS using the XOD visual programming language with the esp32-preferences library.

The XOD esp32-preferences library is a wrapper for Espressif's preferences Arduino library. It stores data in NVS as key-value pairs. The keys are defined within a namespace to ensure that they are unique. If you have not encountered the term namespace before, a familiar example is a directory of files on your computer. The directory is the namespace and within the directory all file names (keys) must be unique. Two different directories (namespaces) could each contain a file (key) named "readme.txt".

Add ESP32 board to XOD IDE

You won't find the ESP32 on the list of board models in the XOD IDE, but it can easily be added.

In your user directory you will find a directory named xod. Within this directory is a file named extra.txt.

Add the following line to the extra.txt file:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

This line is the URL of a JSON file which describes the ESP32 board. The ESP32 Dev Module should now appear in the list of board models in the XOD IDE; if it doesn't, click the Refresh button:

When you first try to upload a patch to the ESP32 you will be prompted to install dependencies. Click Download & Install.

The XOD IDE will display a message to confirm that the dependencies have been successfully installed:

Install esp32-preferences library

We are now ready to install the esp32-preferences library. In XOD IDE, hit “File → Add Library” and enter the full library name:

wayland/esp32-preferences

See Using libraries for more information.

Following installation in the IDE workspace, the library will be visible in the project browser. To find out the function of a node, select the node and hit H to invoke help:

The nodes of the esp32-preferences library

The preferences node creates a preferences object that represents the NVS. A preferences node is required for all patches using the esp32-prefrences library.

Various action nodes are provided to operate on the preferences object. The begin node opens the specified namespace. If RO (read only) is set to false, then storage will be opened in read/write mode. If the namespace does not exist, then it will be created if RO is set to False. The end node will close the open namespace.

Data are stored as key-value pairs using the put nodes. Three data types are supported, byte (put-byte), number (put-number) and string (put-string).

The get-byte, get-number and get-string nodes are used to retrieve data from the open namespace.

A key-value pair can be deleted from the open namespace using the remove node. This functionality is demonstrated in the library's example-remove-key patch.

All key-value pairs can be deleted from the open namespace using the clear node (see example-store-retrieve).

The entire NVS can be erased and reinitialized using the erase-nvs node (see example-erase-nvs).

Store data

Below is a patch demonstrating how to store data in NVS. In this example we will store the value of Pi in a namespace called "math constants". The begin node opens the "math constants" namespace in read/write mode (if the "math constants" namespace doesn't exist, the begin node will create it). The put-number node stores the value of Pi as a number, identified by the key "pi". Once the key-value pair has been written, the namespace is closed using the end node.

N.B. XOD has a Pi node, so in practice there would be no need to store the value of Pi.

Retrieve data

The patch below demonstrates how to retrieve the datum store in the previous example. The namespace "math constants" can be opened in read-only mode, as nothing will be written to it. The value identified by the key "pi" can be retrieved using the get-number node. The format number node is used to display the value of "pi" to six decimal places (by default, the number would be rounded to two decimal places). Run the patch in the debugger and send a pulse using the tweak-pulse node to initiate the process of reading from NVS.

A boot counter

The esp32-preferences library includes an example-boot-count patch which records the number of times the microcontroller has been booted and displays the count on an I²C LCD. Detailed comments are provided on the patch itself, so further explanation will not be provided here.

The I²C LCD is connected to the ESP32 using four wires:

• LCD GND – ESP32 GND
• LCD VCC – ESP32 5V
• LCD SDA – ESP32 GPIO21
• LCD SCL – ESP32 GPIO22

On the first boot following upload of the patch, the LCD should display a count of one. The count will be incremented on each subsequent boot.

Summary

The esp32-preferences library should be useful for xoders needing to store data in the NVS of the ESP32. Please note that although you can read from NVS as many times as you like, the number of write-cycles is limited to 100, 000 to 1, 000, 000 (see https://randomnerdtutorials.com/esp32-flash-memory/).