Virtual Component ControlPlane Commands

Overview of HDMI-CEC Virtual Component Control Plane Commands

The HDMI-CEC virtual component enables comprehensive testing of HDMI-CEC functionalities through the control plane. Testers can interact with the virtual component using four primary types of commands, each serving a distinct purpose:

Command: Directly trigger specific HDMI-CEC commands between devices, simulating real-world user interactions.

Event: Simulate HDMI-CEC events like hotplug (device connection/disconnection) to test how devices react.

Config: Modify the virtual CEC network configuration, changing device types, connections, and capabilities.

State: Dynamically add or remove devices during testing and print the current status for debugging.

Each command type is structured as a YAML payload, which is outlined in detail in the following sections. These payloads allow testers to precisely control the virtual HDMI-CEC environment, replicating various scenarios and edge cases.

1. Command

HDMI Consumer Electronics Control (CEC) commands are designed to allow control of multiple devices through a single remote control and enable devices to communicate with each other. These commands are categorized based on their functionalities and the end-user features they support.

Example YAML CEC Command

---
hdmicec:
  command: SetOsdName
  initiator: Sony HomeTheatre
  destination: IPSTB
  parameters:
    osd_name: IPSTB

2. Event

This category of messages allow the test user to trigger changes in the virtual component state machine.

Example Event

Command to trigger a hotplug event from device connected in Port 2:

hdmicec:
    command: hotplug
    port: 2
    connected: false

3. Config

Test user can also trigger a re-configuration of the initial profile with which the emulator state machine was set up, like the device type (Sink or Source) and the list of devices in the network etc.

Example config change trigger

---
hdmicec:
  config:
    emulated_device: IPSTB
    number_ports: 1
    ports:
      - id: 1
        type: out
        cec_supported: true
        arc_supported: false
    number_devices: 3
    device_map:
      - name: Sony TV
        type: TV
        version: 4
        active_source: false
        vendor_info: SONY
        pwr_status: on
        number_chlidren: 2
        children:
         -  name: IPSTB
            type: PlaybackDevice
            version: 4 
            active_source: true
            vendor: TEST_VENDOR
            pwr_status: on
            port_id: 1
            num_children: 0

         -  name: Chromecast
            type: PlaybackDevice
            version: 4
            active_source: false
            vendor: GOOGLE
            pwr_status: on
            port_id: 1
            num_children: 0

4. State

Test user can trigger state changes by dynamically adding or removing device(s). Debug printing of the current status of virtual component in logs can also be triggered.

Status	YAML Payload	Action
AddDevice	--- hdmicec: state: AddDevice parameters: parent: TV name: TestDevice type: PlaybackDevice version: 4 active_source: false vendor: TEST_VENDOR pwr_status: on port_id: 2 number_children: 0	Adds the new device as a child to given parent
RemoveDevice	--- hdmicec: state: RemoveDevice parameters: name: TestDevice	Removes a device and its children from the Virtual Component state.
PrintStatus	--- hdmicec: state: PrintStatus parameters: status: Devices	Prints the current network of devices

Parameters for PrintStatus

Parameter	Description	Values
status	Specific status	Devices, Ports, General

Example state trigger to add a new device to a parent port.

hdmicec:
    state: AddDevice
    prameters:
       parent: TV
       name: TestDevice
       type: PlaybackDevice
       version: 4
       active_source: false
       vendor: TEST_VENDOR
       pwr_status: on
       port_id: 2
       number_children: 0

Example state trigger to print status of devices connected

hdmicec:
    state: PrintStatus
    parameters:
       status: Devices

Anatomy of the YAML CEC Command

The YAML representation of CEC commands provides a structured and human-readable format for defining and triggering HDMI-CEC commands. These YAML commands closely follow the CEC specifications but are more descriptive in nature.

