Menu

Reference

com.webos.service.cec

Note
This API has been available since API level 17.

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

getConfig

ACG: cec.query
  • Added: API level 17

Description

Gets the value of the specified input configuration.

Parameters

Name

Required

Type

Description

adapterOptionalString

Input HDMI-CEC adapter.

Default: cec0

keyRequiredString

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

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

Key name of input configuration.

valueRequiredString

Value of input configuration.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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, 6See 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"
}

listAdapters

ACG: cec.query
  • Added: API level 17

Description

Searches CEC adapters from system and list all the identified local CEC adapters.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

List of local HDMI-CEC adapters.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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
  • Added: API level 17

Description

Scans the CEC bus and provides information of the connected HDMI CEC devices.

Parameters

Name

Required

Type

Description

adapterOptionalString

Input HDMI-CEC adapter.

Default: cec0

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

Information about connected HDMI CEC devices.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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, 6See 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
  • Added: API level 17

Description

Sends the input command to destination HDMI CEC devices connected on CEC bus.

Parameters

Name

Required

Type

Description

adapterOptionalString

HDMI CEC device from which the command gets executed.

Default: cec0

destAddressRequiredString

Physical or logical address of destination HDMI CEC device.

timeoutOptionalNumber

Reply timeout, in milliseconds.

Default: 1000

commandRequiredObject: command

Command to execute on destination CEC device.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

The error code for the failed operation.

errorTextOptionalString

The reason for the failure of the operation. See the 'API Error Codes Reference' section for details.

payloadOptionalObject

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, 7See 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"}
    ]
}

setConfig

ACG: cec.operation
  • Added: API level 17

Description

Sets the input configuration.

Parameters

Name

Required

Type

Description

adapterOptionalString

Input CEC adapter.

Default: cec0

keyRequiredString

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).
valueRequiredString

Configuration value to be set for the specified key.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

The error code for the failed operation.

errorTextOptionalString

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, 6See 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

args

Contains list of arguments passed to command.

Name

Required

Type

Description

argRequiredString

Indicates command argument. Below are supported "arg":

Available command

nameargvalue
report-power-statuspwr-state
  • on
  • standby
report-audio-statusaud-mute-status
  • off
  • on
set-volumevolume
  • up
  • down
osd-displayosdstring
activeset-active NA
one-touch-playactive-source NA
system-information
  • vendor-id
  • version
  • name
  • language
  • power-state
  • is-active
 NA
vendor-commandspayloadraw data in hex (eg:20:36)
valueOptionalString

Value of command argument.

command

Command to execute on destination HDMI CEC device.

Name

Required

Type

Description

nameRequiredString

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.
argsRequiredObject: args

An array of objects that contains list of arguments passed to command.

devices

Contains information about connected HDMI CEC devices.

Name

Required

Type

Description

nameRequiredString

Indicates HDMI CEC device name.

addressRequiredString

Physical address of HDMI CEC device that identifies the device uniquely on CEC bus.

activeSourceRequiredString

Indicates whether HDMI CEC device is currently active source or not.

vendorRequiredString

Vendor name of connected HDMI CEC device.

osdRequiredString

On-screen display (OSD) name of HDMI CEC device.

cecVersionRequiredString

CEC version of connected HDMI CEC device.

powerStatusRequiredString

Power status of connected HDMI CEC device.

languageRequiredString

Language of HDMI CEC device.

API Error Codes Reference

Error Code

Error Text

Error Description

1The 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.

2Invalid input parameter

Invalid input parameter value.

4Destination device not found

Provided input destination device is not found.

5Invalid input command

Invalid input command, make sure that you have entered commands from list of available commands.

6CEC adapter doesn't exist

Input CEC adapter does not exist.

7Command aborted by target device

Command aborted by target device.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents