Version: 2.0 | Last Updated: 2024-12-04
- Introduction
- About the Specification
- Requirements
- Protocol Basics
- DAB Operations
5.1. Supported operations
5.2. Applications
5.3. System
5.4. Input
5.5. Output
5.6. Device and Application Telemetry
5.7. Health Check
5.8. General Notifications
5.9. Voice - Versioning of the protocol
- Appendix
- Deprecated APIs
This document describes Device Automation Bus (DAB), a simple protocol for intuitively interacting with living room devices. Living room devices are consumer electronics in the living room that are connected to the Internet such as televisions and games consoles. DAB is a protocol that allows device manufacturers and application developers to programmatically communicate with living room devices to start and stop applications, send key presses to the device, restart the device, capture device metrics among other operations. Using DAB, device manufacturers and application developers can automate manual tasks such as application compatibility checks, cross application performance testing and monitoring device memory usage. Automating manual tasks provides reliable results and saves time and money.
The diagram below provides a high level view of how DAB works:
This specification describes a message based protocol to support programmatically communicating with a device under test. This specification provides a description of the supported messages and their payloads as well as positive and negative response codes.
The DAB protocol is built on top of MQTT 5. MQTT is a publish-subscribe messaging transport protocol for connecting to remote devices. For more details, see https://mqtt.org/
The following topics are not covered in this specification:
Recommendations for securing DAB, as well as connecting to a device under test that supports DAB will be defined in a separate document.
Protocol Compliance testing will be defined in a separate DAB certification guide.
An endpoint is DAB compliant only if the following conditions are met:
- HTTP/1.1 or above is supported for media operations
- 2 megabytes are dedicated to DAB for media operations
This section describes message payloads, request and response formats, message types and common status codes.
DAB relies on the MQTT request/response model which is native to all MQTT 5 compliant brokers and clients.
To send requests and receive responses from DAB:
- The responding client (device side) is running and subscribed to all topics corresponding to the supported DAB operations.
- The requesting client (user side) determines to which topic responses should be sent and subscribes to this
responseTopic
. Response topics may be reused ifcorrelationData
is included, otherwise they must be unique. - The requesting client generates a unique binary request ID, referred to as
correlationData
, to aid in associating responses with requests. Use of correlation data is not required, but strongly encouraged. - The requesting client publishes the message to the request topic with the required
responseTopic
and optionalcorrelationData
message properties. - When the request is received by the responding client, an operation is performed, response message is formed,
correlationData
is copied from the request message property to the response (if it exists), and the message is published to theresponseTopic
property from the request. - The operation is complete when the requesting client receives a message on the
responseTopic
with matchingcorrelationData
(if applicable), or the client chooses to time out the request.
- The user client wants to send a message to the request topic
dab/<device-id>/health-check/get
and get responses atdab/userClient-1/responses
. Note: TheresponseTopic
doesn't have to be similar todab/userClient-1/responses
, it can be anything that the user client specifies. Device client uses theresponseTopic
field to send back the response. - A unique binary
correlationData
value is generated. - The user client subscribes to
dab/userClient-1/responses
and waits for a response message with the matchingcorrelationData
value to arrive. - The user client publishes a message to
dab/<device-id>/health-check/get
with request propertiescorrelationData
andresponseTopic: dab/userClient-1/responses
. - When a message sent by device client is received on the user client at
dab/userClient-1/responses
with matchingcorrelationData
, the message payload will be the health-check response and the operation is complete.
topic: "dab/<device-id>/health-check/get",
correlationData: "abc",
responseTopic: "dab/userClient-1/responses",
payload: DabRequest{...}
topic: "dab/userClient-1/responses",
correlationData: "abc",
payload: DabResponse{...}
The Device ID is an unique identifier that helps with DAB message routing across multiple device clients.
One should implement the Device ID as:
- The device under test defines what its Device ID should be. 2.1. It may or may not be baked into the device, but it should be globally unique. 2.2. It may be configurable, but using transient values, such as current IP address, is not recommended as this can make reconnecting after restart difficult.
- Device ID must be a string, and only include lower case alphanumeric characters and -_.
When a device client first connected to the MQTT broker, it should do the following setup procedure:
- Subscribe to all topics listed in this spec, like
dab/<device-id>/device/info
topic. - Subscribe to
dab/discovery
topic.
These are the steps using which a user client can discover all the DAB device clients present in the current setup:
- When a User client connects to the MQTT broker for the first time, there might be device clients already connected to the broker. User Client should publish a request to the discovery topic
dab/discovery
similar to the following:
topic: "dab/discovery",
correlationData: "abc",
responseTopic: "dab/userClient-1/responses",
payload: DabRequest{...}
- All connected DAB devices will send a response back to the
responseTopic
as set by the user client. The user client can then extract the device-id from these responses.
DAB protocol message payloads are always JSON and the characters must use UTF-8 encoding.
This specification uses typescript interfaces to define request and response schemas. Typescript interfaces are used in order to be descriptive, compact and concise with the request and response schema definitions.
As an example, the following JSON maps to the example Typescript interface (and vice versa):
{
"variableName": "Value",
}
maps to:
interface ExampleResponse {
variableName: string;
optionallyIncludedVariable?: string;
}
For more information on TypeScript, please see the TypeScript documentation.
All DAB requests must be valid JSON objects even if no parameters are required. All DAB requests must inherit from the DabRequest
format
interface DabRequest {
}
Sample Response An empty request is equal to an empty JSON map
{}
All DAB responses must inherit from the DabResponse
format. DAB responses must contain the status
field and may contain the error
field when an error occurs.
interface DabResponse {
status: number;
error?: string;
}
Parameter | Description |
---|---|
status | status code |
error | optional explanation of the error |
Status code | Description |
---|---|
200 | The request was successful. |
400 | Bad request. The request was invalid or malformed. The explanation of the error must be included in the error field of the response. |
500 | Internal error. The explanation of the error must be included in the error field of the response. |
501 | Not implemented. The device must return this error when the requested functionality is not implemented. |
An operation must respond with one of the above common status codes, unless the operation states otherwise.
A response with the success status code
{
"status": 200
}
A response with the error status code
{
"status": 400,
"error": "App parameter is required to launch the application"
}
Unsolicited Messages are a feature of MQTT. An unsolicited message is a message that can be sent to communicate temporal messages like memory usage. In most cases, the client will subscribe to a topic where these messages are being sent. The client may or may not have to send a request for these messages to be enabled. Subscribing to the topic does not give the client a history or even the last published message - they will only get future messages.
Friendly name | Type identifier | Description | Example |
---|---|---|---|
Language code | rfc_5646_language_tag |
All language tags use the IETF language tags defined in RFC 5646. All language tags are string fields. | "en-US" |
UNIX Time stamp | unix_timestamp_ms |
UNIX Epoch time in milliseconds. The data type is a 64 bit unsigned integer. | 1568815387403 |
Application Identifier | appId |
The application identifier consists of characters. For resiliency, uppercase letters are equivalent to lowercase (e.g., "netflix" is the same as "Netflix"). The minimum number of characters is 1 and the maximum is 64. | "PrimeVideo" |
Uniform Resource Locator | url |
MQTT has a max play load size of 256mb for binary data. HTTP is used for pushing and pulling resources from devices to support larger media files. URLs are defined in RFC 3986. | http://192.168.0.1/file |
In order to refer to applications and voice systems in a standardized manner, key application identifiers and voice system names are provided within Secton 7 -- Appendix. DAB implementations must use these appId and voice system names, and not any internal codenames. This is necessary for test automation to use uniform names across all DAB-capable platforms.
Operation model: Request / Response
The operation lists all the DAB operations supported by the device. All devices are required to implement this operation. The operations are identified by the name of the topic without the dab
prefix. The result should not include the list operations operation itself.
dab/<device-id>/operations/list
type ListSupportedOperationRequest = DabRequest
interface ListSupportedOperationResponse extends DabResponse {
operations: string [];
}
Parameter | Description |
---|---|
operations | a list of operations supported by the DAB device client |
{
"status": 200,
"operations": [
"applications/list",
"applications/launch",
"applications/launch-with-content",
"applications/get-state",
"applications/exit",
"device/info",
"system/restart",
"system/settings/list",
"system/settings/get",
"system/settings/set",
"input/key/list",
"input/key-press",
"input/long-key-press",
"output/image",
"device-telemetry/start",
"device-telemetry/stop",
"device-telemetry/metrics",
"app-telemetry/start",
"app-telemetry/stop",
"app-telemetry/metrics",
"health-check/get",
"messages",
"voice/list",
"voice/send-audio",
"voice/send-text",
]
}
An application can be in one of the following states:
State | Description |
---|---|
STOPPED | There is no instance of the application running on the device. |
FOREGROUND | The application is visible, active and accepting input. |
BACKGROUND | There is a running instance of the application on the device but it is not visible and not accepting input. |
Your device may support more states, choose the one that best represents the described state
Operation model: Request / Response
This operation lists the applications installed on the device. This list can be limited to applications that are known to leverage DAB.
dab/<device-id>/applications/list
type ListApplicationsRequest = DabRequest
interface Application {
appId: string;
friendlyName?: string;
version?: string;
}
Parameter | Description |
---|---|
appId | Application Identifier, as defined in the DAB Registry |
friendlyName | optional application friendly name |
version | optional application version |
interface ListApplicationsResponse extends DabResponse {
applications: Application [];
}
Parameter | Description |
---|---|
applications | a list of applications |
{
"status": 200,
"applications": [
{
"appId": "Netflix",
"friendlyName": "Netflix",
"version": "2.0.0"
},
{
"appId": "PrimeVideo",
"friendlyName": "Amazon Prime Video",
"version": "2.0.0"
},
{
"appId": "YouTube",
"friendlyName": "YouTube",
"version": "2.0.0"
}
]
}
Operation model: Request / Response
This operation launches an instance of the application into the FOREGROUND state. There can only be one instance of an application running in the system and the instance is referenced by the application identifier. The response should only be sent after the application state has changed on the platform.
- If the application is in the STOPPED state, this operation will launch a new instance into the FOREGROUND state.
- If the application is in the BACKGROUND state, this operation will bring the instance of the application into the FOREGROUND state.
- If the application is in the FOREGROUND state, this operation will not change the state of the application.
dab/<device-id>/applications/launch
interface LaunchApplicationRequest extends DabRequest {
appId: string;
parameters?: string [];
}
Parameter | Default | Description |
---|---|---|
appId | - | Application Identifier |
parameters | [] |
URL encoded list of parameters to be passed to the application being launched (usually directly to the app executable). The technique to pass parameters may be app specific. Please work with app partners in DAB Registry for how the parameters are expected to be passed. |
{
"appId": "Netflix",
"parameters": [
"-KEY",
"https%3A%2F%2Fwww.example-value.com%2F",
"-STANDALONE_PARAM",
"%22param-with-quotes%22",
]
}
In the above sample, since parameters
is defined, DAB implementations must URL decode each parameter and pass them in order. As an example, for Netflix it would look like ./netflix -KEY https://www.example-value.com -STANDALONE_PARAM "param-with-quotes"
. Note how the order is preserved and parameters containing quotes and other miscellaneous characters are passed without issue due to URL encoding / decoding.
type LaunchApplicationResponse = DabResponse
Operation model: Request / Response
This operation launches the application into FOREGROUND state with the specified content (also known as deep linking). There can only be one instance of an application running in the system and the instance is referenced by the application identifier. The response should only be sent after the application state has changed on the platform.
- If the application is in the STOPPED state, this operation will launch a new instance into the FOREGROUND state with the specified content
- If the application is in the BACKGROUND state, this operation will bring the instance of the application into the FOREGROUND and pass the specified content to the instance
- If the application is in the FOREGROUND state, this operation will pass the content to the instance
dab/<device-id>/applications/launch-with-content
interface LaunchApplicationWithContentRequest extends DabRequest {
appId: string;
contentId: string;
parameters?: string [];
}
Parameter | Default | Description |
---|---|---|
appId | - | Application Identifier |
contentId | - | Application specific content identifier |
parameters | [] |
URL encoded list of parameters to be passed to the application being launched (usually directly to the app executable). The technique to pass parameters may be app specific. Please work with app partners in DAB Registry for how the parameters are expected to be passed. |
{
"appId": "YouTube",
"contentId": "XqZsoesa55w"
}
type LaunchApplicationWithContentResponse = DabResponse
Operation model: Request / Response
This operation returns the state the application is in.
dab/<device-id>/applications/get-state
interface GetApplicationStateRequest extends DabRequest {
appId: string;
}
Parameter | Default | Description |
---|---|---|
appId | - | Application Identifier |
{
"appId": "YouTube"
}
interface GetApplicationStateResponse extends DabResponse {
state: string;
}
Parameter | Description |
---|---|
state | state of the application at the time of the request, one of STOPPED , BACKGROUND or FOREGROUND |
{
"status": 200,
"state": "BACKGROUND"
}
Operation model: Request / Response
This operation exits the application.
- If the optional background parameter is set, this operation attempts to move the application to the BACKGROUND state.
- If the background parameter is omitted or is set to false, this operation attempts to completely stop the application and move it to a STOPPED state.
When using the exit operation without the background flag, the intention is to stop/kill the corresponding application process.
When using the exit operation with the background flag, the intention is to put the application in a background state, similarly to when the user presses the home
key.
The response should only be sent after the application state has changed on the platform.
dab/<device-id>/applications/exit
interface ExitApplicationRequest extends DabRequest {
appId: string;
background?: boolean;
}
Parameter | Default | Description |
---|---|---|
appId | - | Application Identifier |
background | false | decides whether to background or completely stop the application |
{
"appId": "PrimeVideo",
"background": false
}
interface ExitApplicationResponse extends DabResponse {
state: string;
}
Parameter | Description |
---|---|
state | state of the application after the exit operation |
{
"status": 200,
"state": "STOPPED"
}
Operation model: Request / Response
dab/<device-id>/device/info
type GetDeviceInformationRequest = DabRequest
enum NetworkInterfaceType {
Ethernet = "Ethernet",
Wifi = "Wifi",
Bluetooth = "Bluetooth",
Coax = "Coax",
Other = "Other",
}
enum displayType {
// Device has native display capability
Native = "Native",
// Device cannot display natively and needs an external display connected
External = "External",
}
interface NetworkInterface {
connected: boolean;
macAddress: string;
ipAddress?: string;
dns?: string [];
type: NetworkInterfaceType;
}
interface GetDeviceInformationResponse extends DabResponse {
manufacturer: string;
model: string;
serialNumber: string;
chipset: string;
firmwareVersion: string;
firmwareBuild: string;
networkInterfaces: NetworkInterface [];
displayType: DisplayType;
screenWidthPixels: number;
screenHeightPixels: number;
uptimeSince: unix_timestamp_ms;
deviceId: string;
}
Parameter | Description |
---|---|
manufacturer | The device manufacturer e.g. Samsung |
model | The device model e.g. UE32F4500 |
serialNumber | String used by the manufacturer to uniquely identify this device |
chipset | Device chipset e.g. X12 |
firmwareVersion | Device OS or firmware version e.g. 7.00 |
firmwareBuild | Device OS or firmware build number e.g. 60129 |
networkInterfaces | One or more network interfaces, indicating the type (e.g. WiFi, Ethernet, Bluetooth), connection status, MAC address, and IP address (if applicable) |
displayType | Type of display used by the device e.g. Native display like TVs, Monitors, Projector etc or an external display like HDMI/DisplayPort used by STBs, Streaming Sticks, Soundbars etc |
screenWidthPixels | Current screen resolution width measured in pixels (e.g. 1920). Should not be present when no screen is attached. |
screenHeightPixels | Current screen resolution height measured in pixels (e.g. 1080). Should not be present when no screen is attached. |
uptimeSince | The unix timestamp of when the device was last booted (e.g. 1615205137769 would denote the device was last booted on Mon Mar 08 2021 12:05:37, UTC) |
deviceId | The unique identifier of this device. Should be same as in the topic. |
If any of the parameters are not applicable/supported, the whole parameter should be omitted from the response.
Operation model: Request / Response
This operation will start the device restart sequence. After the device is restarted, DAB should stay enabled; DAB remaining enabled is the only expectation of the specification.
dab/<device-id>/system/restart
type RestartDeviceRequest = DabRequest
type RestartDeviceResponse = DabResponse
Success:
{
"status": 200
}
Error:
{
"status": 403,
"error": "insufficient privileges"
}
Operation model: Request / Response
This operation is used to retrieve the possible values that can be assigned to each system setting.
Implementations must consider the current operating environment and surface only the setting values that the device believes is possible to set.
dab/<device-id>/system/settings/list
type ListSupportedSystemSettingsRequest = DabRequest
interface OutputResolution {
width: int;
height: int;
frequency: number;
}
enum MatchContentFrameRate {
// Match Content Frame Rate is Always Allowed even if the transition is not Seamless
EnabledAlways = "EnabledAlways",
// Match Content Frame Rate is Only Allowed when the transition is Seamless
EnabledSeamlessOnly = "EnabledSeamlessOnly",
// Match Content Frame Rate is Disabled
Disabled = "Disabled",
}
enum HdrOutputMode {
// Always output HDMI signal in HDR Format
AlwaysHdr = "AlwaysHdr",
// Output HDMI signal in HDR Format Only when playing HDR content
HdrOnPlayback = "HdrOnPlayback",
// Never Output HDMI Signal in HDR Mode
DisableHdr = "DisableHdr",
}
enum PictureMode {
// Standard Mode or Normal Mode
Standard = "Standard",
// Dynamic or Vivid Mode
Dynamic = "Dynamic",
// Movie or Cinema Mode
Movie = "Movie",
// Sports Mode
Sports = "Sports",
// Filmmaker Mode
FilmMaker = "FilmMaker",
// Game Mode, Lowest Latency Option
Game = "Game",
// Automatically adjust the picture mode to the best option for current content
Auto = "Auto",
}
enum AudioOutputMode {
// 2 Channel PCM
Stereo = "Stereo",
// Multichannel PCM e.g. 5.1 PCM
MultichannelPcm = "MultichannelPcm",
// Bitstreams sent in passthrough mode
PassThrough = "PassThrough",
// Audio Output Mode Recommended by the device partner in current setup
Auto = "Auto",
}
enum AudioOutputSource {
// Audio Output on Native Speakers of the device
NativeSpeaker = "NativeSpeaker",
// Audio Output on ARC Port
Arc = "Arc",
// Audio Output on E-ARC Port
EArc = "EArc",
// Audio Output on Optical Port
Optical = "Optical",
// Audio Output on Auxilliary Port
Aux = "Aux",
// Audio Output on connected Bluetooth Speaker
Bluetooth = "Bluetooth",
// Audio Output in the default mode recommended by the device partner in current setup
Auto = "Auto",
// HDMI, This is only applicable for Source devices
HDMI = "HDMI",
}
enum VideoInputSource {
// TV Tuner / Antenna
Tuner = "Tuner",
// First HDMI Input Port
HDMI1 = "HDMI1",
// Second HDMI Input Port
HDMI2 = "HDMI2",
// Third HDMI Input Port
HDMI3 = "HDMI3",
// Fourth HDMI Input Port
HDMI4 = "HDMI4",
// Composite input port
Composite = "Composite",
// Component input port
Component = "Component",
// TV Home Screen
Home = "Home",
// Wireless Casting
Cast = "Cast",
}
interface ListSupportedSystemSettingsResponse extends DabResponse {
language: rfc_5646_language_tag [];
outputResolution: OutputResolution [];
memc: boolean;
cec: boolean;
lowLatencyMode: boolean;
matchContentFrameRate: MatchContentFrameRate [];
hdrOutputMode: HdrOutputMode [];
pictureMode: PictureMode [];
audioOutputMode: AudioOutputMode [];
audioOutputSource: AudioOutputSource [];
videoInputSource: VideoInputSource [];
audioVolume: {
min: int;
max: int;
},
mute: boolean;
textToSpeech: boolean;
}
Setting | Description |
---|---|
language | All possible language settings per RFC 5646 language tag |
outputResolution | All possible Video output resolutions for the device |
memc | Motion estimation and compensation setting support |
cec | CEC feature support on the device |
lowLatencyMode | Low Latency Mode Setting support |
matchContentFrameRate | Match Content FrameRate selection options |
hdrOutputMode | HDR Output Mode options on the Source Device |
pictureMode | Picture modes supported by the device |
audioOutputMode | Audio Output modes supported by the device |
audioOutputSource | Audio output source selection options |
videoInputSource | Video input source options on TV |
audioVolume | Audio output volume control range. If it cannot be controlled by device, set both min and max equal to the current volume level. |
mute | Volume mute operation support by the device |
textToSpeech | Text to Speech support on the device |
Type | Sample Value | Description |
---|---|---|
list | ["a", "b"] | list of all the possible values. Empty list means it's not supported. |
boolean | true | This is a on/off only setting. true means there exists at-least one circumstance where the feature is supported, false if not. |
number | 3 | Usually goes by range with min max pair. Having min>max means it's not supported. |
{
"status": 200,
"language": ["en-US", "es"],
"outputResolution": [{
"width": 3840,
"height": 2160,
"frequency": 60
},
{
"width": 1920,
"height": 1080,
"frequency": 60
}],
"memc": false,
"cec": true,
"lowLatencyMode": true,
"matchContentFrameRate": ["EnabledAlways", "EnabledSeamlessOnly","Disabled"],
"hdrOutputMode": ["AlwaysHdr", "HdrOnPlayback", "DisableHdr"],
"pictureMode": ["Standard", "Dynamic", "Movie"],
"audioOutputMode": ["Stereo", "Auto"],
"audioOutputSource": ["HDMI", "Optical"],
"videoInputSource": [],
"audioVolume": {
"min": 0,
"max": 100
},
"mute": false,
"textToSpeech": true
}
Operation model: Request / Response
This operation is used to retrieve the current settings on the device.
dab/<device-id>/system/settings/get
type GetCurrentSystemSettingsRequest = DabRequest
interface GetCurrentSystemSettingsResponse extends DabResponse {
language: rfc_5646_language_tag;
outputResolution: OutputResolution;
memc: boolean;
cec: boolean;
lowLatencyMode: boolean;
matchContentFrameRate: MatchContentFrameRate;
hdrOutputMode: HdrOutputMode;
pictureMode: PictureMode;
audioOutputMode: AudioOutputMode;
audioOutputSource: AudioOutputSource;
videoInputSource: VideoInputSource;
audioVolume: int;
mute: boolean;
textToSpeech: boolean;
}
Setting | Description |
---|---|
language | Current language setting per RFC 5646 language tag |
outputResolution | Current Video output resolution for the device |
memc | Current Motion estimation and compensation setting used |
cec | Current CEC feature state on the device |
lowLatencyMode | Current Low Latency Mode Setting used on the device |
matchContentFrameRate | Current Match Content FrameRate selected option |
hdrOutputMode | HDR Output Mode as selected on the Source Device |
pictureMode | Picture modes currently used by the device |
audioOutputMode | Audio Output mode currently used by the device |
audioOutputSource | Current Audio output source selected on the device |
videoInputSource | Current Video input source selected on TV |
audioVolume | Current audio output volume |
mute | Current Volume mute state |
textToSpeech | Current Text to Speech state |
{
"status": 200,
"language": "en-US",
"outputResolution": {
"width": 3840,
"height": 2160,
"frequency": 60
},
"memc": false,
"cec": true,
"lowLatencyMode": true,
"matchContentFrameRate": "EnabledSeamlessOnly",
"hdrOutputMode": "AlwaysHdr",
"pictureMode": "Other",
"audioOutputMode": "Auto",
"audioOutputSource": "HDMI",
"videoInputSource": "Other",
"audioVolume": 20,
"mute": false,
"textToSpeech": true
}
Operation model: Request / Response
This operation is used to update a discreet settings on the device. This operation updates device settings. Some changes, such as language adjustments, may require significant time to complete. The operation should only return once the setting change has fully taken effect. For settings with longer processing times, DAB clients will use an extended timeout value when making these requests.
dab/<device-id>/system/settings/set
interface SetSystemSettingsRequest extends DabRequest {
[system_setting_key: keyof SystemSettings]: [value: any];
}
{
"outputResolution": {
"width": 3840,
"height": 2160,
"frequency": 60
}
}
interface SetSystemSettingsResponse extends DabResponse {
[system_setting_key: keyof SystemSettings]: [value: any];
}
Success:
{
"status": 200,
"outputResolution": {
"width": 3840,
"height": 2160,
"frequency": 60
}
}
Error:
{
"status": 400,
"error": "Setting outputResolution does not support value { width: 3840, height: 2160, frequency: 60}"
}
Below is a list of common key codes applicable to all Input operations in this section.
Key Code | Description |
---|---|
KEY_POWER | power on / power off the device |
KEY_HOME | go to home screen |
KEY_VOLUME_UP | increase the volume |
KEY_VOLUME_DOWN | decrease the volume |
KEY_MUTE | mute audio |
KEY_CHANNEL_UP | next channel |
KEY_CHANNEL_DOWN | previous channel |
KEY_MENU | go to main menu |
KEY_EXIT | exit from current screen |
KEY_INFO | display program information |
KEY_GUIDE | display guide screen |
KEY_CAPTIONS | toggle closed captions/subtitles |
KEY_UP | navigation: go up |
KEY_PAGE_UP | navigation: page up |
KEY_PAGE_DOWN | navigation: page down |
KEY_RIGHT | navigation: go right |
KEY_DOWN | navigation: go down |
KEY_LEFT | navigation: go left |
KEY_ENTER | confirm current selection |
KEY_BACK | go to the previous screen |
KEY_PLAY | start playback |
KEY_PLAY_PAUSE | start or pause playback |
KEY_PAUSE | pause playback |
KEY_RECORD | start recording |
KEY_STOP | stop recording |
KEY_REWIND | rewind playback (continuous) |
KEY_FAST_FORWARD | fast forward playback (continuous) |
KEY_SKIP_REWIND | rewind/skip (set increments) |
KEY_SKIP_FAST_FORWARD | fast forward (set increments) |
KEY_0 | 0 numeric key |
KEY_1 | 1 numeric key |
KEY_2 | 2 numeric key |
KEY_3 | 3 numeric key |
KEY_4 | 4 numeric key |
KEY_5 | 5 numeric key |
KEY_6 | 6 numeric key |
KEY_7 | 7 numeric key |
KEY_8 | 8 numeric key |
KEY_9 | 9 numeric key |
KEY_RED | red function button |
KEY_GREEN | green function button |
KEY_YELLOW | yellow function button |
KEY_BLUE | blue function button |
If an action is available on the device, it must be mapped to one of the specified key codes.
The device may choose to accept key codes not specified in the Common key codes section above if they are supported (e.g. vendor buttons). Custom keys must start with KEY_CUSTOM_
prefix.
Operation model: Request / Response
This operation retrieves the list of all the input key codes supported by the device.
dab/<device-id>/input/key/list
type ListSupportedKeysRequest = DabRequest
interface ListSupportedKeysResponse extends DabResponse {
keyCodes: string [];
}
Parameter | Description |
---|---|
keyCodes | list of key codes supported by the device |
{
"status": 200,
"keyCodes": [
"KEY_POWER",
"KEY_HOME",
"KEY_MENU",
"KEY_EXIT",
"KEY_INFO",
"KEY_UP",
"KEY_RIGHT",
"KEY_DOWN",
"KEY_LEFT",
"KEY_ENTER",
"KEY_BACK"
]
}
Operation model: Request / Response
This operation sends a key press to the device. Key press is an action that can be associated with the key press on the remote control. The operational should mimic the same behavior as a key press and release of a remote control. A key code represents button name or function name typically found on the remote control.
dab/<device-id>/input/key-press
interface SendKeyPressRequest extends DabRequest {
keyCode: string;
}
Parameter | Description |
---|---|
keyCode | string literal, prefixed with KEY_ , representing the button name / function name, e.g. KEY_PLAY . A valid key code consists of a sequence of alpha-numeric characters and/or _ (underscore) characters. The minimum number of characters is 1 and the maximum is 64. |
To navigate left in the menu
{
"keyCode": "KEY_LEFT"
}
To press Vendor 1
key on the remote. Vendor 1
is a custom key and its key code starts with KEY_CUSTOM_
{
"keyCode": "KEY_CUSTOM_VENDOR_1"
}
type SendKeyPressResponse = DabResponse
Operation model: Request / Response
This operation mimics the action of pressing a key for a specified duration.
dab/<device-id>/input/long-key-press
interface SendLongKeyPressRequest extends DabRequest {
keyCode: string;
durationMs: int;
}
Parameter | Description |
---|---|
keyCode | string literal, prefixed with KEY_ , representing the button name / function name, e.g. KEY_PLAY . A valid key code consists of a sequence of alpha-numeric characters and/or _ (underscore) characters. The minimum number of characters is 1 and the maximum is 64. |
durationMs | Duration in milliseconds for which the key specified in keyCode must be pressed |
To press the left key for 3 seconds
{
"keyCode": "KEY_LEFT",
"durationMs": 3000
}
type SendLongKeyPressResponse = DabResponse
Retrieves outputs from the device (such as images, audio, etc.). Images are the only outputs currently supported.
Operation model: Request / Response
This operation captures the current output of the device and returns an image that is base64 encoded. The image must include both graphics plane content and clear (non-DRM) stream video. DRM content and any video that passes through the device's secure video pipeline or trusted execution environment shall not be in the captured image. The image data must be in PNG format.
dab/<device-id>/output/image
interface CaptureScreenshotRequest = DabRequest
interface CaptureScreenshotResponse extends DabResponse {
outputImage: string;
}
Parameter | Description |
---|---|
outputImage | base64 encoded PNG image in a data URL |
{
"outputImage": "data:image/png;base64,iVBORw0KGgo..."
}
Device and application telemetry allows the connected clients to gather metrics about the device and the applications running on the device. To start or stop the telemetry, either for the device or for the specific application, a request must be made to the correct request topic.
Once the telemetry is started the device will start publishing metrics to the assigned telemetry notification topic until requested to stop. Telemetry is stateless, and it is expected that start telemetry will have to be requested again after a device restart.
Operation model: Request / Response
dab/<device-id>/device-telemetry/start
interface StartDeviceTelemetryRequest extends DabRequest {
duration: number;
}
Parameter | Default | Description |
---|---|---|
duration | - | desired pull duration for telemetry updates in milliseconds |
A request to start telemetry for the device with the pull duration of 500 milliseconds
{
"duration": 500
}
interface StartDeviceTelemetryResponse extends DabResponse {
duration: number;
}
Parameter | Description |
---|---|
duration | actual duration between pull requests device is capable of for telemetry updates |
Telemetry started with the actual duration of 1 second
{
"status": 200,
"duration": 1000
}
Operation model: Request / Response
dab/<device-id>/device-telemetry/stop
interface StopDeviceTelemetryRequest extends DabRequest {
}
type StopDeviceTelemetryResponse = DabResponse
Operation model: Request / Response
dab/<device-id>/app-telemetry/start
interface StartApplicationTelemetryRequest extends DabRequest {
appId: string;
duration: number;
}
Parameter | Default | Description |
---|---|---|
appId | - | application identifier |
duration | - | desired duration for telemetry updates in milliseconds |
A request to start telemetry for the application media-player-1
with the duration of 5 seconds
{
"appId": "media-player-1",
"duration": 5000
}
interface StartApplicationTelemetryResponse extends DabResponse {
duration: number;
}
Parameter | Description |
---|---|
duration | actual duration device is capable of for telemetry updates |
Telemetry started with the actual duration of 1 second
{
"status": 200,
"duration": 1000
}
Operation model: Request / Response
dab/<device-id>/app-telemetry/stop
interface StopApplicationTelemetryRequest extends DabRequest {
appId: string;
}
Parameter | Description |
---|---|
appId | Application identifier |
To stop the telemetry for the application media-player-2
:
{
"appId": "media-player-2"
}
type StopApplicationTelemetryResponse = DabResponse
Scope | Notification Topic | Description |
---|---|---|
Device | dab/<device-id>/device-telemetry/metrics |
- |
Application | dab/<device-id>/app-telemetry/metrics/<appId> |
where <appId> is the application ID |
The application identified in the system by media-player-1
will have its metrics delivered to the notification topic dab/app-telemetry/metrics/media-player-1
List of supported metrics
Metric | Unit | Description | Example |
---|---|---|---|
cpu | percentage expressed as a number | optional Overall CPU usage scaled to the range of 0% to 100% | 26 |
memory | kilobytes | optional Memory usage | 43008 |
If an application is not running and the app specific telemetry collection is ongoing or gets started, the device should return 0 as the value for both cpu and memory metric.
interface TelemetryMessage {
timestamp: unix_timestamp_ms;
metric: string;
value: number;
}
Parameter | Description |
---|---|
timestamp | UNIX Epoch time in milliseconds |
metric | metric name |
value | value of the metric |
{
"timestamp": 1568815387403,
"metric": "cpu",
"value": 33.5
}
{
"timestamp": 1568815390414,
"metric": "memory",
"value": 44040192
}
Operation model: Request / Response
This operation checks whether DAB is enabled and operational on the device.
dab/<device-id>/health-check/get
type CheckDeviceHealthRequest = DabRequest
interface CheckDeviceHealthResponse extends DabResponse {
healthy: boolean;
message?: string;
}
Parameter | Description |
---|---|
healthy | true when DAB is enabled and operational, false otherwise |
message | optional message to indicate any problems with the DAB protocol |
{
"status": 200,
"healthy": true
}
{
"status": 200,
"healthy": false,
"message": "Internal DAB error"
}
The device may publish any errors, warnings, general information to the general notification topic. These messages provide developers an internal observability into the state of DAB on the device and help debug potential issues on the platform. While not required, it is highly suggested to at-least provide retained MQTT messages informing clients about the state of DAB as shown in the examples below.
dab/<device-id>/messages
type NotificationLevel = "info" | "warn" | "debug" | "trace" | "error";
interface Notification {
timestamp: unix_timestamp_ms;
level: NotificationLevel;
message: string;
}
Notification Level | Description |
---|---|
info |
A message at coarse-grained level |
warn |
A message indicating a warning, potentially problematic event |
debug |
A message intended to help with the debugging of the problem |
trace |
A message at fine-grained level, low-level details |
error |
A message indicating an error event |
Parameter | Description |
---|---|
timestamp | UNIX Epoch time in milliseconds |
level | Notification level |
message | Message |
{
"timestamp": 1610704569349,
"level": "info",
"message": "DAB started successfully and is online."
}
{
"timestamp": 1610704569349,
"level": "error",
"message": "DAB faced an exception. Terminating abnormally."
}
This section applies to all devices where users may interact with the device using a microphone.
A voice system can be any platform assistant or speech recognizer that accepts audio as input.
Operation model: Request / Response
This operation lists the available voice systems installed on the device.
dab/<device-id>/voice/list
type ListSupportedVoiceSystemsRequest = DabRequest
interface VoiceSystem {
name: string;
enabled: boolean;
}
Parameter | Description |
---|---|
name | Name of the voice system |
enabled | 'true' when the voice system is enabled on the platform, 'false' otherwise |
interface ListSupportedVoiceSystemsResponse extends DabResponse {
voiceSystems: VoiceSystem [];
}
Parameter | Description |
---|---|
voiceSystems | a list of available voice systems supported by the device, as defined in the DAB Voice System Registry |
{
"status": 200,
"voiceSystems": [
{
"name": "AmazonAlexa",
"enabled": true
},
{
"name": "GoogleAssistant",
"enabled": false
},
{
"name": "Siri",
"enabled": false
}
]
}
Operation model: Request / Response
This operation is used to change the currently enabled voice system(s). The platform shall determine whether multiple voice systems may be enabled concurrently.
dab/<device-id>/voice/set
interface SetVoiceSystemRequest extends DabRequest {
voiceSystem: VoiceSystem;
}
{
"voiceSystem": {
"name": "GoogleAssistant",
"enabled": true
},
}
interface SetVoiceSystemResponse extends DabResponse {
voiceSystem: VoiceSystem;
}
Success:
{
"status": 200,
"voiceSystem": {
"name": "GoogleAssistant",
"enabled": true
},
}
Error:
{
"status": 400,
"error": "Setting voiceSystem failed"
}
Operation model: Request / Response
This operation provides an HTTP URL identifying an audio file of MIME type audio/wav
to be used for a voice request. The platform must issue a GET request to the URL and appropriately route the retrieved audio through the platform as if it came from the device's microphone.
Audio must be a WAV format file containing 16-bit linear PCM, 16-kHz sample rate, single channel, little-endian byte order format. The sample rate must be contained in the header.
File size must not exceed 4MB.
dab/<device-id>/voice/send-audio
interface SendVoiceAsAudioRequest extends DabRequest {
fileLocation: url;
voiceSystem?: string;
}
Parameter | Default | Description |
---|---|---|
fileLocation | - | HTTP URL identifying the location of the audio resource for the platform to download. |
voiceSystem | - | Optional Specific voice system to direct the audio to. Voice system must be enabled first. As defined in the DAB Voice System Registry |
{
"fileLocation": "http://192.168.1.8:80/utterance_1.wav",
"voiceSystem": "AmazonAlexa"
}
type SendVoiceAsAudioResponse = DabResponse
{
"status": 200
}
{
"status": 400,
"error": "File not available at fileLocation"
}
Operation model: Request / Response
This operation provides a text string to be used for a simulated voice request. The platform must treat the text string as if it were the transcribed output of a traditional, microphone-initiated voice request.
dab/<device-id>/voice/send-text
interface SendVoiceAsTextRequest extends DabRequest {
requestText: string;
voiceSystem: string;
}
Parameter | Default | Description |
---|---|---|
requestText | - | The string to be passed as output of a voice system |
voiceSystem | - | Specific voice system to direct the audio to. Voice system must be enabled first. |
{
"requestText": "Play Ed Sheeran on YouTube",
"voiceSystem": "GoogleAssistant"
}
type SendVoiceAsTextResponse = DabResponse
{
"status": 200
}
{
"status": 501,
"error": "Not implemented"
}
Operation model: Request / Response
This operation provides a way for user client to discover devices under the same MQTT broker. For each DAB capable device a device discovery response must be provided.
dab/discovery
type DiscoverDevicesRequest = DabRequest
interface DiscoverDevicesResponse extends DabResponse {
ip: string;
deviceId: string;
}
Parameter | Description |
---|---|
ip | IP Address of the device. |
deviceId | The unique identifier of this device. Should be same as in other topics. |
{
"status": 200,
"ip": "192.168.1.119",
"deviceId": "device3"
}
Operation model: Request / Response
This operation allows the use clients to know the DAB version implemented on a device client. It is possible for a device to implement more than one version of the DAB protocol.
A protocol version consists of the major version and the minor version delimited by a full stop character .
Major and minor versions are non-negative integers.
Examples:
Valid versions:
1.0
, 2.3
, 0.48
Invalid versions
1.a
, x.5
dab/<device-id>/version
type GetDabVersionRequest = DabRequest
interface GetDabVersionResponse extends DabResponse {
versions: string [];
}
Parameter | Description |
---|---|
versions | a list of versions of the protocol implemented on the device |
{
"status": 200,
"versions": ["2.0"]
}
Application | DAB appId |
---|---|
Netflix | Netflix |
YouTube | YouTube |
Amazon Prime Video | PrimeVideo |
BBC iPlayer | uk.co.bbc.iplayer |
YouTube TV | YouTubeTV |
Voice System | DAB Voice System Name |
---|---|
Google Assistant | GoogleAssistant |
Amazon Alexa | AmazonAlexa |
LG ThinQ | LGThinQ |
Yandex Alice | YandexAlice |
TiVo Conversation | TiVoConversation |
WhaleAIVoice | WhaleAIVoice |
If you are an application or voice system owner and your identifier is not found in the registry, you can register it by following these steps:
- Fork this specification repository
- Add and commit your application or voice system identifier in your repo
- Create a pull request to merge your additions to this DAB specification
- A DAB consortium member will review your pull request, approve, and merge promptly
You can see more instructions on how to create a pull request from a forked repository on GitHub using these instructions.
This operation lists the available languages on the device.
All language operations apply to the device language. The device language is defined as the language setting that will be provided to applications as the device locale. All language codes used are defined in the RFC 5646 specification.
dab/system/language/list
type GetAvailableLanguagesRequest = DabRequest
interface GetAvailableLanguagesResponse extends DabResponse {
languages: rfc_5646_language_tag [];
}
{
"status": 200,
"languages": [
"en-GB",
"en-US",
"fr"
]
}
This operation returns the currently set language on the device.
dab/system/language/get
type GetCurrentLanguageRequest = DabRequest
interface GetCurrentLanguageResponse extends DabResponse {
language: rfc_5646_language_tag;
}
Parameter | Description |
---|---|
language | language that is currently set on the device |
Success:
{
"status": 200,
"language": "en-US"
}
This operation is used to update the language on the device. The language tag being set by the set topic must match a language tag in the list returned by the dab/system/language/list
topic.
dab/system/language/set
interface SetLanguageRequest extends DabRequest {
language: rfc_5646_language_tag;
}
type SetLanguageResponse = DabResponse
{
"status": 200
}