---
hdmicec:
  command: # The CEC command to be executed (e.g., SetOsdName, ActiveSource, UserControlPressed, etc.)
  initiator: # The device sending the command (e.g., Sony HomeTheatre, IPSTB, TV, etc.)
  destination: # The device receiving the command (e.g., TV, IPSTB, Broadcast, etc.)
  parameters: # Optional: Additional parameters required for the command
    # Add specific parameters below as needed for the command
    osd_name: # Example: OSD name to be set (for SetOsdName command)
    device_name: # Example: Physical address of the device (for ActiveSource or ReportPhysicalAddress commands)
    ui_command: # Example: User interface command (for UserControlPressed command)
    device_type: # Example: Device type (for ReportPhysicalAddress command)
    deck_info: # Example: Deck status information (for DeckStatus command)
    tuner_info: # Example: Tuner status information

Components of the YAML CEC Command

Root Element (hdmicec):

The root element of the YAML file, indicating that this is a CEC command.

Command:

The command key specifies the CEC command to be executed. Example: SetOsdName is the command to set the On-Screen Display name of a device.

Initiator:

The initiator key indicates the device that is sending the command. All devices are identified by its unique name that is configured in the profile YAML. The virtual component takes care of converting the device names into physical and logical addresses internaly.

Example: Sony HomeTheatre is the device initiating the command.

Destination:

The destination key specifies the target device that will receive the command. Example: IPSTB is the device receiving the command.

Parameters:

The parameters key holds a dictionary of additional data required for the command. Example: For the SetOsdName command, the parameters section includes an osd_name key with the value IPSTB.

Using the Parameters Section in Different CEC Commands

The parameters section in the YAML CEC command is used to provide additional data required for executing specific CEC commands. The parameters vary depending on the command being issued. Below are examples and descriptions of how the parameters section can be used in different CEC commands.

Example 1: SetOsdName

The SetOsdName command sets the On-Screen Display (OSD) name for a device. This command requires an osd_name parameter to specify the name to be set.

---
hdmicec:
  command: SetOsdName
  initiator: Sony HomeTheatre
  destination: IPSTB
  parameters:
    osd_name: IPSTB

Example 2: ActiveSource

The ActiveSource command is used to indicate which device is currently the active source. This command requires a physical_address parameter.

---
hdmicec:
  command: ActiveSource
  initiator: IPSTB
  destination: TV
  parameters:
    physical_address: 0x1000

Example 3: UserControlPressed

The UserControlPressed command simulates a button press on the remote control. This command requires a ui_command parameter to specify the user interface command.

---
hdmicec:
  command: UserControlPressed
  initiator: TV
  destination: IPSTB
  parameters:
    ui_command: Select

HDMI-CEC Command Categories Based on End User Features

HDMI CEC commands are categorized based on their functionalities and the end-user features they support.

Below are some of the commonly used categories of CEC commands:

1. One Touch Play

Commands in this category are used to turn on devices and switch them to the correct input automatically.

Command	YAML Payload	Action	How to Trigger in Real Setup
ActiveSource	--- hdmicec: command: "ActiveSource" initiator: "IPSTB" destination: "Broadcast" parameters: device_name: "TV"	Announces that the initiator is the active source	Automatically triggered when a device becomes active
ImageViewOn	--- hdmicec: command: "ImageViewOn" initiator: "DVD Player" destination: "TV"	Switches the TV to the initiator's input	Using a DVD player remote control to turn on the TV
TextViewOn	--- hdmicec: command: "TextViewOn" initiator: "DVD Player" destination: "TV"	Switches the TV to the initiator's input with text display	Using a DVD player remote control to turn on the TV

Example YAML Payloads

Active Source:

---
hdmicec:
  command: "ActiveSource"
  initiator: "IPSTB"
  destination: "Broadcast"
  parameters:
    device_name: "TV"

Image View On:

---
hdmicec:
  command: "ImageViewOn"
  initiator: "DVD Player"
  destination: "TV"

Text View On:

