设备控制

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

概述

brookesia_service_device 是面向应用层的设备控制服务。它不是新的硬件驱动，而是应用层访问 HAL 的统一服务接口：服务启动后会发现当前已初始化的 HAL 接口，并把常用的控制类和状态获取类能力封装成 Service 函数与事件。

典型使用方式是：

应用层只通过 service::helper::Device 调用函数或订阅事件。
HAL adaptor/board 负责提供底层 AudioCodecPlayerIface、DisplayBacklightIface、StorageFsIface、PowerBatteryIface、ProtocolSntpIface 等接口。
brookesia_service_device 在中间完成参数校验、状态缓存、事件发布，以及部分状态持久化。

因此，应用代码通常不需要直接持有 HAL interface 指针，除非需要访问非常底层或板级私有能力。

功能特性

能力发现

服务提供 GetCapabilities 函数，用于返回当前系统已经注册的 HAL 接口能力。应用可先查询能力，再决定是否显示对应 UI 或调用相关控制函数。

常见能力包括：

HAL 接口	典型用途
`BoardInfoIface`	获取板卡名称、芯片、版本、厂商等静态信息
`DisplayBacklightIface`	设置/查询背光亮度和背光开关状态
`AudioCodecPlayerIface`	设置/查询播放音量和静音状态
`StorageFsIface`	获取已挂载文件系统列表
`PowerBatteryIface`	获取电池信息、状态和充电配置，支持时可控制充电
`ProtocolSntpIface`	配置 NTP 服务器和时区，启动或停止 SNTP，并查询时间同步状态

控制类接口

控制类接口用于修改设备状态，主要面向 UI、Agent 工具调用或远程控制场景：

显示控制：设置背光亮度百分比，设置背光开关状态。
音频控制：设置播放器音量百分比，设置播放器静音状态。
电源控制：在 HAL 支持时设置电池充电配置，或启用/禁用充电。
SNTP 控制：设置 NTP 服务器和时区，启动或停止时间同步，并查询时间同步状态。
数据重置：清除服务保存的音量、静音、亮度和 SNTP 状态并恢复默认值。

亮度和音量传入值使用应用层百分比 [0, 100]，服务会根据 Kconfig 中配置的硬件最小/最大值映射到底层 HAL。

状态获取类接口

状态获取类接口用于读取设备状态或静态信息：

能力与板卡信息：获取当前 HAL 能力快照，获取板卡静态信息。
显示状态：读取当前背光亮度百分比和背光开关状态。
音频状态：读取当前目标音量百分比和静音状态。
存储状态：读取已挂载文件系统及其挂载点。
电池状态：读取电池能力信息、电压、电量百分比、充电状态、低电量/严重低电量状态等。
SNTP 状态：读取配置的 NTP 服务器、时区，以及系统时间是否已经同步。

事件通知

服务会在状态变化时发布事件，应用层可以通过 service::helper::Device::subscribe_event 订阅：

DisplayBacklightBrightnessChanged
DisplayBacklightOnOffChanged
AudioPlayerVolumeChanged
AudioPlayerMuteChanged
PowerBatteryStateChanged
PowerBatteryChargeConfigChanged

其中电池状态会按配置周期轮询 HAL，检测到快照变化后发布事件。

持久化状态

当系统启用并启动 brookesia_service_storage 时，Device 服务会尝试保存和恢复以下应用层状态：

播放器音量
播放器静音
背光亮度
SNTP 时区
SNTP NTP 服务器列表

如果 Storage 服务不可用，Device 服务仍可工作，只是这些状态不会跨重启保存。

使用建议

在应用启动阶段先初始化所需 HAL 设备，再启动 ServiceManager 和 Device 服务。
调用控制接口前先通过 GetCapabilities 判断能力是否存在。
需要时间同步时启用 HAL General SNTP 实现。
网络配置完成后显式调用 StartSntp；Device 服务会准备 SNTP，但不会自动开始同步。
对 UI 和 Agent 工具调用，优先使用 Device 服务作为访问 HAL 的入口，避免业务层直接依赖具体板级 HAL 实现。
对实时音频流、显示刷图等高频数据通道，仍应使用专门服务或 HAL 接口，不建议通过 Device 服务承载大数据流。

服务接口

函数

`GetCapabilities`

描述

