Device Control

[中文]

  • Component registry: espressif/brookesia_service_device

  • Helper header: #include "brookesia/service_helper/device.hpp"

  • Helper class: esp_brookesia::service::helper::Device

Overview

brookesia_service_device is an application-facing device control service. It is not a new hardware driver. Instead, it provides a unified service interface for application code to access HAL capabilities. When the service starts, it discovers initialized HAL interfaces and exposes common control and status-query operations as Service functions and events.

Typical usage:

  • Application code calls functions or subscribes to events through service::helper::Device.

  • HAL adaptor and board components provide low-level interfaces such as AudioCodecPlayerIface, DisplayBacklightIface, StorageFsIface, and PowerBatteryIface.

  • brookesia_service_device sits in between to validate parameters, cache state, publish events, and persist selected application-level state.

Therefore, applications usually do not need to hold HAL interface pointers directly unless they need low-level or board-specific behavior.

Features

Capability Discovery

The service provides GetCapabilities to return a snapshot of registered HAL interfaces. Applications can query capabilities first, then decide whether to show related UI or invoke related control functions.

Common capabilities:

HAL Interface

Typical Usage

BoardInfoIface

Get static board name, chip, version, vendor, and description.

DisplayBacklightIface

Set/query backlight brightness and on/off state.

AudioCodecPlayerIface

Set/query player volume and mute state.

StorageFsIface

Get mounted file-system information.

PowerBatteryIface

Get battery information, state, and charge configuration; control charging when supported.

Control Functions

Control functions update device state and are intended for UI, Agent tool calls, or remote-control workflows:

  • Display control: set backlight brightness percentage and backlight on/off state.

  • Audio control: set player volume percentage and mute state.

  • Power control: set battery charge configuration or enable/disable charging when supported by HAL.

  • Data reset: clear persisted volume, mute, and brightness state, then restore defaults.

Brightness and volume use application-level percentages in [0, 100]. The service maps them to the hardware min/max ranges configured through Kconfig before calling HAL.

Status Query Functions

Status-query functions read static information or runtime state:

  • Capabilities and board information: get the current HAL capability snapshot and static board information.

  • Display state: get current backlight brightness percentage and on/off state.

  • Audio state: get target player volume percentage and mute state.

  • Storage state: get mounted file systems and mount points.

  • Battery state: get battery capabilities, voltage, percentage, charge state, low/critical flags, and charge configuration when supported.

Events

The service publishes events when cached state changes. Applications can subscribe through service::helper::Device::subscribe_event:

  • DisplayBacklightBrightnessChanged

  • DisplayBacklightOnOffChanged

  • AudioPlayerVolumeChanged

  • AudioPlayerMuteChanged

  • PowerBatteryStateChanged

  • PowerBatteryChargeConfigChanged

Battery state is polled from HAL at the configured interval, and an event is published when the snapshot changes.

Persisted State

When brookesia_service_nvs is enabled and running, Device service attempts to save and restore the following application-level state:

  • Player volume

  • Player mute

  • Backlight brightness

If the NVS service is unavailable, Device service still works, but these values are not persisted across reboot.

Usage Recommendations

  • Initialize required HAL devices before starting ServiceManager and the Device service.

  • Query GetCapabilities before invoking optional control functions.

  • For UI and Agent tool calls, prefer Device service as the application-layer entry point to HAL instead of depending on board-specific HAL implementations directly.

  • For high-throughput data paths such as audio streams or display frame drawing, use dedicated services or HAL interfaces instead of routing bulk data through Device service.

Standard Include / Helper Class

  • Standard include: #include \"brookesia/service_helper/device.hpp\"

  • Helper class: esp_brookesia::service::helper::Device

Service Interfaces

Functions

GetCapabilities

Description

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

Execution

  • Requires scheduler: Not required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetCapabilities

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

Execution

  • Requires scheduler: Not required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetBoardInfo

SetDisplayBacklightBrightness

Description

Set display backlight brightness percentage.

Execution

  • Requires scheduler: Required

Parameters

  • Brightness

    • Type: Number

    • Required: required

    • 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].

Schema JSON
Show raw 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 Command
svc_call Device SetDisplayBacklightBrightness {"Brightness":null}