---
hdmicec:
  command: "TextViewOn"
  initiator: "DVD Player"
  destination: "TV"

2. One Touch Record

Allows whatever is shown on the TV screen to be recorded on a selected Recording Device.

Command	YAML Payload	Action	How to Trigger in Real Setup
RecordOn	--- hdmicec: command: RecordOn initiator: TV destination: RecordingDevice parameters: source: Tuner	Starts recording on the specified recording device	Using a TV remote control to start recording on a DVR
RecordOff	--- hdmicec: command: RecordOff initiator: TV destination: RecordingDevice	Stops recording on the specified recording device	Using a TV remote control to stop recording on a DVR
RecordStatus	--- hdmicec: command: RecordStatus initiator: RecordingDevice destination: TV parameters: status: Recording	Reports the current recording status of the device	Automatically triggered by the recording device to inform status

Parameters for RecordOn

Parameter	Description	Values
source	Source of the recording	Tuner, ExternalInput, Auxiliary

Parameters for RecordStatus

Parameter	Description	Values
status	Indicates the current recording status	Recording, NoRecording, InsufficientSpace, AlreadyRecording

Example YAML Payloads

Record On - Tuner Source:

---
hdmicec:
  command: RecordOn
  initiator: TV
  destination: RecordingDevice
  parameters:
    source: Tuner

Record Off:

---
hdmicec:
  command: RecordOff
  initiator: TV
  destination: RecordingDevice

Record Status - Recording:

---
hdmicec:
  command: RecordStatus
  initiator: RecordingDevice
  destination: TV
  parameters:
    status: Recording

3. Routing Control

These commands manage the routing of signals between devices, ensuring the correct source is displayed on the TV.

Command	YAML Payload	Action	How to Trigger in Real Setup
RoutingChange	--- hdmicec: command: "RoutingChange" initiator: "AV Receiver" destination: "Broadcast" parameters: from_device: "DVD Player" to_device: "TV"	Notifies that the source device has changed from one to another	Automatically triggered when the AV Receiver changes the input source
RoutingInformation	--- hdmicec: command: "RoutingInformation" initiator: "AV Receiver" destination: "Broadcast" parameters: device_name: "TV"	Provides information about the current routing path	Automatically triggered to inform the routing path change
RequestActiveSource	--- hdmicec: command: "RequestActiveSource" initiator: "TV" destination: "Broadcast"	Requests the active source device to identify itself	Using a TV remote control to switch inputs
SetStreamPath	--- hdmicec: command: "SetStreamPath" initiator: "TV" destination: "Broadcast" parameters: device_name: "AV Receiver"	Sets the stream path to the specified device	Using a TV remote control to select the AV Receiver
InactiveSource	--- hdmicec: command: "InactiveSource" initiator: "DVD Player" destination: "TV"	Notifies that the initiator device is no longer the active source	Automatically triggered when the DVD Player is turned off
ReportPhysicalAddress	--- hdmicec: command: "ReportPhysicalAddress" initiator: "AV Receiver" destination: "Broadcast" parameters: device_name: "TV"	Provides the physical address of the device	Automatically triggered when a device is connected
GivePhysicalAddress	--- hdmicec: command: "GivePhysicalAddress" initiator: "TV" destination: "AV Receiver"	Requests the physical address of the destination device	Using a TV remote control to identify the AV Receiver

Example YAML Payloads

Routing Change:

---
hdmicec:
  command: "RoutingChange"
  initiator: "AV Receiver"
  destination: "Broadcast"
  parameters:
    from_device: "DVD Player"
    to_device: "TV"

Routing Information:

---
hdmicec:
  command: "RoutingInformation"
  initiator: "AV Receiver"
  destination: "Broadcast"
  parameters:
    device_name: "TV"

Request Active Source:

---
hdmicec:
  command: "RequestActiveSource"
  initiator: "TV"
  destination: "Broadcast"

Set Stream Path:

