Storage

[English]

组件注册表： espressif/brookesia_service_storage
辅助头文件： #include "brookesia/service_helper/system/storage.hpp"
辅助类： esp_brookesia::service::helper::Storage

概述

brookesia_service_storage 是为 ESP-Brookesia 生态系统提供的命名空间键值存储服务，提供：

命名空间管理：基于命名空间的键值对存储，支持多个独立的存储空间。
数据类型支持：支持布尔值、整数、字符串三种基本数据类型。
持久化存储：数据通过底层存储后端持久化，断电后不丢失。
线程安全：可选基于 TaskScheduler 实现异步任务调度，保证线程安全。
灵活查询：支持列出命名空间中的所有键值对，或按需获取指定键的值。

功能特性

命名空间管理

默认命名空间：如果不指定命名空间，将使用默认命名空间 "storage"。
多命名空间：可以创建多个命名空间来组织不同类型的数据。
命名空间隔离：不同命名空间的数据相互独立，互不影响。

支持的数据类型

布尔值（Bool）：true 或 false。
整数（Int）：32 位有符号整数。
字符串（String）：UTF-8 编码的字符串。

备注

除了上述三种基本数据类型外，Storage Helper 提供的 esp_brookesia::service::helper::Storage::save_key_value() 和 esp_brookesia::service::helper::Storage::get_key_value() 模板助手函数还支持存储和获取任意类型的数据。

核心功能

列出键信息：列出命名空间中所有键的信息（包括键名、类型等）。
设置键值对：支持批量设置多个键值对。
获取键值对：支持获取指定键的值，或获取命名空间中的所有键值对。
删除键值对：支持删除指定键，或清空整个命名空间。

服务接口

函数

`KVList`

描述

List key-value entries in a Storage namespace.

执行要求

是否需要调度器: 需要

参数

Nspace
- 类型: String
- 是否必填: 可选
- 默认值: "storage"
- 描述: Namespace to list (optional). Uses the default namespace when omitted.

返回值

类型: Array
描述: Example: [{"nspace":"storage","key":"key1","type":"String"},{"nspace":"storage","key":"key2","type":"Int"}]

Schema JSON

展开查看 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 命令

svc_call Storage KVList {"Nspace":null}

`KVSet`

描述

Set key-value pairs in a Storage namespace.

执行要求

是否需要调度器: 需要

参数

Nspace
- 类型: String
- 是否必填: 可选
- 默认值: "storage"
- 描述: Namespace to write (optional). Uses the default namespace when omitted or empty.
KeyValuePairs
- 类型: Object
- 是否必填: 必填
- 描述: Key-value pairs as a JSON object. Allowed value types: ["Bool","Int","String"]. Example: {"key1":"value1","key2":2,"key3":true}

Schema JSON

展开查看 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 命令

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

`KVGet`

描述

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

执行要求

是否需要调度器: 需要

参数

Nspace
- 类型: String
- 是否必填: 可选
- 默认值: "storage"
- 描述: Namespace to read (optional). Uses the default namespace when omitted.
Keys
- 类型: Array
- 是否必填: 可选
- 默认值: []
- 描述: Keys to read as JSON array<string> (optional). Returns all pairs when omitted. Example: ["key1","key2","key3"]

返回值

类型: Object
描述: Example: {"key1":"value1","key2":2,"key3":true}

Schema JSON

展开查看 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 命令

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

`KVErase`

描述

Erase key-value pairs from a Storage namespace.

执行要求

是否需要调度器: 需要

参数

Nspace
- 类型: String
- 是否必填: 可选
- 默认值: "storage"
- 描述: Namespace to erase (optional). Uses the default namespace when omitted.
Keys
- 类型: Array
- 是否必填: 可选
- 默认值: []
- 描述: Keys to erase as JSON array<string> (optional). Erases all pairs when omitted or empty. Example: ["key1","key2","key3"]

Schema JSON

展开查看 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 命令

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

`GetFileSystems`

描述

Get mounted storage file systems.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: 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

展开查看 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 命令

svc_call Storage GetFileSystems

`GetFileSystemCapacity`

描述

Get one mounted storage file system capacity.

执行要求

是否需要调度器: 需要

参数

MountPoint
- 类型: String
- 是否必填: 必填
- 描述: Mount point returned by GetFileSystems.

返回值

类型: Object
描述: Example: {"total_bytes":1048576,"used_bytes":262144,"free_bytes":786432}

Schema JSON

展开查看 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 命令

svc_call Storage GetFileSystemCapacity {"MountPoint":null}

`FSStat`

描述

Get file-system path information.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute path under a mounted Storage file system.

返回值

类型: Object
描述: Example: {"type":"File","size":16,"mtime_ms":1000,"exists":true}

Schema JSON

