设备控制

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

概述

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

典型使用方式是：

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

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

功能特性

能力发现

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

常见能力包括：

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

控制类接口

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

显示控制：设置背光亮度百分比，设置背光开关状态。
音频控制：设置播放器音量百分比，设置播放器静音状态。
电源控制：在 HAL 支持时设置电池充电配置，或启用/禁用充电。
数据重置：清除服务保存的音量、静音、亮度等持久化状态并恢复默认值。

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

状态获取类接口

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

能力与板卡信息：获取当前 HAL 能力快照，获取板卡静态信息。
显示状态：读取当前背光亮度百分比和背光开关状态。
音频状态：读取当前目标音量百分比和静音状态。
存储状态：读取已挂载文件系统及其挂载点。
电池状态：读取电池能力信息、电压、电量百分比、充电状态、低电量/严重低电量状态等。

事件通知

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

DisplayBacklightBrightnessChanged
DisplayBacklightOnOffChanged
AudioPlayerVolumeChanged
AudioPlayerMuteChanged
PowerBatteryStateChanged
PowerBatteryChargeConfigChanged

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

持久化状态

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

播放器音量
播放器静音
背光亮度

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

使用建议

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

服务接口

函数

`GetCapabilities`

描述

Get device control service capabilities. Return type: JSON object. Example: {"BoardInfo":["General:BoardInfo"],"DisplayPanel":["Display:PanelA","Display:PanelB"]}

执行要求

是否需要调度器: 不需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetCapabilities",
  "description": "Get device control service capabilities. Return type: JSON object. Example: {\"BoardInfo\":[\"General:BoardInfo\"],\"DisplayPanel\":[\"Display:PanelA\",\"Display:PanelB\"]}",
  "require_scheduler": false,
  "parameters": []
}

CLI 命令

svc_call Device GetCapabilities

`GetBoardInfo`

描述

Get static board information. Return type: JSON 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. Return type: JSON object. Example: {\"name\":\"esp32_s3_touch_amoled_1_8\",\"chip\":\"ESP32-S3\",\"version\":\"v1.0\",\"description\":\"Example board information\",\"manufacturer\":\"Espressif\"}",
  "require_scheduler": false,
  "parameters": []
}

CLI 命令

svc_call Device GetBoardInfo

`SetDisplayBacklightBrightness`

描述

Set display backlight brightness percentage.

执行要求

是否需要调度器: 需要

参数

Brightness
- 类型: Number
- 是否必填: 必填
- 描述: Backlight brightness percentage in range [0, 100]. The actual brightness will be mapped to the hardware range [BROOKESIA_SERVICE_DEVICE_DISPLAY_BACKLIGHT_BRIGHTNESS_MIN, BROOKESIA_SERVICE_DEVICE_DISPLAY_BACKLIGHT_BRIGHTNESS_MAX].

Schema JSON

展开查看 JSON