---
hdmicec:
  command: "SetStreamPath"
  initiator: "TV"
  destination: "Broadcast"
  parameters:
    device_name: "AV Receiver"

Inactive Source:

---
hdmicec:
  command: "InactiveSource"
  initiator: "DVD Player"
  destination: "TV"

4. Deck Control

These commands control the playback devices, such as recorders and players.

Command	YAML Payload	Action	How to Trigger in Real Setup
DeckControl	--- hdmicec: command: DeckControl initiator: TV destination: PlaybackDevice1 parameters: deck_info: Play	Controls deck functions such as play, pause, etc.	Using a TV remote control to control playback functions
GiveDeckStatus	--- hdmicec: command: GiveDeckStatus initiator: TV destination: PlaybackDevice1 parameters: status_request: On	Requests the current status of the playback device	Automatically triggered by TV to get the status of the playback device
Play	--- hdmicec: command: Play initiator: TV destination: PlaybackDevice1 parameters: play_mode: PlayForward	Starts playback on the specified playback device	Using a TV remote control to play content
DeckStatus	--- hdmicec: command: DeckStatus initiator: PlaybackDevice1 destination: TV parameters: deck_info: Play	Reports the current status of the playback device	Automatically triggered by the playback device to inform its status

Parameters for DeckControl

Parameter	Description	Values
deck_info	Indicates the deck control mode	Play, Pause, Stop, Rewind, FastForward, Eject, Seek
seek_time	Time to seek to in milliseconds	0 to n (where n is the duration of the content in ms)

Possible Values for status_request

Prameter	Possible Values	Description
status_request	"On", "Off", "Once"	Requests status information from the device. "On" requests continuous updates, "Off" stops updates, "Once" requests a single update.

Parameters for Play

Parameter	Description	Values
play_mode	Indicates the play mode	PlayForward, PlayReverse, Still

Parameters for DeckStatus

Parameter	Description	Values
deck_info	Indicates the current status of the deck	Play, Pause, Stop, Rewind, FastForward

Example YAML Payloads

Deck Control - Play Command:

---
hdmicec:
  command: DeckControl
  initiator: TV
  destination: PlaybackDevice1
  parameters:
    deck_info: Play

Give Deck Status Command:

---
hdmicec:
  command: GiveDeckStatus
  initiator: TV
  destination: PlaybackDevice1
  parameters:
    status_request: 1

Play Command:

---
hdmicec:
  command: Play
  initiator: TV
  destination: PlaybackDevice1
  parameters:
    play_mode: PlayForward

Deck Status - Playing:

---
hdmicec:
  command: DeckStatus
  initiator: PlaybackDevice1
  destination: TV
  parameters:
    deck_info: Play

5. OSD Display

These commands manage the On-Screen Display settings and information.

Command	YAML Payload	Action	How to Trigger in Real Setup
SetOsdString	--- hdmicec: command: "SetOsdString" initiator: "PlaybackDevice1" destination: "TV" parameters: osd_string: "IPSTB"	Sets the OSD (On-Screen Display) string on the TV	Automatically triggered when the playback device sets the OSD string
SetOsdName	--- hdmicec: command: "SetOsdName" initiator: "TV" destination: "Broadcast" parameters: osd_name: "IPSTB"	Sets the OSD (On-Screen Display) name on all devices	Automatically triggered when the TV sets the OSD name
GiveOSDName	--- hdmicec: command: "GiveOSDName" initiator: "TV" destination: "Broadcast"	Requests the OSD (On-Screen Display) name from all devices	Using a TV remote control to request OSD name from all devices

Example YAML Payloads

Set OSD String ("IPSTB") on TV:

---
hdmicec:
  command: "SetOsdString"
  initiator: "PlaybackDevice1"
  destination: "TV"
  parameters:
    osd_string: "IPSTB"

Set OSD Name ("IPSTB") on all devices:

