esp-nvs-utils-js

NVS (Non-volatile storage) partition parser and encoder for Espressif's ESP32 line of chips. It is written in TypeScript and supports running in the browser and node.js

See the official esp-idf documentation about the NVS library for more information about NVS.

Installation

npm i --save esp-nvs-utils

API

/**
 * Encoding/type of an NVS entry value.
 */
export type NVSEncoding = "u8" | "i8" | "u16" | "i16" | "u32" | "i32" | "u64" | "i64" | "string" | "blob_data";
/**
 * A single key-value entry within a namespace.
 *
 * value type by encoding:
 *   u8/i8/u16/i16/u32/i32 → number
 *   u64/i64               → bigint (full 64-bit range)
 *   string                → string
 *   blob_data             → Uint8Array
 */
export interface NVSValue {
    name: string;
    encoding: NVSEncoding;
    value: number | bigint | string | Uint8Array;
}
/**
 * A decoded NVS partition.
 * Keys are namespace names, values are the entries within that namespace.
 */
export type NVSNamespaces = Record<string, NVSValue[]>;

/**
 * Encode an NVSNamespaces object into a binary NVS partition.
 * Output is always V2 (multipage blob support enabled).
 * Partition size is auto-calculated based on data volume.
 */
export function encodeNVS(namespaces: NVSNamespaces): Uint8Array;

/**
 * Decode an NVS partition binary into structured namespaces.
 *
 * Handles V1 (single-page blobs) and V2 (multi-page blobs).
 * Does not support encrypted partitions.
 */
export declare function decodeNVS(data: ArrayBuffer | Uint8Array): NVSNamespaces;

Usage

Consult the following example:

import { decodeNVS, encodeNVS, type NVSNamespaces } from "esp-nvs-utils";

const input: NVSNamespaces = {
    namespace1: [
        { name: "my_blob", encoding: "blob_data", value: new Uint8Array([1, 2, 3, 4]) },
    ],
    namespace2: [
        { name: "my_int", encoding: "u32", value: 42 },
        { name: "a_str", encoding: "string", value: "ExampleNetwork" },
       
    ],
};

const binary = encodeNVS(input);

const decoded = decodeNVS(binary);

console.log(decoded.namespace1[0]);

console.log(decoded.namespace2[0]);
console.log(decoded.namespace2[1]);

Development

# Install dev dependenciess
npm install

# Run unit-tests (requires Python and python-cryptography)
npm run test

# Build
npm run build

# Format
npm run format

# Lint
npm run lint

License

Apache-2.0, see ./LICENSE. This project includes the original Python NVS parser/generator pulled from esp-idf under ./python_original, which is used during unit-tests. It is licensed under the same license.