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": 2000,
  "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}

`FSStat`

Description

Get file-system path information.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute path under a mounted Storage file system.

Return Value

Type: Object
Description: Example: {"type":"File","size":16,"mtime_ms":1000,"exists":true}

Schema JSON

Show raw JSON


{
  "name": "FSStat",
  "description": "Get file-system path information.",
  "require_scheduler": false,
  "default_timeout_ms": 2000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"type\":\"File\",\"size\":16,\"mtime_ms\":1000,\"exists\":true}"
  }
}

CLI Command

svc_call Storage FSStat {"Path":null}

`FSList`

Description

List direct children under a file-system directory.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute directory path under a mounted Storage file system.

Return Value

Type: Array
Description: Example: [{"name":"file.txt","info":{"type":"File","size":16,"mtime_ms":1000,"exists":true}}]

Schema JSON

Show raw JSON


{
  "name": "FSList",
  "description": "List direct children under a file-system directory.",
  "require_scheduler": false,
  "default_timeout_ms": 2000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute directory path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"name\":\"file.txt\",\"info\":{\"type\":\"File\",\"size\":16,\"mtime_ms\":1000,\"exists\":true}}]"
  }
}

CLI Command

svc_call Storage FSList {"Path":null}

`FSMkdir`

Description

Create a file-system directory tree.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute directory path under a mounted Storage file system.

Schema JSON

Show raw JSON


{
  "name": "FSMkdir",
  "description": "Create a file-system directory tree.",
  "require_scheduler": false,
  "default_timeout_ms": 2000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute directory path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSMkdir {"Path":null}

`FSReadText`

Description

Read a file-system file as text.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute file path under a mounted Storage file system.

Return Value

Type: String
Description: File contents.

Schema JSON

Show raw JSON


{
  "name": "FSReadText",
  "description": "Read a file-system file as text.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute file path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "String",
    "description": "File contents."
  }
}

CLI Command

svc_call Storage FSReadText {"Path":null}

`FSRead`

Description

Read a file-system file into a mutable raw buffer.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute file path under a mounted Storage file system.
Buffer
- Type: RawBuffer
- Required: required
- Description: Mutable raw destination buffer.

Return Value

Type: Number
Description: Number of bytes read.

Schema JSON

Show raw JSON


{
  "name": "FSRead",
  "description": "Read a file-system file into a mutable raw buffer.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute file path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Buffer",
      "description": "Mutable raw destination buffer.",
      "type": "RawBuffer",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Number",
    "description": "Number of bytes read."
  }
}

CLI Command

svc_call Storage FSRead {"Path":null,"Buffer":null}

`FSWriteText`

Description

Write text to a file-system file.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute file path under a mounted Storage file system.
Data
- Type: String
- Required: required
- Description: Text content to write.

Schema JSON

Show raw JSON


{
  "name": "FSWriteText",
  "description": "Write text to a file-system file.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute file path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Data",
      "description": "Text content to write.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSWriteText {"Path":null,"Data":null}

`FSWrite`

Description

Write raw data to a file-system file.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute file path under a mounted Storage file system.
Data
- Type: RawBuffer
- Required: required
- Description: Raw source buffer.

Schema JSON

Show raw JSON


{
  "name": "FSWrite",
  "description": "Write raw data to a file-system file.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute file path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Data",
      "description": "Raw source buffer.",
      "type": "RawBuffer",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSWrite {"Path":null,"Data":null}

`FSRemove`

Description

Remove a file-system file or directory tree.

Execution

Requires scheduler: Not required

Parameters

Path
- Type: String
- Required: required
- Description: Absolute path under a mounted Storage file system.

Schema JSON

Show raw JSON


{
  "name": "FSRemove",
  "description": "Remove a file-system file or directory tree.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "Path",
      "description": "Absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSRemove {"Path":null}

`FSRename`

Description

Rename or move a file-system path.

Execution

Requires scheduler: Not required

Parameters

From
- Type: String
- Required: required
- Description: Source absolute path under a mounted Storage file system.
To
- Type: String
- Required: required
- Description: Destination absolute path under a mounted Storage file system.

Schema JSON

Show raw JSON


{
  "name": "FSRename",
  "description": "Rename or move a file-system path.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "From",
      "description": "Source absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "To",
      "description": "Destination absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSRename {"From":null,"To":null}

`FSCopyTree`

Description

Copy a file-system directory tree.

Execution

Requires scheduler: Not required

Parameters

From
- Type: String
- Required: required
- Description: Source absolute path under a mounted Storage file system.
To
- Type: String
- Required: required
- Description: Destination absolute path under a mounted Storage file system.
Overwrite
- Type: Boolean
- Required: optional
- Default: true
- Description: Overwrite existing destination files.

Schema JSON

Show raw JSON


{
  "name": "FSCopyTree",
  "description": "Copy a file-system directory tree.",
  "require_scheduler": false,
  "default_timeout_ms": 10000,
  "parameters": [
    {
      "name": "From",
      "description": "Source absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "To",
      "description": "Destination absolute path under a mounted Storage file system.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Overwrite",
      "description": "Overwrite existing destination files.",
      "type": "Boolean",
      "required": false,
      "default_value": true
    }
  ],
  "return_value": null
}

CLI Command

svc_call Storage FSCopyTree {"From":null,"To":null,"Overwrite":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

FSStat

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

FSList

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

FSMkdir

Description

Execution

Parameters

Schema JSON

CLI Command

FSReadText

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

FSRead

Description

Execution

Parameters

`KVList`

`KVSet`

`KVGet`

`KVErase`

`GetFileSystems`

`GetFileSystemCapacity`

`FSStat`

`FSList`

`FSMkdir`

`FSReadText`

`FSRead`

`FSWriteText`

`FSWrite`

`FSRemove`

`FSRename`

`FSCopyTree`

`MakeKVKey`

`MakeKVNamespace`