---
hdmicec:
  command: "SetOsdName"
  initiator: "TV"
  destination: "Broadcast"
  parameters:
    osd_name: "IPSTB"

Give OSD Name (Request from TV):

---
hdmicec:
  command: "GiveOSDName"
  initiator: "TV"
  destination: "Broadcast"

6. Device Menu Control

Commands to control the device's menu interface, enabling navigation and selection of menu items.

Command	YAML Payload	Action	How to Trigger in Real Setup
MenuRequest	--- hdmicec: command: "MenuRequest" initiator: "TV" destination: "PlaybackDevice1"	Requests the menu from the playback device	Using a TV remote control to request the menu from the device
MenuStatus	--- hdmicec: command: "MenuStatus" initiator: "PlaybackDevice1" destination: "TV" parameters: status: "activated"	Provides the status of the menu	Automatically triggered to inform the TV of the menu status
UserControlPressed	--- hdmicec: command: "UserControlPressed" initiator: "TV" destination: "PlaybackDevice1" parameters: ui_command: "Select"	Sends a user control command (Select) to the playback device	Using a TV remote control to send a select command to the device

Example YAML Payloads

Menu Request:

---
hdmicec:
  command: "MenuRequest"
  initiator: "TV"
  destination: "PlaybackDevice1"

Menu Status:

---
hdmicec:
  command: "MenuStatus"
  initiator: "PlaybackDevice1"
  destination: "TV"
  parameters:
    status: "activated"

User Control Pressed (Select):

---
hdmicec:
  command: "UserControlPressed"
  initiator: "TV"
  destination: "PlaybackDevice1"
  parameters:
    ui_command: "Select"

7. Remote Control Passthrough

Allows remote control commands to be sent directly to devices.

Command	YAML Payload	Action	How to Trigger in Real Setup
UserControlPressed	--- hdmicec: command: "UserControlPressed" initiator: "TV" destination: "PlaybackDevice1" parameters: ui_command: "Play"	Sends a user control command (Play) to the playback device	Using a TV remote control to send a play command to the device
UserControlReleased	--- hdmicec: command: "UserControlReleased" initiator: "TV" destination: "PlaybackDevice1" parameters: ui_command: "Play"	Sends a user control command (Play release) to the playback device	Using a TV remote control to release the play command on the device

Example YAML Payloads

User Control Pressed (Play):

---
hdmicec:
  command: "UserControlPressed"
  initiator: "TV"
  destination: "PlaybackDevice1"
  parameters:
    ui_command: "Play"

User Control Released (Play):

---
hdmicec:
  command: "UserControlReleased"
  initiator: "TV"
  destination: "PlaybackDevice1"
  parameters:
    ui_command: "Play"

8. Power Status

These commands manage the power state of devices, such as putting them into standby mode.

Command	YAML Payload	Action	How to Trigger in Real Setup
GiveDevicePowerStatus	--- hdmicec: command: "GiveDevicePowerStatus" initiator: "TV" destination: "AudioSystem"	Requests the power status of the audio system	Using a TV remote control to request power status from the audio system
ReportPowerStatus	--- hdmicec: command: "ReportPowerStatus" initiator: "AudioSystem" destination: "TV" parameters: power_status: "on"	Provides the power status of the audio system	Automatically triggered to inform the TV of the audio system power status
Standby	--- hdmicec: command: "Standby" initiator: "TV" destination: "AudioSystem"	Puts the audio system into standby mode	Using a TV remote control to send a standby command to the audio system

Example YAML Payloads

Give Device Power Status:

---
hdmicec:
  command: "GiveDevicePowerStatus"
  initiator: "TV"
  destination: "AudioSystem"

Report Power Status (On):

---
hdmicec:
  command: "ReportPowerStatus"
  initiator: "AudioSystem"
  destination: "TV"
  parameters:
    power_status: "on"

Standby:

---
hdmicec:
  command: "Standby"
  initiator: "TV"
  destination: "AudioSystem"

