Display Service
Helper header:
#include "brookesia/service_helper/media/display.hpp"Helper class:
esp_brookesia::service::helper::Display
Overview
brookesia_service_display owns display outputs, sources, active-source arbitration, frame presentation, touch gestures, and backlight control.
Core Responsibilities
Registers display sources and routes frames to active physical outputs.
Provides service functions for output/source discovery and active-source selection.
Exposes touch gesture events and output-bound backlight operations.
Integration Position
This component is an independent ESP-Brookesia release component. It can be integrated through ESP-IDF component dependencies and combined with peer framework components as needed.
Standard Include / Helper Class
Standard include:
#include \"brookesia/service_helper/media/display.hpp\"Helper class:
esp_brookesia::service::helper::Display
Service Interfaces
Functions
GetOutputs
Description
Get display outputs.
Execution
Requires scheduler: Not required
Parameters
No parameters.
Return Value
Type:
ArrayDescription: Example: [{"id":1,"name":"Output0","width":240,"height":240,"pixel_format":"RGB565","slot":"HalPanel","panel_instance":"Display:Panel0","group_id":"main_display","touch":{"id":1,"name":"Touch0","instance":"Display:Touch0","max_points":5,"operation_mode":"Interrupt"},"backlight":{"instance":"Display:Backlight0","on_off_supported":true}}]
Schema JSON
Show raw JSON
{
"name": "GetOutputs",
"description": "Get display outputs.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":1,\"name\":\"Output0\",\"width\":240,\"height\":240,\"pixel_format\":\"RGB565\",\"slot\":\"HalPanel\",\"panel_instance\":\"Display:Panel0\",\"group_id\":\"main_display\",\"touch\":{\"id\":1,\"name\":\"Touch0\",\"instance\":\"Display:Touch0\",\"max_points\":5,\"operation_mode\":\"Interrupt\"},\"backlight\":{\"instance\":\"Display:Backlight0\",\"on_off_supported\":true}}]"
}
}
CLI Command
svc_call Display GetOutputs
GetSources
Description
Get registered display sources.
Execution
Requires scheduler: Not required
Parameters
No parameters.
Return Value
Type:
ArrayDescription: Example: [{"id":1,"name":"LVGL","role":"gui","preferred_outputs":["Output0"],"priority":0}]
Schema JSON
Show raw JSON
{
"name": "GetSources",
"description": "Get registered display sources.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":1,\"name\":\"LVGL\",\"role\":\"gui\",\"preferred_outputs\":[\"Output0\"],\"priority\":0}]"
}
}
CLI Command
svc_call Display GetSources
RegisterSource
Description
Register a display source. Example source: {"id":0,"name":"LVGL","role":"gui","preferred_outputs":["Output0"],"priority":0}
Execution
Requires scheduler: Not required
Parameters
SourceType:
ObjectRequired: required
Description: Display source info object. The id field is assigned by Display service.
Return Value
Type:
NumberDescription: Registered display source id.
Schema JSON
Show raw JSON
{
"name": "RegisterSource",
"description": "Register a display source. Example source: {\"id\":0,\"name\":\"LVGL\",\"role\":\"gui\",\"preferred_outputs\":[\"Output0\"],\"priority\":0}",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "Source",
"description": "Display source info object. The id field is assigned by Display service.",
"type": "Object",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Number",
"description": "Registered display source id."
}
}
CLI Command
svc_call Display RegisterSource {"Source":null}
UnregisterSource
Description
Unregister a named display source.
Execution
Requires scheduler: Not required
Parameters
SourceNameType:
StringRequired: required
Description: Display source name.
Schema JSON
Show raw JSON
{
"name": "UnregisterSource",
"description": "Unregister a named display source.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Display source name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI Command
svc_call Display UnregisterSource {"SourceName":null}
RequestOutput
Description
Request permission for a source to draw to one output.
Execution
Requires scheduler: Not required
Parameters
SourceNameType:
StringRequired: required
Description: Registered source name.
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name. Empty string uses the first output.
Schema JSON
Show raw JSON
{
"name": "RequestOutput",
"description": "Request permission for a source to draw to one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Registered source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Display output name. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": null
}
CLI Command
svc_call Display RequestOutput {"SourceName":null,"OutputName":null}
ReleaseOutput
Description
Release a source's request for one output.
Execution
Requires scheduler: Not required
Parameters
SourceNameType:
StringRequired: required
Description: Registered source name.
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name. Empty string uses the first output.
Schema JSON
Show raw JSON
{
"name": "ReleaseOutput",
"description": "Release a source's request for one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Registered source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Display output name. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": null
}
CLI Command
svc_call Display ReleaseOutput {"SourceName":null,"OutputName":null}
SetActiveSource
Description
Grant one display output to a named source. Empty source name clears the active source.
Execution
Requires scheduler: Required
Parameters
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name, for example Output0. Empty string uses the first output.
SourceNameType:
StringRequired: required
Description: Registered source name, or empty string to clear.
Schema JSON
Show raw JSON
{
"name": "SetActiveSource",
"description": "Grant one display output to a named source. Empty source name clears the active source.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
},
{
"name": "SourceName",
"description": "Registered source name, or empty string to clear.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI Command
svc_call Display SetActiveSource {"OutputName":null,"SourceName":null}
GetActiveSource
Description
Get the active source name for one display output. Returns empty string when no source is active.
Execution
Requires scheduler: Required
Parameters
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name, for example Output0. Empty string uses the first output.
Return Value
Type:
StringDescription: Active source name, or an empty string when no source is active.
Schema JSON
Show raw JSON
{
"name": "GetActiveSource",
"description": "Get the active source name for one display output. Returns empty string when no source is active.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": {
"type": "String",
"description": "Active source name, or an empty string when no source is active."
}
}
CLI Command
svc_call Display GetActiveSource {"OutputName":null}
SetActiveSourceRole
Description
Grant one display output to the first registered source with the specified role.
Execution
Requires scheduler: Required
Parameters
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name, for example Output0. Empty string uses the first output.
RoleType:
StringRequired: required
Description: Registered source role.
Schema JSON
Show raw JSON
{
"name": "SetActiveSourceRole",
"description": "Grant one display output to the first registered source with the specified role.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
},
{
"name": "Role",
"description": "Registered source role.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI Command
svc_call Display SetActiveSourceRole {"OutputName":null,"Role":null}
GetActiveRole
Description
Get the active source role for one display output. Returns empty string when no source is active.
Execution
Requires scheduler: Required
Parameters
OutputNameType:
StringRequired: optional
Default:
""Description: Display output name, for example Output0. Empty string uses the first output.
Return Value
Type:
StringDescription: Active source role, or an empty string when no source is active.
Schema JSON
Show raw JSON
{
"name": "GetActiveRole",
"description": "Get the active source role for one display output. Returns empty string when no source is active.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": {
"type": "String",
"description": "Active source role, or an empty string when no source is active."
}
}
CLI Command
svc_call Display GetActiveRole {"OutputName":null}
GetSourceRoles
Description
Get registered display source roles, de-duplicated in first-registration order.
Execution
Requires scheduler: Not required
Parameters
No parameters.
Return Value
Type:
ArrayDescription: Example: ["gui","video"]
Schema JSON
Show raw JSON
{
"name": "GetSourceRoles",
"description": "Get registered display source roles, de-duplicated in first-registration order.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [\"gui\",\"video\"]"
}
}
CLI Command
svc_call Display GetSourceRoles
SetTouchGestureConfig
Description
Configure touch gesture detection for one output. Example config: {"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}
Execution
Requires scheduler: Not required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
ConfigType:
ObjectRequired: optional
Default:
{"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}Description: Gesture configuration object. Zero threshold fields use output defaults.
Schema JSON
Show raw JSON
{
"name": "SetTouchGestureConfig",
"description": "Configure touch gesture detection for one output. Example config: {\"enabled\":false,\"detect_period_ms\":20,\"direction_lock_enabled\":true,\"release_debounce_ms\":40,\"threshold\":{\"direction_vertical\":0,\"direction_horizon\":0,\"direction_angle\":45,\"horizontal_edge\":0,\"vertical_edge\":0,\"duration_short_ms\":220,\"speed_slow_px_per_ms\":6.000000238418579E-1}}",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "Config",
"description": "Gesture configuration object. Zero threshold fields use output defaults.",
"type": "Object",
"required": false,
"default_value": {
"enabled": false,
"detect_period_ms": 20,
"direction_lock_enabled": true,
"release_debounce_ms": 40,
"threshold": {
"direction_vertical": 0,
"direction_horizon": 0,
"direction_angle": 45,
"horizontal_edge": 0,
"vertical_edge": 0,
"duration_short_ms": 220,
"speed_slow_px_per_ms": 0.6000000238418579
}
}
}
],
"return_value": null
}
CLI Command
svc_call Display SetTouchGestureConfig {"OutputId":null,"Config":null}
GetTouchGestureConfig
Description
Get touch gesture config for one output.
Execution
Requires scheduler: Not required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
Return Value
Type:
ObjectDescription: Example: {"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}
Schema JSON
Show raw JSON
{
"name": "GetTouchGestureConfig",
"description": "Get touch gesture config for one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Object",
"description": "Example: {\"enabled\":false,\"detect_period_ms\":20,\"direction_lock_enabled\":true,\"release_debounce_ms\":40,\"threshold\":{\"direction_vertical\":0,\"direction_horizon\":0,\"direction_angle\":45,\"horizontal_edge\":0,\"vertical_edge\":0,\"duration_short_ms\":220,\"speed_slow_px_per_ms\":6.000000238418579E-1}}"
}
}
CLI Command
svc_call Display GetTouchGestureConfig {"OutputId":null}
SetBacklightBrightness
Description
Set backlight brightness percentage for one display output.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
BrightnessType:
NumberRequired: required
Description: Backlight brightness percentage in range [0, 100].
Schema JSON
Show raw JSON
{
"name": "SetBacklightBrightness",
"description": "Set backlight brightness percentage for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "Brightness",
"description": "Backlight brightness percentage in range [0, 100].",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI Command
svc_call Display SetBacklightBrightness {"OutputId":null,"Brightness":null}
GetBacklightBrightness
Description
Get backlight brightness percentage for one display output.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
Return Value
Type:
NumberDescription: Backlight brightness percentage in range [0, 100].
Schema JSON
Show raw JSON
{
"name": "GetBacklightBrightness",
"description": "Get backlight brightness percentage for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Number",
"description": "Backlight brightness percentage in range [0, 100]."
}
}
CLI Command
svc_call Display GetBacklightBrightness {"OutputId":null}
SetBacklightOnOff
Description
Turn the backlight on or off for one display output.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
OnType:
BooleanRequired: required
Description: True to turn on the backlight, false to turn it off.
Schema JSON
Show raw JSON
{
"name": "SetBacklightOnOff",
"description": "Turn the backlight on or off for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "On",
"description": "True to turn on the backlight, false to turn it off.",
"type": "Boolean",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI Command
svc_call Display SetBacklightOnOff {"OutputId":null,"On":null}
GetBacklightOnOff
Description
Get whether the backlight is enabled for one display output.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: required
Description: Runtime Display output id from GetOutputs().
Return Value
Type:
BooleanDescription: True when backlight is enabled, false otherwise.
Schema JSON
Show raw JSON
{
"name": "GetBacklightOnOff",
"description": "Get whether the backlight is enabled for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Boolean",
"description": "True when backlight is enabled, false otherwise."
}
}
CLI Command
svc_call Display GetBacklightOnOff {"OutputId":null}
LoadData
Description
Load persisted Display state. OutputId 0 loads all backlight-bound outputs.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: optional
Default:
0E0Description: Runtime Display output id from GetOutputs(), or 0 for all outputs.
Schema JSON
Show raw JSON
{
"name": "LoadData",
"description": "Load persisted Display state. OutputId 0 loads all backlight-bound outputs.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs(), or 0 for all outputs.",
"type": "Number",
"required": false,
"default_value": 0.0
}
],
"return_value": null
}
CLI Command
svc_call Display LoadData {"OutputId":null}
ResetData
Description
Reset persisted Display state. OutputId 0 resets all backlight-bound outputs.
Execution
Requires scheduler: Required
Parameters
OutputIdType:
NumberRequired: optional
Default:
0E0Description: Runtime Display output id from GetOutputs(), or 0 for all outputs.
Schema JSON
Show raw JSON
{
"name": "ResetData",
"description": "Reset persisted Display state. OutputId 0 resets all backlight-bound outputs.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs(), or 0 for all outputs.",
"type": "Number",
"required": false,
"default_value": 0.0
}
],
"return_value": null
}
CLI Command
svc_call Display ResetData {"OutputId":null}
Events
SourceStateChanged
Description
A display source state changed relative to an output.
Execution
Requires scheduler: Not required
Items
SourceNameType:
StringDescription: Source name.
OutputNameType:
StringDescription: Output name, or empty string for source-global changes.
StateType:
StringDescription: New source state.
Schema JSON
Show raw JSON
{
"name": "SourceStateChanged",
"description": "A display source state changed relative to an output.",
"require_scheduler": false,
"items": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String"
},
{
"name": "OutputName",
"description": "Output name, or empty string for source-global changes.",
"type": "String"
},
{
"name": "State",
"description": "New source state.",
"type": "String"
}
]
}
CLI Command
svc_subscribe Display SourceStateChanged
ActiveSourceChanged
Description
The active source for an output changed.
Execution
Requires scheduler: Not required
Items
OutputNameType:
StringDescription: Output name.
SourceNameType:
StringDescription: Active source name, or empty string when cleared.
Schema JSON
Show raw JSON
{
"name": "ActiveSourceChanged",
"description": "The active source for an output changed.",
"require_scheduler": false,
"items": [
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "SourceName",
"description": "Active source name, or empty string when cleared.",
"type": "String"
}
]
}
CLI Command
svc_subscribe Display ActiveSourceChanged
OutputRegistered
Description
A dynamic display output was registered.
Execution
Requires scheduler: Not required
Items
InfoType:
ObjectDescription: Registered output info.
Schema JSON
Show raw JSON
{
"name": "OutputRegistered",
"description": "A dynamic display output was registered.",
"require_scheduler": false,
"items": [
{
"name": "Info",
"description": "Registered output info.",
"type": "Object"
}
]
}
CLI Command
svc_subscribe Display OutputRegistered
OutputUnregistered
Description
A dynamic display output was unregistered.
Execution
Requires scheduler: Not required
Items
OutputNameType:
StringDescription: Display output name.
Schema JSON
Show raw JSON
{
"name": "OutputUnregistered",
"description": "A dynamic display output was unregistered.",
"require_scheduler": false,
"items": [
{
"name": "OutputName",
"description": "Display output name.",
"type": "String"
}
]
}
CLI Command
svc_subscribe Display OutputUnregistered
TouchGesture
Description
A display output touch gesture changed state.
Execution
Requires scheduler: Not required
Items
InfoType:
ObjectDescription: Gesture event payload.
Schema JSON
Show raw JSON
{
"name": "TouchGesture",
"description": "A display output touch gesture changed state.",
"require_scheduler": false,
"items": [
{
"name": "Info",
"description": "Gesture event payload.",
"type": "Object"
}
]
}
CLI Command
svc_subscribe Display TouchGesture
BacklightBrightnessChanged
Description
The backlight brightness for an output changed.
Execution
Requires scheduler: Required
Items
OutputIdType:
NumberDescription: Runtime Display output id.
OutputNameType:
StringDescription: Output name.
BrightnessType:
NumberDescription: Current target backlight brightness percentage [0, 100].
Schema JSON
Show raw JSON
{
"name": "BacklightBrightnessChanged",
"description": "The backlight brightness for an output changed.",
"require_scheduler": true,
"items": [
{
"name": "OutputId",
"description": "Runtime Display output id.",
"type": "Number"
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "Brightness",
"description": "Current target backlight brightness percentage [0, 100].",
"type": "Number"
}
]
}
CLI Command
svc_subscribe Display BacklightBrightnessChanged
BacklightOnOffChanged
Description
The backlight on/off state for an output changed.
Execution
Requires scheduler: Required
Items
OutputIdType:
NumberDescription: Runtime Display output id.
OutputNameType:
StringDescription: Output name.
IsOnType:
BooleanDescription: Whether display backlight is currently on. True if on, false if off.
Schema JSON
Show raw JSON
{
"name": "BacklightOnOffChanged",
"description": "The backlight on/off state for an output changed.",
"require_scheduler": true,
"items": [
{
"name": "OutputId",
"description": "Runtime Display output id.",
"type": "Number"
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "IsOn",
"description": "Whether display backlight is currently on. True if on, false if off.",
"type": "Boolean"
}
]
}
CLI Command
svc_subscribe Display BacklightOnOffChanged