NVS

[中文]

  • Component registry: espressif/brookesia_service_nvs

  • Helper header: #include "brookesia/service_helper/nvs.hpp"

  • Helper class: esp_brookesia::service::helper::NVS

Overview

brookesia_service_nvs provides NVS (non-volatile storage) for the ESP-Brookesia ecosystem:

  • Namespaces: Key–value storage partitioned by namespace.

  • Types: Boolean, 32-bit signed integer, and UTF-8 string.

  • Persistence: Data survives power cycles in the NVS partition.

  • Thread safety: Optional TaskScheduler–based async execution.

  • Queries: List keys in a namespace or read specific keys.

Features

Namespaces

  • Default: If omitted, namespace "storage" is used.

  • Multiple: Create several namespaces for different data.

  • Isolation: Namespaces are independent.

Supported Types

  • Bool: true / false.

  • Int: 32-bit signed integer.

  • String: UTF-8 string.

Note

Beyond these primitives, NVS Helper templates esp_brookesia::service::helper::NVS::save_key_value() and esp_brookesia::service::helper::NVS::get_key_value() can store and retrieve arbitrary types.

Core Capabilities

  • List key metadata in a namespace.

  • Set multiple key–value pairs in batch.

  • Read one key or all pairs in a namespace.

  • Delete a key or clear a namespace.

Standard Include / Helper Class

  • Standard include: #include \"brookesia/service_helper/nvs.hpp\"

  • Helper class: esp_brookesia::service::helper::NVS

Service Interfaces

Functions

List

Description

List key-value entries in an NVS namespace. Return type: JSON array<object>. Example: [{“nspace”:”storage”,”key”:”key1”,”type”:”String”},{“nspace”:”storage”,”key”:”key2”,”type”:”Int”}]

Execution

  • Requires scheduler: Required

Parameters

  • Nspace

    • Type: String

    • Required: optional

    • Default: "storage"

    • Description: Namespace to list (optional). Uses the default namespace when omitted.

Schema JSON
Show raw JSON 

{
  "name": "List",
  "description": "List key-value entries in an NVS namespace. Return type: JSON array<object>. Example: [{\"nspace\":\"storage\",\"key\":\"key1\",\"type\":\"String\"},{\"nspace\":\"storage\",\"key\":\"key2\",\"type\":\"Int\"}]",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Nspace",
      "description": "Namespace to list (optional). Uses the default namespace when omitted.",
      "type": "String",
      "required": false,
      "default_value": "storage"
    }
  ]
}
CLI Command
svc_call NVS List {"Nspace":null}

Set

Description

Set key-value pairs in an NVS namespace.

Execution

  • Requires scheduler: Required

Parameters

  • Nspace

    • Type: String

    • Required: optional

    • Default: "storage"

    • Description: Namespace to write (optional). Uses the default namespace when omitted or empty.

  • KeyValuePairs

    • Type: Object

    • Required: required

    • Description: Key-value pairs as a JSON object. Allowed value types: [“Bool”,”Int”,”String”]. Example: {“key1”:”value1”,”key2”:2,”key3”:true}

Schema JSON
Show raw JSON 

{
  "name": "Set",
  "description": "Set key-value pairs in an NVS namespace.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Nspace",
      "description": "Namespace to write (optional). Uses the default namespace when omitted or empty.",
      "type": "String",
      "required": false,
      "default_value": "storage"
    },
    {
      "name": "KeyValuePairs",
      "description": "Key-value pairs as a JSON object. Allowed value types: [\"Bool\",\"Int\",\"String\"]. Example: {\"key1\":\"value1\",\"key2\":2,\"key3\":true}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}
CLI Command
svc_call NVS Set {"Nspace":null,"KeyValuePairs":null}

Get

Description

Get key-value pairs by keys from an NVS namespace. Return type: JSON object. Example: {“key1”:”value1”,”key2”:2,”key3”:true}

Execution

  • Requires scheduler: Required

Parameters

  • Nspace

    • Type: String

    • Required: optional

    • Default: "storage"

    • Description: Namespace to read (optional). Uses the default namespace when omitted.

  • Keys

    • Type: Array

    • Required: optional

    • Default: []

    • Description: Keys to read as JSON array<string> (optional). Returns all pairs when omitted. Example: [“key1”,”key2”,”key3”]

Schema JSON
Show raw JSON 

{
  "name": "Get",
  "description": "Get key-value pairs by keys from an NVS namespace. Return type: JSON object. Example: {\"key1\":\"value1\",\"key2\":2,\"key3\":true}",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Nspace",
      "description": "Namespace to read (optional). Uses the default namespace when omitted.",
      "type": "String",
      "required": false,
      "default_value": "storage"
    },
    {
      "name": "Keys",
      "description": "Keys to read as JSON array<string> (optional). Returns all pairs when omitted. Example: [\"key1\",\"key2\",\"key3\"]",
      "type": "Array",
      "required": false,
      "default_value": []
    }
  ]
}
CLI Command
svc_call NVS Get {"Nspace":null,"Keys":null}

Erase

Description

Erase key-value pairs from an NVS namespace.

Execution

  • Requires scheduler: Required

Parameters

  • Nspace

    • Type: String

    • Required: optional

    • Default: "storage"

    • Description: Namespace to erase (optional). Uses the default namespace when omitted.

  • Keys

    • Type: Array

    • Required: optional

    • Default: []

    • Description: Keys to erase as JSON array<string> (optional). Erases all pairs when omitted or empty. Example: [“key1”,”key2”,”key3”]

Schema JSON
Show raw JSON 

{
  "name": "Erase",
  "description": "Erase key-value pairs from an NVS namespace.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Nspace",
      "description": "Namespace to erase (optional). Uses the default namespace when omitted.",
      "type": "String",
      "required": false,
      "default_value": "storage"
    },
    {
      "name": "Keys",
      "description": "Keys to erase as JSON array<string> (optional). Erases all pairs when omitted or empty. Example: [\"key1\",\"key2\",\"key3\"]",
      "type": "Array",
      "required": false,
      "default_value": []
    }
  ]
}
CLI Command
svc_call NVS Erase {"Nspace":null,"Keys":null}

Events

This contract does not publish standard event schemas.