展开查看 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 命令

svc_call Storage FSStat {"Path":null}

`FSList`

描述

List direct children under a file-system directory.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute directory path under a mounted Storage file system.

返回值

类型: Array
描述: Example: [{"name":"file.txt","info":{"type":"File","size":16,"mtime_ms":1000,"exists":true}}]

Schema JSON

展开查看 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 命令

svc_call Storage FSList {"Path":null}

`FSMkdir`

描述

Create a file-system directory tree.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute directory path under a mounted Storage file system.

Schema JSON

展开查看 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 命令

svc_call Storage FSMkdir {"Path":null}

`FSReadText`

描述

Read a file-system file as text.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute file path under a mounted Storage file system.

返回值

类型: String
描述: File contents.

Schema JSON

展开查看 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 命令

svc_call Storage FSReadText {"Path":null}

`FSRead`

描述

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

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute file path under a mounted Storage file system.
Buffer
- 类型: RawBuffer
- 是否必填: 必填
- 描述: Mutable raw destination buffer.

返回值

类型: Number
描述: Number of bytes read.

Schema JSON

展开查看 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 命令

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

`FSWriteText`

描述

Write text to a file-system file.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute file path under a mounted Storage file system.
Data
- 类型: String
- 是否必填: 必填
- 描述: Text content to write.

Schema JSON

展开查看 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 命令

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

`FSWrite`

描述

Write raw data to a file-system file.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute file path under a mounted Storage file system.
Data
- 类型: RawBuffer
- 是否必填: 必填
- 描述: Raw source buffer.

Schema JSON

展开查看 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 命令

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

`FSRemove`

描述

Remove a file-system file or directory tree.

执行要求

是否需要调度器: 不需要

参数

Path
- 类型: String
- 是否必填: 必填
- 描述: Absolute path under a mounted Storage file system.

Schema JSON

展开查看 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 命令

svc_call Storage FSRemove {"Path":null}

`FSRename`

描述

Rename or move a file-system path.

执行要求

是否需要调度器: 不需要

参数

From
- 类型: String
- 是否必填: 必填
- 描述: Source absolute path under a mounted Storage file system.
To
- 类型: String
- 是否必填: 必填
- 描述: Destination absolute path under a mounted Storage file system.

Schema JSON

展开查看 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 命令

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

`FSCopyTree`

描述

Copy a file-system directory tree.

执行要求

是否需要调度器: 不需要

参数

From
- 类型: String
- 是否必填: 必填
- 描述: Source absolute path under a mounted Storage file system.
To
- 类型: String
- 是否必填: 必填
- 描述: Destination absolute path under a mounted Storage file system.
Overwrite
- 类型: Boolean
- 是否必填: 可选
- 默认值: true
- 描述: Overwrite existing destination files.

Schema JSON

展开查看 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 命令

svc_call Storage FSCopyTree {"From":null,"To":null,"Overwrite":null}

`MakeKVKey`

描述

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

执行要求

是否需要调度器: 不需要

参数

Parts
- 类型: Array
- 是否必填: 必填
- 描述: Name parts as JSON array<string>. Empty parts are rejected.
Separator
- 类型: String
- 是否必填: 可选
- 默认值: "."
- 描述: Separator inserted between name parts.

返回值

类型: Object
描述: 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

展开查看 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 命令

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

`MakeKVNamespace`

描述

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

执行要求

是否需要调度器: 不需要

参数

Parts
- 类型: Array
- 是否必填: 必填
- 描述: Namespace parts as JSON array<string>. Empty parts are rejected.
Separator
- 类型: String
- 是否必填: 可选
- 默认值: "."
- 描述: Separator inserted between namespace parts.

返回值

类型: Object
描述: Example: {"name":"Display","original_name":"Display","hashed":false,"warning":""}

Schema JSON

展开查看 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 命令

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

事件

无。

Storage

概述

功能特性

命名空间管理

支持的数据类型

核心功能

服务接口

函数

KVList

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

KVSet

描述

执行要求

参数

Schema JSON

CLI 命令

KVGet

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

KVErase

描述

执行要求

参数

Schema JSON

CLI 命令

GetFileSystems

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetFileSystemCapacity

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

FSStat

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

FSList

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

FSMkdir

描述

执行要求

参数

Schema JSON

CLI 命令

FSReadText

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

FSRead

描述

执行要求

参数

返回值

`KVList`

`KVSet`

`KVGet`

`KVErase`

`GetFileSystems`

`GetFileSystemCapacity`

`FSStat`

`FSList`

`FSMkdir`

`FSReadText`

`FSRead`

`FSWriteText`

`FSWrite`

`FSRemove`

`FSRename`

`FSCopyTree`

`MakeKVKey`

`MakeKVNamespace`