com.webos.service.cec
API Summary
The CEC (Consumer Electronic Control) service allows webOS to control connected HDMI CEC devices.
Overview of the API
HDMI-CEC is a feature of HDMI which allows to command and control devices connected through HDMI without user intervention. For example:
- CEC can be used to control playback on a TV device connected via HDMI
- When you play a video on a Chromecast with the TV off, and the TV automatically powers on and switches to the Chromecast source.
These APIs provide the following support:
- Control a device that supports CEC, like a TV, connected via HDMI.
- Power the TV on or off
- Control TV playback
- Change the TV volume up or down
Methods
listAdapters
Description
Searches CEC adapters from system and list all the identified local CEC adapters.
Parameters
None
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
cecAdapters | Required | String array | List of local HDMI-CEC adapters. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | The reason for the failure of the operation. See the 'API Error Codes Reference' section for details. |
Example
Example : List HDMI-CEC adapters
# luna-send -n 1 -f luna://com.webos.service.cec/listAdapters '{ }'
Response:
{
"returnValue": true,
"cecAdapters" : [
"cec0",
"cec1"
]
}
scan
Description
Scans the CEC bus and provides information of the connected HDMI CEC devices.
Parameters
Name | Required | Type | Description |
---|---|---|---|
adapter | Optional | String | Input HDMI-CEC adapter. Default: cec0 |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
devices | Required | Object array: devices | Information about connected HDMI CEC devices. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | The reason for the failure of the operation. See the 'API Error Codes Reference' section for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1, 6 | See API Error Codes Reference | See API Error Codes Reference. |
Example
Example : Scan the cec0 adapter and list the devices
# luna-send -n 1 -f luna://com.webos.service.cec/scan '{ "adapter": "cec0" }'
Response:
{
"returnValue": true,
"devices" : [
{
"name": "TV"
"address": "0.0.0.0"
"activeSource": "no"
"vendor": "LG"
"osd": "TV"
"cecVersion": "1.3a"
"powerStatus": "on"
"language": "eng"
},
{
"name": "Recorder 1"
"address": "1.0.0.0"
"activeSource": "yes"
"vendor": "LG"
"osd": "CECTester"
"cecVersion": "1.3a"
"powerStatus": "on"
"language": "eng"
}
]
}
sendCommand
Description
Sends the input command to destination HDMI CEC devices connected on CEC bus.
Parameters
Name | Required | Type | Description |
---|---|---|---|
adapter | Optional | String | HDMI CEC device from which the command gets executed. Default: cec0 |
destAddress | Required | String | Physical or logical address of destination HDMI CEC device. |
timeout | Optional | Number | Reply timeout, in milliseconds. Default: 1000 |
command | Required | Object: command | Command to execute on destination CEC device. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | The reason for the failure of the operation. See the 'API Error Codes Reference' section for details. |
payload | Optional | Object | Response payload provides the array of return values for the requested parameters in key value form. Check examples below. Note: This parameter is only returned in cases where the arg value is not provided (this means the command is requesting for information). |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1, 2, 4, 5, 6, 7 | See API Error Codes Reference | See API Error Codes Reference. |
Example
Example : Set audio mute status off
# luna-send -n 1 -f luna://com.webos.service.cec/sendCommand '{
"adapter": "cec0",
"destAddress" : "0.0.0.0",
"timeout": 500,
"command" : {
"name" : "report-audio-status",
"args" : [
{ "arg" : "aud-mute-status", "value" : "off"}
]
}
}'
Response:
{
"returnValue": true
}
Example : Get language information
# luna-send -n 1 -f luna://com.webos.service.cec/sendCommand '{
"adapter": "cec0",
"destAddress" : "0.0.0.0",
"timeout": 500,
"command" : {
"name" : "system-information",
"args" : [
{ "arg" : "language"}
]
}
}'
Response:
{
"returnValue": true,
"payload" : [{"language": "eng"}]
}
Example : Get language and version information
# luna-send -n 1 -f luna://com.webos.service.cec/sendCommand '{
"adapter": "cec0",
"destAddress" : "0.0.0.0",
"timeout": 500,
"command" : {
"name" : "system-information",
"args" : [
{ "arg" : "language"},
{ "arg" : "version"}
]
}
}'
Response:
{
"returnValue": true,
"payload" : [
{"language": "eng"},
{"version": "1.3a"}
]
}
getConfig
Description
Gets the value of the specified input configuration.
Parameters
Name | Required | Type | Description |
---|---|---|---|
adapter | Optional | String | Input HDMI-CEC adapter. Default: cec0 |
key | Required | String | Key name to get configuration value. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
key | Required | String | Key name of input configuration. |
value | Required | String | Value of input configuration. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | The reason for the failure of the operation. See the 'API Error Codes Reference' section for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1, 2, 6 | See API Error Codes Reference | See API Error Codes Reference. |
Example
Example : Get the vendor ID
# luna-send -n 1 -f luna://com.webos.service.cec/getConfig '{ "adapter":"cec0", "key": "vendorId" }'
Response:
{
"returnValue": true,
"key": "vendorId",
"value": "LG"
}
setConfig
Description
Sets the input configuration.
Parameters
Name | Required | Type | Description |
---|---|---|---|
adapter | Optional | String | Input CEC adapter. Default: cec0 |
key | Required | String | Key name to set configuration value. Possible values are:
|
value | Required | String | Configuration value to be set for the specified key. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | The reason for the failure of the operation. See the 'API Error Codes Reference' section for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1, 2, 6 | See API Error Codes Reference | See API Error Codes Reference. |
Example
Example : Set the vendor ID
# luna-send -n 1 -f luna://com.webos.service.cec/setConfig '{"adapter":"cec0","key": "vendorId", "value": "LG"}'
Response:
{
"returnValue": true
}
Objects
devices
Contains information about connected HDMI CEC devices.
Name | Required | Type | Description |
---|---|---|---|
name | Required | String | Indicates HDMI CEC device name. |
address | Required | String | Physical address of HDMI CEC device that identifies the device uniquely on CEC bus. |
activeSource | Required | String | Indicates whether HDMI CEC device is currently active source or not. |
vendor | Required | String | Vendor name of connected HDMI CEC device. |
osd | Required | String | On-screen display (OSD) name of HDMI CEC device. |
cecVersion | Required | String | CEC version of connected HDMI CEC device. |
powerStatus | Required | String | Power status of connected HDMI CEC device. |
language | Required | String | Language of HDMI CEC device. |
command
Command to execute on destination HDMI CEC device.
Name | Required | Type | Description |
---|---|---|---|
name | Required | String | Indicates command to be executed. Possible values are:
|
args | Required | Object: args | An array of objects that contains list of arguments passed to command. |
args
Contains list of arguments passed to command.
Name | Required | Type | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
arg | Required | String | Indicates command argument. Below are supported "arg": Available command
| |||||||||||||||||||||||||||
value | Optional | String | Value of command argument. |
API Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1 | The JSON input does not match the expected schema | One or more of the parameters do not have the correct parameter type. See the "Parameters" table to know the expected data type for each input parameter. Note: Any required parameter missing will be a different error return based on the missing key. |
2 | Invalid input parameter | Invalid input parameter value. |
4 | Destination device not found | Provided input destination device is not found. |
5 | Invalid input command | Invalid input command, make sure that you have entered commands from list of available commands. |
6 | CEC adapter doesn't exist | Input CEC adapter does not exist. |
7 | Command aborted by target device | Command aborted by target device. |