{
  "name": "SetDisplayBacklightBrightness",
  "description": "Set display backlight brightness percentage.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Brightness",
      "description": "Backlight brightness percentage in range [0, 100]. The actual brightness will be mapped to the hardware range [BROOKESIA_SERVICE_DEVICE_DISPLAY_BACKLIGHT_BRIGHTNESS_MIN, BROOKESIA_SERVICE_DEVICE_DISPLAY_BACKLIGHT_BRIGHTNESS_MAX].",
      "type": "Number",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Device SetDisplayBacklightBrightness {"Brightness":null}

`GetDisplayBacklightBrightness`

描述

Get current display backlight brightness percentage [0, 100]. Return type: number.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetDisplayBacklightBrightness",
  "description": "Get current display backlight brightness percentage [0, 100]. Return type: number.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetDisplayBacklightBrightness

`SetDisplayBacklightOnOff`

描述

Turn display backlight on or off.

执行要求

是否需要调度器: 需要

参数

On
- 类型: Boolean
- 是否必填: 必填
- 描述: True to turn on the backlight, false to turn it off.

Schema JSON

展开查看 JSON


{
  "name": "SetDisplayBacklightOnOff",
  "description": "Turn display backlight on or off.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "On",
      "description": "True to turn on the backlight, false to turn it off.",
      "type": "Boolean",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Device SetDisplayBacklightOnOff {"On":null}

`GetDisplayBacklightOnOff`

描述

Get whether display backlight is enabled. Return type: boolean.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetDisplayBacklightOnOff",
  "description": "Get whether display backlight is enabled. Return type: boolean.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetDisplayBacklightOnOff

`SetAudioPlayerVolume`

描述

Set target audio player volume percentage.

执行要求

是否需要调度器: 需要

参数

Volume
- 类型: Number
- 是否必填: 必填
- 描述: Player volume percentage in range [0, 100]. The actual volume will be mapped to the hardware range [BROOKESIA_SERVICE_DEVICE_AUDIO_PLAYER_VOLUME_MIN, BROOKESIA_SERVICE_DEVICE_AUDIO_PLAYER_VOLUME_MAX].

Schema JSON

展开查看 JSON


{
  "name": "SetAudioPlayerVolume",
  "description": "Set target audio player volume percentage.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Volume",
      "description": "Player volume percentage in range [0, 100]. The actual volume will be mapped to the hardware range [BROOKESIA_SERVICE_DEVICE_AUDIO_PLAYER_VOLUME_MIN, BROOKESIA_SERVICE_DEVICE_AUDIO_PLAYER_VOLUME_MAX].",
      "type": "Number",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Device SetAudioPlayerVolume {"Volume":null}

`GetAudioPlayerVolume`

描述

Get target audio player volume percentage. Return type: number.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetAudioPlayerVolume",
  "description": "Get target audio player volume percentage. Return type: number.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetAudioPlayerVolume

`SetAudioPlayerMute`

描述

Set whether audio player is muted.

执行要求

是否需要调度器: 需要

参数

Enable
- 类型: Boolean
- 是否必填: 必填
- 描述: True to mute audio player, false to unmute it.

Schema JSON

展开查看 JSON


{
  "name": "SetAudioPlayerMute",
  "description": "Set whether audio player is muted.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Enable",
      "description": "True to mute audio player, false to unmute it.",
      "type": "Boolean",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Device SetAudioPlayerMute {"Enable":null}

`GetAudioPlayerMute`

描述

Get whether audio player is muted. Return type: boolean.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetAudioPlayerMute",
  "description": "Get whether audio player is muted. Return type: boolean.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetAudioPlayerMute

`GetStorageFileSystems`

描述

Get mounted storage file systems. Return type: JSON array<object>. Example: [{"fs_type":"SPIFFS","medium_type":"Flash","mount_point":"/spiffs"},{"fs_type":"FATFS","medium_type":"SDCard","mount_point":"/sdcard"}]

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetStorageFileSystems",
  "description": "Get mounted storage file systems. Return type: JSON array<object>. Example: [{\"fs_type\":\"SPIFFS\",\"medium_type\":\"Flash\",\"mount_point\":\"/spiffs\"},{\"fs_type\":\"FATFS\",\"medium_type\":\"SDCard\",\"mount_point\":\"/sdcard\"}]",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetStorageFileSystems

`GetPowerBatteryInfo`

描述

Get static power battery information. Return type: JSON object. Example: {"name":"MainBattery","chemistry":"Li-ion","abilities":["Voltage","Percentage","ChargeState"]}

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Device GetPowerBatteryInfo

`GetPowerBatteryState`

描述

Get current power battery state. Return type: JSON 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. Return type: JSON 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}",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device GetPowerBatteryState

`GetPowerBatteryChargeConfig`

描述

Get current power battery charge configuration. Return type: JSON 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. Return type: JSON object. Example: {\"enabled\":true,\"target_voltage_mv\":4200,\"charge_current_ma\":500,\"precharge_current_ma\":100,\"termination_current_ma\":100}",
  "require_scheduler": true,
  "parameters": []
}

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,
  "parameters": [
    {
      "name": "Config",
      "description": "Battery charge configuration object.",
      "type": "Object",
      "required": true,
      "default_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,
  "parameters": [
    {
      "name": "Enabled",
      "description": "True to enable charging, false to disable charging.",
      "type": "Boolean",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Device SetPowerBatteryChargingEnabled {"Enabled":null}

`ResetData`

描述

Reset persisted device control state, including backlight brightness, player volume, and player mute.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResetData",
  "description": "Reset persisted device control state, including backlight brightness, player volume, and player mute.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Device ResetData

事件

`DisplayBacklightBrightnessChanged`

描述

Emitted when the target display backlight brightness changes.

执行要求

是否需要调度器: 需要

参数

Brightness
- 类型: Number
- 描述: Current target backlight brightness percentage [0, 100].

Schema JSON

展开查看 JSON


{
  "name": "DisplayBacklightBrightnessChanged",
  "description": "Emitted when the target display backlight brightness changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Brightness",
      "description": "Current target backlight brightness percentage [0, 100].",
      "type": "Number"
    }
  ]
}

CLI 命令

svc_subscribe Device DisplayBacklightBrightnessChanged

`DisplayBacklightOnOffChanged`

描述

Emitted when the target display backlight on/off state changes.

执行要求

是否需要调度器: 需要

参数

IsOn
- 类型: Boolean
- 描述: Whether display backlight is currently on. True if on, false if off.

Schema JSON

展开查看 JSON


{
  "name": "DisplayBacklightOnOffChanged",
  "description": "Emitted when the target display backlight on/off state changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsOn",
      "description": "Whether display backlight is currently on. True if on, false if off.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe Device DisplayBacklightOnOffChanged

`AudioPlayerVolumeChanged`

描述

Emitted when the target audio player volume changes.

执行要求

是否需要调度器: 需要

参数

Volume
- 类型: Number
- 描述: Current target player volume percentage [0, 100].

Schema JSON

展开查看 JSON


{
  "name": "AudioPlayerVolumeChanged",
  "description": "Emitted when the target audio player volume changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Volume",
      "description": "Current target player volume percentage [0, 100].",
      "type": "Number"
    }
  ]
}

CLI 命令

svc_subscribe Device AudioPlayerVolumeChanged

`AudioPlayerMuteChanged`

描述

Emitted when the target audio player mute state changes.

执行要求

是否需要调度器: 需要

参数

IsMuted
- 类型: Boolean
- 描述: Whether audio player is currently muted. True if muted, false if unmuted.

Schema JSON

展开查看 JSON


{
  "name": "AudioPlayerMuteChanged",
  "description": "Emitted when the target audio player mute state changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsMuted",
      "description": "Whether audio player is currently muted. True if muted, false if unmuted.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe Device AudioPlayerMuteChanged

`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 命令

SetDisplayBacklightBrightness

描述

执行要求

参数

Schema JSON

CLI 命令

GetDisplayBacklightBrightness

描述

执行要求

参数

Schema JSON

CLI 命令

SetDisplayBacklightOnOff

描述

执行要求

参数

Schema JSON

CLI 命令

GetDisplayBacklightOnOff

描述

执行要求

参数

Schema JSON

CLI 命令

SetAudioPlayerVolume

描述

执行要求

参数

Schema JSON

CLI 命令

GetAudioPlayerVolume

描述

执行要求

参数

Schema JSON

CLI 命令

SetAudioPlayerMute

描述

执行要求

参数

Schema JSON

CLI 命令

GetAudioPlayerMute

描述

执行要求

参数

Schema JSON

CLI 命令

GetStorageFileSystems

描述

执行要求

参数

Schema JSON

CLI 命令

GetPowerBatteryInfo

描述

执行要求

`GetCapabilities`

`GetBoardInfo`

`SetDisplayBacklightBrightness`

`GetDisplayBacklightBrightness`

`SetDisplayBacklightOnOff`

`GetDisplayBacklightOnOff`

`SetAudioPlayerVolume`

`GetAudioPlayerVolume`

`SetAudioPlayerMute`

`GetAudioPlayerMute`

`GetStorageFileSystems`

`GetPowerBatteryInfo`

`GetPowerBatteryState`

`GetPowerBatteryChargeConfig`

`SetPowerBatteryChargeConfig`

`SetPowerBatteryChargingEnabled`

`ResetData`

`DisplayBacklightBrightnessChanged`

`DisplayBacklightOnOffChanged`

`AudioPlayerVolumeChanged`

`AudioPlayerMuteChanged`

`PowerBatteryStateChanged`

`PowerBatteryChargeConfigChanged`