GetDisplayBacklightBrightness

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

SetDisplayBacklightOnOff

Description

Turn display backlight on or off.

Execution

  • Requires scheduler: Required

Parameters

  • On

    • Type: Boolean

    • Required: required

    • Description: True to turn on the backlight, false to turn it off.

Schema JSON
Show raw 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 Command
svc_call Device SetDisplayBacklightOnOff {"On":null}

GetDisplayBacklightOnOff

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

SetAudioPlayerVolume

Description

Set target audio player volume percentage.

Execution

  • Requires scheduler: Required

Parameters

  • Volume

    • Type: Number

    • Required: required

    • 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].

Schema JSON
Show raw 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 Command
svc_call Device SetAudioPlayerVolume {"Volume":null}

GetAudioPlayerVolume

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

SetAudioPlayerMute

Description

Set whether audio player is muted.

Execution

  • Requires scheduler: Required

Parameters

  • Enable

    • Type: Boolean

    • Required: required

    • Description: True to mute audio player, false to unmute it.

Schema JSON
Show raw 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 Command
svc_call Device SetAudioPlayerMute {"Enable":null}

GetAudioPlayerMute

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetStorageFileSystems

GetPowerBatteryInfo

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetPowerBatteryInfo

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}

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetPowerBatteryState

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}

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw 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 Command
svc_call Device GetPowerBatteryChargeConfig

SetPowerBatteryChargeConfig

Description

Set power battery charge configuration.

Execution

  • Requires scheduler: Required

Parameters

  • Config

    • Type: Object

    • Required: required

    • Description: Battery charge configuration object.

Schema JSON
Show raw 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 Command
svc_call Device SetPowerBatteryChargeConfig {"Config":null}

SetPowerBatteryChargingEnabled

Description

Enable or disable battery charging.

Execution

  • Requires scheduler: Required

Parameters

  • Enabled

    • Type: Boolean

    • Required: required

    • Description: True to enable charging, false to disable charging.

Schema JSON
Show raw 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 Command
svc_call Device SetPowerBatteryChargingEnabled {"Enabled":null}

ResetData

Description

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

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

Events

DisplayBacklightBrightnessChanged

Description

Emitted when the target display backlight brightness changes.

Execution

  • Requires scheduler: Required

Items

  • Brightness

    • Type: Number

    • Description: Current target backlight brightness percentage [0, 100].

Schema JSON
Show raw 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 Command
svc_subscribe Device DisplayBacklightBrightnessChanged

DisplayBacklightOnOffChanged

Description

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

Execution

  • Requires scheduler: Required

Items

  • IsOn

    • Type: Boolean

    • Description: Whether display backlight is currently on. True if on, false if off.

Schema JSON
Show raw 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 Command
svc_subscribe Device DisplayBacklightOnOffChanged

AudioPlayerVolumeChanged

Description

Emitted when the target audio player volume changes.

Execution

  • Requires scheduler: Required

Items

  • Volume

    • Type: Number

    • Description: Current target player volume percentage [0, 100].

Schema JSON
Show raw 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 Command
svc_subscribe Device AudioPlayerVolumeChanged

AudioPlayerMuteChanged

Description

Emitted when the target audio player mute state changes.

Execution

  • Requires scheduler: Required

Items

  • IsMuted

    • Type: Boolean

    • Description: Whether audio player is currently muted. True if muted, false if unmuted.

Schema JSON
Show raw 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 Command
svc_subscribe Device AudioPlayerMuteChanged

PowerBatteryStateChanged

Description

Emitted when the power battery state snapshot changes.

Execution

  • Requires scheduler: Required

Items

  • State

    • Type: Object

    • Description: Current power battery state snapshot.

Schema JSON
Show raw 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 Command
svc_subscribe Device PowerBatteryStateChanged

PowerBatteryChargeConfigChanged

Description

Emitted when the power battery charge configuration changes.

Execution

  • Requires scheduler: Required

Items

  • Config

    • Type: Object

    • Description: Current power battery charge configuration.

Schema JSON
Show raw 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 Command
svc_subscribe Device PowerBatteryChargeConfigChanged