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

ACG: cec.query

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: true: Operation is successful. false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
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

ACG: cec.query

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

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: true: Operation is successful. false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
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

ACG: cec.operation

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: true: Operation is successful. false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
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

ACG: cec.query

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: vendorId: Vendor ID of device. version: CEC Version of the device. osd: OSD name of the device. language: Menu language. powerState: Power status of the device. physicalAddress: Physical address of the device. logicalAddress: Logical address of the device. deviceType: Type of device (TV, recorder, playback).

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:

vendorId: Vendor ID of device.
version: CEC Version of the device.
osd: OSD name of the device.
language: Menu language.
powerState: Power status of the device.
physicalAddress: Physical address of the device.
logicalAddress: Logical address of the device.
deviceType: Type of device (TV, recorder, playback).

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Operation is successful. false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
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

ACG: cec.operation

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: vendorId: Vendor ID of device. version: CEC Version of the device. osd: OSD name of the device. language: Menu language. powerState: Power status of the device. physicalAddress: Physical address of the device. logicalAddress: Logical address of the device. deviceType: Type of device (TV, recorder, playback).
value	Required	String	Configuration value to be set for the specified key.

Name

Required

Type

Description

adapter

Optional

String

Input CEC adapter.

Default: cec0

key

Required

String

Key name to set configuration value.

Possible values are:

vendorId: Vendor ID of device.
version: CEC Version of the device.
osd: OSD name of the device.
language: Menu language.
powerState: Power status of the device.
physicalAddress: Physical address of the device.
logicalAddress: Logical address of the device.
deviceType: Type of device (TV, recorder, playback).

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:

true: Operation is successful.
false: Operation has failed. Check the 'errorCode' and 'errorText' fields.

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: report-power-status: Control power of remote device. report-audio-status: Audio Status. set-volume: Control volume of device. osd-display: Display OSD string on device. active: Make the device as active source. one-touch-play: One Touch Play. system-information: Checks following information: Vendor ID of device CEC Version OSD Name Menu Language Check if device is active source vendor-commands: Vendor commands.
args	Required	Object: args	An array of objects that contains list of arguments passed to command.

Name

Required

Type

Description

name

Required

String

Indicates command to be executed.

Possible values are:

report-power-status: Control power of remote device.
report-audio-status: Audio Status.
set-volume: Control volume of device.
osd-display: Display OSD string on device.
active: Make the device as active source.
one-touch-play: One Touch Play.
system-information: Checks following information:
- Vendor ID of device
- CEC Version
- OSD Name
- Menu Language
- Check if device is active source
vendor-commands: Vendor commands.

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

name	arg	value
report-power-status	pwr-state	on standby
report-audio-status	aud-mute-status	off on
set-volume	volume	up down
osd-display	osd	string
active	set-active	NA
one-touch-play	active-source	NA
system-information	vendor-id version name language power-state is-active	NA
vendor-commands	payload	raw data in hex (eg:20:36)

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.