9. System Audio Control

When an Audio Amplifier / Receiver is connected with the TV, functionality like volume can be controlled using any of the remote controls of any cec enabled devices in the system.

Command	YAML Payload	Action	How to Trigger in Real Setup
GiveAudioStatus	--- hdmicec: command: "GiveAudioStatus" initiator: "TV" destination: "AudioSystem"	Requests the audio system status	Using a TV remote control to get the status of the audio system
GiveSystemAudioModeStatus	--- hdmicec: command: "GiveSystemAudioModeStatus" initiator: "TV" destination: "AudioSystem"	Requests the audio system mode status	Using a TV remote control to get the current audio system mode
ReportAudioStatus	--- hdmicec: command: "ReportAudioStatus" initiator: "AudioSystem" destination: "TV"	Provides the audio system status	Automatically triggered to inform the TV of the audio system status
ReportShortAudioDescriptor	--- hdmicec: command: "ReportShortAudioDescriptor" initiator: "AudioSystem" destination: "TV"	Provides the audio capabilities of the audio system	Automatically triggered to inform the TV of the audio capabilities
RequestAudioDescriptor	--- hdmicec: command: "RequestAudioDescriptor" initiator: "TV" destination: "AudioSystem"	Requests the audio capabilities from the audio system	Using a TV remote control to request audio capabilities from the audio system

Example YAML Payloads

Give Audio Status:

---
hdmicec:
  command: "GiveAudioStatus"
  initiator: "TV"
  destination: "AudioSystem"

Give System Audio Mode Status:

---
hdmicec:
  command: "GiveSystemAudioModeStatus"
  initiator: "TV"
  destination: "AudioSystem"

Report Audio Status:

---
hdmicec:
  command: "ReportAudioStatus"
  initiator: "AudioSystem"
  destination: "TV"

Report Short Audio Descriptor:

---
hdmicec:
  command: "ReportShortAudioDescriptor"
  initiator: "AudioSystem"
  destination: "TV"

Request Audio Descriptor:

---
hdmicec:
  command: "RequestAudioDescriptor"
  initiator: "TV"
  destination: "AudioSystem"

10. System Information

Command	YAML Payload	Action	How to Trigger in Real Setup
GetCECVersion	--- hdmicec: command: "GetCECVersion" initiator: "TV" destination: "Broadcast"	Requests the CEC version from all devices	Automatically triggered to get the CEC version
GetMenuLanguage	--- hdmicec: command: "GetMenuLanguage" initiator: "TV" destination: "AudioSystem"	Requests the menu language from the audio system	Using TV remote control to request menu language from audio system
SetMenuLanguage	--- hdmicec: command: "SetMenuLanguage" initiator: "TV" destination: "AudioSystem" parameters: menu_language: "ENG"	Sets the menu language on the audio system	Automatically triggered to set the menu language on the audio system
ReportPhysicalAddress	--- hdmicec: command: "ReportPhysicalAddress" initiator: "AudioSystem" destination: "TV" parameters: physical_address: [16, 0]	Reports the physical address of the audio system to the TV	Automatically triggered to report physical address to the TV

Example YAML Payloads

Get CEC Version (Request from TV):

---
hdmicec:
  command: "GetCECVersion"
  initiator: "TV"
  destination: "Broadcast"

Get Menu Language (Request from TV):

---
hdmicec:
  command: "GetMenuLanguage"
  initiator: "TV"
  destination: "AudioSystem"

Set Menu Language ("ENG") on AudioSystem:

---
hdmicec:
  command: "SetMenuLanguage"
  initiator: "TV"
  destination: "AudioSystem"
  parameters:
    menu_language: "ENG"

Report Physical Address (AudioSystem to TV):

---
hdmicec:
  command: "ReportPhysicalAddress"
  initiator: "AudioSystem"
  destination: "TV"
  parameters:
    physical_address: [16, 0]