Get available HAL devices and interfaces.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: Example: [{"name":"General","interfaces":[{"type_name":"SystemBoardInfo","instance_name":"System:BoardInfo"}]},{"name":"Display","interfaces":[{"type_name":"DisplayPanel","instance_name":"Display:PanelA"},{"type_name":"DisplayPanel","instance_name":"Display:PanelB"}]}]

Schema JSON

展开查看 JSON


{
  "name": "GetCapabilities",
  "description": "Get available HAL devices and interfaces.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"name\":\"General\",\"interfaces\":[{\"type_name\":\"SystemBoardInfo\",\"instance_name\":\"System:BoardInfo\"}]},{\"name\":\"Display\",\"interfaces\":[{\"type_name\":\"DisplayPanel\",\"instance_name\":\"Display:PanelA\"},{\"type_name\":\"DisplayPanel\",\"instance_name\":\"Display:PanelB\"}]}]"
  }
}

CLI 命令

svc_call Device GetCapabilities

`GetBoardInfo`

描述

Get static board information.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"name":"esp32_s3_touch_amoled_1_8","chip":"ESP32-S3","version":"v1.0","description":"Example board information","manufacturer":"Espressif"}

Schema JSON

展开查看 JSON


{
  "name": "GetBoardInfo",
  "description": "Get static board information.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"name\":\"esp32_s3_touch_amoled_1_8\",\"chip\":\"ESP32-S3\",\"version\":\"v1.0\",\"description\":\"Example board information\",\"manufacturer\":\"Espressif\"}"
  }
}

CLI 命令

svc_call Device GetBoardInfo

`GetCameraDeviceInfos`

描述

Get available camera devices.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: Example: [{"id":0,"name":"camera","device_path":"/dev/video0","supported_formats":["YUV422"]}]

Schema JSON

展开查看 JSON


{
  "name": "GetCameraDeviceInfos",
  "description": "Get available camera devices.",
  "require_scheduler": true,
  "default_timeout_ms": 2000,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"id\":0,\"name\":\"camera\",\"device_path\":\"/dev/video0\",\"supported_formats\":[\"YUV422\"]}]"
  }
}

CLI 命令

svc_call Device GetCameraDeviceInfos

`GetNetworkConnectivityInfo`

描述

Get current network connectivity status.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: Example: [{"instance_name":"Network:Connectivity:0","status":{"interface_type":"WifiStation","link_state":"Up","ip_state":"Ready","reachability":"LocalOnly","ip_info":null,"signal_dbm":null,"connected_duration_ms":null},"state":"LocalNetworkReady","network_ready":true,"internet_ready":false}]

Schema JSON

展开查看 JSON


{
  "name": "GetNetworkConnectivityInfo",
  "description": "Get current network connectivity status.",
  "require_scheduler": true,
  "default_timeout_ms": 2000,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"instance_name\":\"Network:Connectivity:0\",\"status\":{\"interface_type\":\"WifiStation\",\"link_state\":\"Up\",\"ip_state\":\"Ready\",\"reachability\":\"LocalOnly\",\"ip_info\":null,\"signal_dbm\":null,\"connected_duration_ms\":null},\"state\":\"LocalNetworkReady\",\"network_ready\":true,\"internet_ready\":false}]"
  }
}

CLI 命令

svc_call Device GetNetworkConnectivityInfo

`GetPowerBatteryInfo`

描述

Get static power battery information.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"name":"MainBattery","chemistry":"Li-ion","abilities":["Voltage","Percentage","ChargeState"]}

Schema JSON

展开查看 JSON


{
  "name": "GetPowerBatteryInfo",
  "description": "Get static power battery information.",
  "require_scheduler": true,
  "default_timeout_ms": 2000,
  "parameters": [],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"name\":\"MainBattery\",\"chemistry\":\"Li-ion\",\"abilities\":[\"Voltage\",\"Percentage\",\"ChargeState\"]}"
  }
}

CLI 命令

svc_call Device GetPowerBatteryInfo

`GetPowerBatteryState`

描述

Get current power battery state.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"is_present":true,"power_source":"Battery","charge_state":"NotCharging","level_source":"VoltageCurve","voltage_mv":3920,"percentage":67,"vbus_voltage_mv":null,"system_voltage_mv":null,"is_low":false,"is_critical":false}

Schema JSON

展开查看 JSON


