Storage

[中文]

Component registry: espressif/brookesia_service_storage
Helper header: #include "brookesia/service_helper/system/storage.hpp"
Helper class: esp_brookesia::service::helper::Storage

Overview

brookesia_service_storage provides namespace-based key-value 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 through the underlying storage backend.
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, Storage Helper templates esp_brookesia::service::helper::Storage::save_key_value() and esp_brookesia::service::helper::Storage::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/system/storage.hpp\"
Helper class: esp_brookesia::service::helper::Storage

Service Interfaces

Functions

`KVList`

Description

List key-value entries in a Storage namespace.

Execution

Requires scheduler: Required

Parameters

Nspace
- Type: String
- Required: optional
- Default: "storage"
- Description: Namespace to list (optional). Uses the default namespace when omitted.

Return Value

Type: Array
Description: Example: [{"nspace":"storage","key":"key1","type":"String"},{"nspace":"storage","key":"key2","type":"Int"}]

Schema JSON

Show raw JSON


{
  "name": "KVList",
  "description": "List key-value entries in a Storage namespace.",
  "require_scheduler": true,
  "default_timeout_ms": 1000,
  "parameters": [
    {
      "name": "Nspace",
      "description": "Namespace to list (optional). Uses the default namespace when omitted.",
      "type": "String",
      "required": false,
      "default_value": "storage"
    }
  ],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"nspace\":\"storage\",\"key\":\"key1\",\"type\":\"String\"},{\"nspace\":\"storage\",\"key\":\"key2\",\"type\":\"Int\"}]"
  }
}

CLI Command

svc_call Storage KVList {"Nspace":null}

`KVSet`

Description

Set key-value pairs in a Storage 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": "KVSet",
  "description": "Set key-value pairs in a Storage namespace.",
  "require_scheduler": true,
  "default_timeout_ms": 1000,
  "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
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage KVSet {"Nspace":null,"KeyValuePairs":null}

`KVGet`

Description

Get key-value pairs by keys from a Storage namespace.

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"]

Return Value

Type: Object
Description: Example: {"key1":"value1","key2":2,"key3":true}

Schema JSON

Show raw JSON


{
  "name": "KVGet",
  "description": "Get key-value pairs by keys from a Storage namespace.",
  "require_scheduler": true,
  "default_timeout_ms": 1000,
  "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": []
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"key1\":\"value1\",\"key2\":2,\"key3\":true}"
  }
}

CLI Command

svc_call Storage KVGet {"Nspace":null,"Keys":null}

`KVErase`

Description

Erase key-value pairs from a Storage 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": "KVErase",
  "description": "Erase key-value pairs from a Storage namespace.",
  "require_scheduler": true,
  "default_timeout_ms": 1000,
  "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": []
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage KVErase {"Nspace":null,"Keys":null}

`GetFileSystems`

Description

Get mounted storage file systems.

Execution

Requires scheduler: Required

Parameters

No parameters.

Return Value

Type: Array
Description: Example: [{"fs_type":"LittleFS","medium_type":"Flash","mount_point":"/littlefs","supports_directories":true},{"fs_type":"FATFS","medium_type":"SDCard","mount_point":"/sdcard","supports_directories":true}]

Schema JSON

Show raw JSON


{
  "name": "GetFileSystems",
  "description": "Get mounted storage file systems.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"fs_type\":\"LittleFS\",\"medium_type\":\"Flash\",\"mount_point\":\"/littlefs\",\"supports_directories\":true},{\"fs_type\":\"FATFS\",\"medium_type\":\"SDCard\",\"mount_point\":\"/sdcard\",\"supports_directories\":true}]"
  }
}

CLI Command

svc_call Storage GetFileSystems

`GetFileSystemCapacity`

Description

Get one mounted storage file system capacity.

Execution

Requires scheduler: Required

Parameters

MountPoint
- Type: String
- Required: required
- Description: Mount point returned by GetFileSystems.

Return Value

Type: Object
Description: Example: {"total_bytes":1048576,"used_bytes":262144,"free_bytes":786432}

Schema JSON

Show raw JSON


{
  "name": "GetFileSystemCapacity",
  "description": "Get one mounted storage file system capacity.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "MountPoint",
      "description": "Mount point returned by GetFileSystems.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"total_bytes\":1048576,\"used_bytes\":262144,\"free_bytes\":786432}"
  }
}

CLI Command

svc_call Storage GetFileSystemCapacity {"MountPoint":null}

`MakeKVKey`

Description

Generate a key that satisfies the active Storage KV backend limits.

Execution

Requires scheduler: Not required

Parameters

Parts
- Type: Array
- Required: required
- Description: Name parts as JSON array<string>. Empty parts are rejected.
Separator
- Type: String
- Required: optional
- Default: "."
- Description: Separator inserted between name parts.

Return Value

Type: Object
Description: Example: {"name":"h1abc","original_name":"bkl.display_lcd.On","hashed":true,"warning":"KV key exceeded backend limit and was replaced by a stable hash"}

Schema JSON

Show raw JSON


{
  "name": "MakeKVKey",
  "description": "Generate a key that satisfies the active Storage KV backend limits.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Parts",
      "description": "Name parts as JSON array<string>. Empty parts are rejected.",
      "type": "Array",
      "required": true,
      "default_value": null
    },
    {
      "name": "Separator",
      "description": "Separator inserted between name parts.",
      "type": "String",
      "required": false,
      "default_value": "."
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"name\":\"h1abc\",\"original_name\":\"bkl.display_lcd.On\",\"hashed\":true,\"warning\":\"KV key exceeded backend limit and was replaced by a stable hash\"}"
  }
}

CLI Command

svc_call Storage MakeKVKey {"Parts":null,"Separator":null}

`MakeKVNamespace`

Description

Generate a namespace that satisfies the active Storage KV backend limits.

Execution

Requires scheduler: Not required

Parameters

Parts
- Type: Array
- Required: required
- Description: Namespace parts as JSON array<string>. Empty parts are rejected.
Separator
- Type: String
- Required: optional
- Default: "."
- Description: Separator inserted between namespace parts.

Return Value

Type: Object
Description: Example: {"name":"Display","original_name":"Display","hashed":false,"warning":""}

Schema JSON

Show raw JSON


{
  "name": "MakeKVNamespace",
  "description": "Generate a namespace that satisfies the active Storage KV backend limits.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Parts",
      "description": "Namespace parts as JSON array<string>. Empty parts are rejected.",
      "type": "Array",
      "required": true,
      "default_value": null
    },
    {
      "name": "Separator",
      "description": "Separator inserted between namespace parts.",
      "type": "String",
      "required": false,
      "default_value": "."
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"name\":\"Display\",\"original_name\":\"Display\",\"hashed\":false,\"warning\":\"\"}"
  }
}

CLI Command

svc_call Storage MakeKVNamespace {"Parts":null,"Separator":null}

Events

This contract does not publish standard event schemas.

Storage

Overview

Features

Namespaces

Supported Types

Core Capabilities

Standard Include / Helper Class

Service Interfaces

Functions

KVList

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

KVSet

Description

Execution

Parameters

Schema JSON

CLI Command

KVGet

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

KVErase

Description

Execution

Parameters

Schema JSON

CLI Command

GetFileSystems

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetFileSystemCapacity

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

MakeKVKey

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

MakeKVNamespace

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

Events

Related Types and Configs

`KVList`

`KVSet`

`KVGet`

`KVErase`

`GetFileSystems`

`GetFileSystemCapacity`

`MakeKVKey`

`MakeKVNamespace`