Device Control

[中文]

  • Component registry: espressif/brookesia_service_device

  • Helper header: #include "brookesia/service_helper/system/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, PowerBatteryIface, expansion::ModuleManagerIface, and ProtocolSntpIface.

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

expansion::ModuleManagerIface

Get stable expansion-slot and module identity, availability, and active state.

ProtocolSntpIface

Configure NTP servers and timezone, start or stop SNTP, and query time-sync state.

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.

  • SNTP control: set NTP servers and timezone, start or stop time synchronization, and query time-sync state.

  • Data reset: clear persisted volume, mute, brightness, and SNTP 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.

  • Expansion-module state: call GetExpansionModuleInfos to get stable snapshots for all provider slots.

  • SNTP state: get configured NTP servers, timezone, and whether system time has synchronized.

Events

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

  • DisplayBacklightBrightnessChanged

  • DisplayBacklightOnOffChanged

  • AudioPlayerVolumeChanged

  • AudioPlayerMuteChanged

  • PowerBatteryStateChanged

  • PowerBatteryChargeConfigChanged

  • ExpansionModuleChanged

Battery state is polled from HAL at the configured interval, and an event is published when the snapshot changes. ExpansionModuleChanged carries the complete stable snapshot received from HAL after module insertion, removal, support, or active-state changes.

Persisted State

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

  • Player volume

  • Player mute

  • Backlight brightness

  • SNTP timezone

  • SNTP NTP server list

If the Storage 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.

  • Use GetExpansionModuleInfos for the initial slot state, then subscribe to ExpansionModuleChanged instead of repeatedly polling from application code.

  • Enable the HAL General SNTP implementation when time synchronization is required.

  • Call StartSntp explicitly after networking has been configured; Device service prepares SNTP but does not auto-start synchronization.

  • 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/system/device.hpp\"

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

Service Interfaces

Functions

GetCapabilities

Description

Get available HAL devices and interfaces.

Execution

  • Requires scheduler: Required

Parameters

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

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

GetBoardInfo

Description

Get static board information.

Execution

  • Requires scheduler: Required

Parameters

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

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

GetCameraDeviceInfos

Description

Get available camera devices.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: Array

  • Description: Example: [{"id":0,"name":"camera","device_path":"/dev/video0","supported_formats":["YUV422"]}]

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

GetNetworkConnectivityInfo

Description

Get current network connectivity status.

Execution

  • Requires scheduler: Required

Parameters

  • No 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}]

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

GetPowerBatteryInfo

Description

Get static power battery information.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: Object

  • Description: Example: {"name":"MainBattery","chemistry":"Li-ion","abilities":["Voltage","Percentage","ChargeState"]}

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

GetPowerBatteryState

Description

Get current power battery state.

Execution

  • Requires scheduler: Required

Parameters

  • No 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}

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

GetPowerBatteryChargeConfig

Description

Get current power battery charge configuration.

Execution

  • Requires scheduler: Required

Parameters

  • No 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}

Schema JSON
Show raw 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 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,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Config",
      "description": "Battery charge configuration object.",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ],
  "return_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,
  "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 Command
svc_call Device SetPowerBatteryChargingEnabled {"Enabled":null}

GetExpansionModuleInfos

Description

Get stable expansion module states for all slots.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: Array

  • Description: Example: [{"provider":"mosaico","slot":"left","type":"camera","board_id":7,"board_name":"OV3640 Camera","generation":1,"state":"Ready"}]

Schema JSON
Show raw JSON 

{
  "name": "GetExpansionModuleInfos",
  "description": "Get stable expansion module states for all slots.",
  "require_scheduler": true,
  "default_timeout_ms": 2000,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"provider\":\"mosaico\",\"slot\":\"left\",\"type\":\"camera\",\"board_id\":7,\"board_name\":\"OV3640 Camera\",\"generation\":1,\"state\":\"Ready\"}]"
  }
}
CLI Command
svc_call Device GetExpansionModuleInfos

Events

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

ExpansionModuleChanged

Description

Emitted when a stable expansion module state changes.

Execution

  • Requires scheduler: Required

Items

  • Module

    • Type: Object

    • Description: Current stable expansion module snapshot.

Schema JSON
Show raw JSON 

{
  "name": "ExpansionModuleChanged",
  "description": "Emitted when a stable expansion module state changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Module",
      "description": "Current stable expansion module snapshot.",
      "type": "Object"
    }
  ]
}
CLI Command
svc_subscribe Device ExpansionModuleChanged