ESP32 Non-Volatile Storage reader

A JavaScript browser library for reading ESP32 Non-Volatile Storage (NVS) entries over USB using WebSerial.

Highlights

• Reads specified NVS partition or auto-detects using device's partition table
• Supports all NVS types (integers, strings, blobs)
• Communicates directly with the ESP32 over USB using WebSerial
• Efficiently reads just enough data to find what you are looking for
• Can retrieve specific entry or get all entries
• Provides both function-based and class-based interfaces
• Includes built-in output formats for JSON and HTML
• Easily customizable output via user-friendly iterator pattern

Browser Support

WebSerial is a non-standard feature and is only supported in Chromium-based browsers. See CanIUse for browser support.

Live Demos

• Simple example
• JSON example
• WiFi example
• Table example

Install

The library can either be downloaded using NPM or loaded on request from a CDN. Local install is only required for full TypeScript types support.

CDN

Import the library from CDN into your JavaScript code like this:

import { NVS } from "https://cdn.jsdelivr.net/gh/FanatiQS/esp-nvs-js@master/src/index.js";
Copy

NPM

Install the library through NPM and then import it into your JavaScript code like this:

npm install fanatiqs/esp-nvs-js
Copy

import { NVS } from "esp-nvs-js";
Copy

Usage

Other than the limited browser support mentioned above, WebSerial also only works on HTTPS/localhost and can only be triggered by a UserGesture, not on load. This means that all examples need to be called from some kind of user input, like a button press or other form of user initiated trigger.

Example 1

Get the value for a specific entry. Look at examples/simple.html (demo) for a complete example.

const nvs = new NVS(await navigator.serial.requestPort());
const chan = await nvs.get("nvs.net80211", "sta.chan");
console.log(chan);
Copy

Example 2

Get all values as JSON. Look at examples/json.html (demo) for a complete example.

const nvs = new NVS(await navigator.serial.requestPort());
console.log(await nvs.toJSON());
Copy

Example 3

Render all values in HTML table. Look at examples/table.html (demo) for a complete example.

const nvs = new NVS(await navigator.serial.requestPort());
document.body.appendChild(await nvs.toHTML());
Copy

Example 4

Get all values through iterator. Look at examples/iterator.html (demo) for a complete example.

const nvs = new NVS(await navigator.serial.requestPort());
await nvs.all();
for (const [ namespace, key, value ] of nvs) {
	console.log(namespace, key, value);
}
Copy

API

The API documentation is available here.

Limitations

• No support for encrypted NVS partitions
• No delete or write support

Known bugs

The class implementation of the parser can not run overlapped. If multiple calls to the parser are done without awaiting result from the previous one first, it will drop entries.

// This silently drops data
const [ value1, value2 ] = await Promise.all([
	nvs.get("foo", "bar"),
	nvs.get("foo", "baz")
]);

// This works correctly
const value1 = await nvs.get("foo", "bar");
const value2 = await nvs.get("foo", "baz");
Copy