{
  "name": "GetPowerBatteryState",
  "description": "Get current power battery state.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"is_present\":true,\"power_source\":\"Battery\",\"charge_state\":\"NotCharging\",\"level_source\":\"VoltageCurve\",\"voltage_mv\":3920,\"percentage\":67,\"vbus_voltage_mv\":null,\"system_voltage_mv\":null,\"is_low\":false,\"is_critical\":false}"
  }
}

CLI 命令

svc_call Device GetPowerBatteryState

`GetPowerBatteryChargeConfig`

描述

Get current power battery charge configuration.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"enabled":true,"target_voltage_mv":4200,"charge_current_ma":500,"precharge_current_ma":100,"termination_current_ma":100}

Schema JSON

展开查看 JSON


{
  "name": "GetPowerBatteryChargeConfig",
  "description": "Get current power battery charge configuration.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"enabled\":true,\"target_voltage_mv\":4200,\"charge_current_ma\":500,\"precharge_current_ma\":100,\"termination_current_ma\":100}"
  }
}

CLI 命令

svc_call Device GetPowerBatteryChargeConfig

`SetPowerBatteryChargeConfig`

描述

Set power battery charge configuration.

执行要求

是否需要调度器: 需要

参数

Config
- 类型: Object
- 是否必填: 必填
- 描述: Battery charge configuration object.

Schema JSON

展开查看 JSON


{
  "name": "SetPowerBatteryChargeConfig",
  "description": "Set power battery charge configuration.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Config",
      "description": "Battery charge configuration object.",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call Device SetPowerBatteryChargeConfig {"Config":null}

`SetPowerBatteryChargingEnabled`

描述

Enable or disable battery charging.

执行要求

是否需要调度器: 需要

参数

Enabled
- 类型: Boolean
- 是否必填: 必填
- 描述: True to enable charging, false to disable charging.

Schema JSON

展开查看 JSON


{
  "name": "SetPowerBatteryChargingEnabled",
  "description": "Enable or disable battery charging.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Enabled",
      "description": "True to enable charging, false to disable charging.",
      "type": "Boolean",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call Device SetPowerBatteryChargingEnabled {"Enabled":null}

事件

`PowerBatteryStateChanged`

描述

Emitted when the power battery state snapshot changes.

执行要求

是否需要调度器: 需要

参数

State
- 类型: Object
- 描述: Current power battery state snapshot.

Schema JSON

展开查看 JSON


{
  "name": "PowerBatteryStateChanged",
  "description": "Emitted when the power battery state snapshot changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "State",
      "description": "Current power battery state snapshot.",
      "type": "Object"
    }
  ]
}

CLI 命令

svc_subscribe Device PowerBatteryStateChanged

`PowerBatteryChargeConfigChanged`

描述

Emitted when the power battery charge configuration changes.

执行要求

是否需要调度器: 需要

参数

Config
- 类型: Object
- 描述: Current power battery charge configuration.

Schema JSON

展开查看 JSON


{
  "name": "PowerBatteryChargeConfigChanged",
  "description": "Emitted when the power battery charge configuration changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Config",
      "description": "Current power battery charge configuration.",
      "type": "Object"
    }
  ]
}

CLI 命令

svc_subscribe Device PowerBatteryChargeConfigChanged

设备控制

概述

功能特性

能力发现

控制类接口

状态获取类接口

事件通知

持久化状态

使用建议

服务接口

函数

GetCapabilities

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetBoardInfo

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetCameraDeviceInfos

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetNetworkConnectivityInfo

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetPowerBatteryInfo

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetPowerBatteryState

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetPowerBatteryChargeConfig

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

SetPowerBatteryChargeConfig

描述

执行要求

参数

Schema JSON

CLI 命令

SetPowerBatteryChargingEnabled

描述

执行要求

参数

Schema JSON

CLI 命令

事件

PowerBatteryStateChanged

描述

执行要求

参数

Schema JSON

CLI 命令

PowerBatteryChargeConfigChanged

`GetCapabilities`

`GetBoardInfo`

`GetCameraDeviceInfos`

`GetNetworkConnectivityInfo`

`GetPowerBatteryInfo`

`GetPowerBatteryState`

`GetPowerBatteryChargeConfig`

`SetPowerBatteryChargeConfig`

`SetPowerBatteryChargingEnabled`

`PowerBatteryStateChanged`

`PowerBatteryChargeConfigChanged`