Feature Summary<\/h2>\n\n\n
The HDMI_CEC API defines the ability to get connected HDMI devices, send messages to those devices, and to be notified when messages are received from HDMI devices.<\/p>\n
HDMI-CEC is a protocol that provides high-level control functions between audio-visual devices connected over HDMI. CEC is a one-wire bidirectional serial bus based on industry-standard AV.Link protocol to perform control functions. All audio-visual sources are connected directly or indirectly to a display device as the ‘root’ in a tree-like structure.<\/p>\n
- \n
- \n
Hardware support for HDMI-CEC as specified in HDMI 1.4a<\/p>\n
- \n
- CEC 4 – Electrical Specification<\/li>\n
- CEC 5 – Signaling and Bit Timings<\/li>\n
- CEC 6 – Frame Description<\/li>\n
- CEC 7 – Reliable Communication Mechanisms<\/li>\n
- CEC 8 – Protocol Extensions<\/li>\n
- CEC 9 – CEC Arbitration<\/li>\n
- CEC 10.1 – Physical Address Discovery<\/li>\n
- CEC 11 – Switch Requirements<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
- \n
- Send raw or formatted CEC messages on behalf of application<\/li>\n
- Provide received CEC messages to registered application listener<\/li>\n
- Get information about a device connected to HDMI input<\/li>\n
- Autonomously handle subset of CEC messages<\/li>\n
- Provide list of connected CEC capable device to application<\/li>\n
- Send “Feature Abort” response if message is not handled autonomously by RDK and message is not handled by application listener<\/li>\n<\/ul>\n\n\n
Device Applicability<\/h2>\n\n\n
This feature applies to the following devices:<\/p>\n
- \n
- Hybrid<\/li>\n
- IP<\/li>\n<\/ul>\n\n\n
Architecture Overview<\/h2>\n\n\n<\/p>\n
![](\"\/wp-content\/uploads\/sites\/16\/2023\/09\/Architecture%20overview.drawio.png\")
<\/p>\n\n\nHDMI-CEC Profiles supported in RDK<\/h2>\n\n\n
\n\n\n<\/colgroup> Profiles<\/strong><\/p><\/td>
Description<\/strong><\/p><\/td><\/tr>
Discovery<\/p><\/td>
Discover HDMI devices that support CEC and provide settop information to those devices<\/p><\/td><\/tr>
Power<\/p><\/td>
Synchronize settop power state with HDMI device power state<\/p><\/td><\/tr>
Switching<\/p><\/td>
Switch settop HDMI inputs to settop HDMI outputs<\/p><\/td><\/tr>
Channel Change<\/p><\/td>
Change channel on settop from HDMI device<\/p><\/td><\/tr>
Audio<\/p><\/td>
Control audio mute\/volume on HDMI device from settop and vice versa<\/p><\/td><\/tr>
User Input<\/p><\/td>
Accept user input commands from HDMI device<\/p><\/td><\/tr><\/tbody><\/table>\n\n\n<\/div>\n\n\n
Component Impacts<\/h2>\n\n\n
CEC Protocol Library<\/strong><\/p>\n
- \n
- Translate application commands to CEC commands<\/li>\n
- Receive CEC commands and provide to application listeners<\/li>\n
- Autonomously respond to a subset of CEC messages<\/li>\n<\/ul>\n
HDMI-CEC HAL<\/strong><\/p>\n
- \n
- Abstracts SoC HDMI-CEC driver from higher level components that means it will abstract SoC CEC library from CEC Protocol Library<\/li>\n
- it allow transmits\/receives HDMI-CEC messages<\/li>\n<\/ul>\n
SoC CEC Driver<\/strong><\/p>\n
- \n
- Serialize and send CEC commands<\/li>\n
- Receive CEC commands and provide to CEC Protocol Library<\/li>\n
- \n
Send EDID to HDMI source<\/p>\n<\/li>\n
- \n
Provide HDMI input connect notification<\/p>\n<\/li>\n<\/ul>\n
Service Manager<\/strong><\/p>\n
- \n
- \n
Provide HDMI input connect notification via State Observer API.<\/p>\n<\/li>\n
- \n
Select select video source<\/p>\n<\/li>\n<\/ul>\n
Device Settings HAL<\/strong><\/p>\n
Device Settings APIs that SoC vendors implement. It provides primitive and hardware specific implementation for each controllable aspect of the SoC. This level API is considered single-app mode only, even though its SoC implementation may potentially support multiple-app mode.<\/p>\n
- \n
- Initialize and terminate device inputs and outputs.<\/li>\n
- Determine device settings capabilities (e.g. supported video resolutions, audio modes, etc).<\/li>\n
- Modify device settings (e.g. audio encoding).<\/li>\n
- Modify front panel LEDs.<\/li>\n
- \n
Provide HDMI event notification<\/p>\n<\/li>\n
- \n
Read\/Modify\/Write EDID<\/p>\n<\/li>\n
- \n
Add dsRegisterHdmiListener<\/p>\n<\/li>\n
- \n
Add dsSelectVideoSource<\/p>\n<\/li>\n
- \n
Add dsScaleVideoSource<\/p>\n<\/li>\n<\/ul>\n
SoC Video Pipeline<\/strong><\/p>\n
- \n
- \n
Source video from HDMI input<\/p>\n<\/li>\n<\/ul>\n\n\n
How HDMI-CEC Works in RDK<\/h2>\n\n\n<\/p>\n
![](\"\/wp-content\/uploads\/sites\/16\/2023\/09\/HDMI.drawio.png\")
<\/p>\n\n\nApplication API Specification<\/h2>\n\n\n
Overall the RDK-CEC library offers 3 categories of application APIs,<\/p>\n
HDMI-CEC Connection<\/strong><\/p>\n
- \n
- The Connection APIs allows application to transmit and receive raw data bytes (a.k.a. CEC Frame) that conforms to the HDMI-CEC specification. <\/li>\n
- This is the only interface that the application can use to access CEC Bus.<\/li>\n<\/ul>\n
HDMI-CEC Message and Frame Structure<\/strong><\/p>\n
- \n
- The Messages APIs allows application to encode high-level message constructs into CECFrame raw bytes, or decode CECFrame raw bytes into high-level message constructs.<\/li>\n<\/ul>\n
HDMI-CEC Library Interface<\/strong><\/p>\n
- \n
- The Library APIs allows application to contrl how the CEC stack operates, such as adding logical address to the stack.<\/li>\n<\/ul>\n
![](\"\/wp-content\/uploads\/sites\/16\/2023\/09\/Components%20of%20CEC%20Library.drawio.png\")
<\/p>\nThe Host <\/strong>interface allows libCEC implementation to interact with the host environment. Such interaction includes monitoring of the Power State change, the HDMI HotPlug events, or API to change the Host State. The Host Interface is delivered as a run-time plugin to the libCEC stack. This allows the CEC stack to run in any devices that implements the Host Interface.<\/p>\n
The Driver<\/strong> Component access the HDMI-CEC SoC Driver via the CEC HAL API. The vendors are responsible in delivering a SoC Driver that conforms to the HAL API (see the header file hdmi_cec_driver.h)<\/p>\n\n\n
HDMI-CEC Applications<\/h2>\n\n\n
The relation between Application, Connection and CEC-Bus is described in the figure.<\/p>\n<\/p>\n
![](\"\/wp-content\/uploads\/sites\/16\/2023\/09\/Application-1.drawio.png\")
<\/p>\nCEC Daemon<\/strong><\/p>\n
- \n
- This daemon receives Raw Bytes from the SoC Driver and dispatches them into IARM Bus via CecIARMMgr, it also receives Raw Bytes from IARM Bus and send to the SoC Driver. It controls the only access point to the physical HDMI CEC Bus.<\/li>\n<\/ul>\n
Receiver<\/strong><\/p>\n
- \n
- This application receives Raw Bytes from IARM Bus and dispatch to Service Manager (which in turn may dispatch the bytes to Guide Application). It also receives Raw bytes from Service Manager and send to the IARM-Bus.<\/li>\n<\/ul>\n
CECDevMgr<\/strong><\/p>\n
- \n
- This application is a “sniffer” on the CEC Bus. It monitors all messages on the bus and construct a Device Map, which depicts the topology of all connected devices on the CEC Bus. Other applications can be developed similar to Receiver or CECDevMgr where the CEC Raw bytes (in form of CECFrame) are send\/receive to\/from IARM Bus. This pseudo CEC Driver implemented on IARM Bus is called CEC IARM Adapter in the diagram.<\/li>\n<\/ul>\n\n\n
HDMI CEC Messaging<\/h2>\n\n\n
The CECFrame<\/strong> is a byte buffer that provides access to raw CEC bytes. CECFrame is guaranteed to be a complete CEC Message that has the necessary data blocks:<\/p>\n
The Header<\/strong> Data block (The byte that contains the initiator and destination address)
The OpCode<\/strong> Data Block (The byte that contains the opcode).
The Operand<\/strong> Data Block.(The bytes that contains the operands).<\/p>\nIn most cases application need not access CECFrame<\/strong> directly, but manipulate the raw bytes through the Message API. The Message API allows the application to send or receive high-level CEC message construct instead of raw bytes. Basically for each CEC message (such as ActiveSource), there is a C++ class implementation representing it. Each message class provides necessary getter and setter methods to access the properties of each message.<\/p>\n
Asynchronous Vs. Synchronous<\/strong><\/p>\n
When messages converge on the logical buses, they are queued for sending opportunities on the physical bus. The waiting time for such send to complete, though short in most cases, can be problematic to some interactive real-time applications. It is recommended that the applications always send CEC messages asynchronously via the <\/span>Connection<\/strong> API and use the listener APIs to monitor response messages or device state changes. The CEC library offers abundant APIs to facilitate such asynchronous implementation and the application is encouraged to make full use of them. <\/span><\/p>\n
Given the vast variance of HDMI-CEC support from the off-the-self media devices, it is not recommended that application wait for the response from a destination device. Even if the request message is sent out successfully, the destination device may choose to ignore the request. The recommended approach is again to send the request asynchronously and use the listener to monitor responses. <\/span><\/p>\n
Overall, given the asynchronous nature of HDMI-CEC, application should always opt to use Asynchronous APIs as first choice. And for same reasons, the RDK CEC library offers only limited support for Synchronous APIs.<\/span><\/p>\n\n\n
Multiple Application Support<\/h2>\n\n\n
Often , the application functionality (Record, Tune and Playback) is distributed across multiple components. In order for any component to have equivalent access to the HDMI-CEC bus, the library offers Multi-App support via IARM-Bus. This support is enabled by default, and can be disabled if desired.<\/p>\n
In essence, there is only one physical CEC bus on a system. However, with the help of Connection, Logical CEC-Bus, and IARM-Bus, the CEC library can converge the CEC traffic from different Connections and Logical Buses before forwarding them to the single physical bus. This is illustrated by the diagram below.<\/p>\n<\/p>\n
![](\"\/wp-content\/uploads\/sites\/16\/2023\/09\/multi-Application.drawio.png\")
<\/p>\nIn this diagram there are two applications (Receiver and CECDevMgr). Since both applications can only access the underlying physical CEC Bus via Connection API, they have no knowledge how the message are eventually delivered to the Physical Bus.<\/p>\n
For both applications, its CEC messages flows from,<\/p>\n
Connection –> Logical Bus–> CEC IARM Apaper–> IARM Bus—> (CECDaemonMain)<\/p>\n
For CECDaemonMain, its CEC messages flows from,<\/p>\n
IARM Bus –> CecIARMMgr –> Connection –> Logical Bus –> CEC Driver –> (Physical Bus)<\/p>\n
The message flow on Connections and Logical Buses are full duplex.<\/p>\n\n\n
Methods & Events<\/h2>\n\n\n
Following methods are used for DMI CEC module.<\/p>\n
\n\n\n<\/colgroup> Name<\/th> Parameters<\/th> Description<\/th><\/tr> setEnabled<\/td> enabled : boolean<\/td> Enables or disables CEC<\/td><\/tr> getEnabled<\/td> none<\/td> Returns true if CEC is enabled<\/td><\/tr> setName<\/td> name : string<\/td> Sets the name of the STB device. The default name is “STB”. It is recommended that the name of the device is set prior to enabling CEC.<\/td><\/tr> getName<\/td> none<\/td> Returns the name of the STB device<\/td><\/tr> sendMessage<\/td> message : String<\/p><\/td>
The message is a base64 encoded byte array of the raw CEC bytes. The CEC message includes the device ID for the intended destination.<\/p><\/td><\/tr>
getCECAddresses<\/td> none<\/td> return the JSON object <CECAddresses<\/em>> that is assigned to the local device. It does not contain the <CECAddresses> of other devices on the connected CEC network.<\/p><\/td><\/tr>
\"CECAddresses\" : {
\"physicalAddress\": Array of 4 bytes [byte0, byte1, byte2, byte3],
\"logicalAddresses\" : Array of <CECLogicalAddress>
}<\/pre>\"CECLogicalAddress\" : {
\"deviceType\" : <string>
\"logicalAddress\": <integer>
}<\/pre>The deviceType<\/em> returned is part or all of devices types optionally set by XRE.<\/p>
A CEC device can have multiple deviceTypes, if so an array of <CECLogicalAddress> with size more than one is returned.<\/span><\/p>
Default deviceType<\/em> is Tuner, and its logical Address is either 3, 6, 7, or 10.<\/p>
In messages sent by XRE, XRE can only use the logicalAddress returned from CECAddresses<\/em>.<\/p>
Accepted deviceType<\/em> are: “Tuner”, “Record”, “Playback”, “AudioSystem”, “VideoProcessor”, “Switch”<\/p><\/td><\/tr><\/tbody><\/table>\n\n\n<\/div>\n
Events notification:<\/strong><\/p>\n
- This application is a “sniffer” on the CEC Bus. It monitors all messages on the bus and construct a Device Map, which depicts the topology of all connected devices on the CEC Bus. Other applications can be developed similar to Receiver or CECDevMgr where the CEC Raw bytes (in form of CECFrame) are send\/receive to\/from IARM Bus. This pseudo CEC Driver implemented on IARM Bus is called CEC IARM Adapter in the diagram.<\/li>\n<\/ul>\n\n\n
- This application receives Raw Bytes from IARM Bus and dispatch to Service Manager (which in turn may dispatch the bytes to Guide Application). It also receives Raw bytes from Service Manager and send to the IARM-Bus.<\/li>\n<\/ul>\n
- This daemon receives Raw Bytes from the SoC Driver and dispatches them into IARM Bus via CecIARMMgr, it also receives Raw Bytes from IARM Bus and send to the SoC Driver. It controls the only access point to the physical HDMI CEC Bus.<\/li>\n<\/ul>\n
- The Library APIs allows application to contrl how the CEC stack operates, such as adding logical address to the stack.<\/li>\n<\/ul>\n
- The Messages APIs allows application to encode high-level message constructs into CECFrame raw bytes, or decode CECFrame raw bytes into high-level message constructs.<\/li>\n<\/ul>\n
- \n
- \n