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, 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.
`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.
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

Battery state is polled from HAL at the configured interval, and an event is published when the snapshot 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.
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}

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

Device Control

Overview

Features

Capability Discovery

Control Functions

Status Query Functions

Events

Persisted State

Usage Recommendations

Standard Include / Helper Class

Service Interfaces

Functions

GetCapabilities

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetBoardInfo

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetCameraDeviceInfos

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetNetworkConnectivityInfo

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetPowerBatteryInfo

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetPowerBatteryState

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

GetPowerBatteryChargeConfig

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

SetPowerBatteryChargeConfig

Description

Execution

Parameters

Schema JSON

CLI Command

SetPowerBatteryChargingEnabled

Description

Execution

Parameters

Schema JSON

CLI Command

Events

PowerBatteryStateChanged

Description

Execution

Items

Schema JSON

CLI Command

`GetCapabilities`

`GetBoardInfo`

`GetCameraDeviceInfos`

`GetNetworkConnectivityInfo`

`GetPowerBatteryInfo`

`GetPowerBatteryState`

`GetPowerBatteryChargeConfig`

`SetPowerBatteryChargeConfig`

`SetPowerBatteryChargingEnabled`

`PowerBatteryStateChanged`

`PowerBatteryChargeConfigChanged`