HDMI-CEC - ArchWiki

Jump to content
From ArchWiki

HDMI-CEC (Consumer Electronics Control) is a low-speed (50 bytes per second) bus on the HDMI connector that a "network" of HDMI devices can use to communicate with each other. It mainly allows HDMI devices to notify each other that they should be turning on or off, that the TV has switched input or that a remote control button is being pressed, among other things. On PC, it would be mostly useful with an HTPC (home-theater PC) configuration.

For a variety of reasons, almost no PC GPU has hardware support for CEC. Video game consoles and set-top boxes usually have to include an external chipset to drive the CEC pin. While there are devices with native CEC support (such as the VideoCore GPU found on a Raspberry Pi), most hardware configurations would need a USB CEC adapter to be able to work.

Note: If you are looking to use HDMI-CEC with Kodi, know that it has built-in support for both Pulse-Eight and Raspberry Pi modes of CEC control and is incompatible with the following configuration.

## Features

The main purpose of CEC is to grant a television insight and control over the state of the devices plugged into it. As such, it is split into a dozen of "features" that each target specific use cases, and which devices can opt to support or not based on their role as initiator/follower, their capabilities, as well as user configuration.

The standardized features are:

One Touch Play
  Lets a device signal that it wishes to immediately become the active source, which can automatically turn on the TV
Routing Control
  Allows the TV to control HDMI switches and lets devices check what source is currently active
Remote Control Passthrough
  Lets devices send remote control signals to each other, usually from the TV to the active source
Deck Control
  To control a movie/music player and query its playback status
Standby/System Standby
  Lets a device request that another specific device be turned off, or broadcast that all devices on the system should now turn off.
Power Status
  Lets devices be probed to see if they are in standby mode or turned on, or if they are in the process of turning on.
System Audio Control
  Grants control of an AV receiver connected over the TV's Audio Return Channel, allowing the volume to be changed and the receiver to be turned on or off.
Tuner Control
  Lets any device step through the list of TV channels known to a tuner device and query information on the active channel, like the channel number for analog TV or DVB/ATSC/ARIB transport stream information for digital TV
One Touch Record
  Enables a recorder to query what channel the TV is currently showing so that said recorder can tune to the same channel and begin recording, or know that it should record itself or a downstream device if it already is the currently active HDMI source
Timer Programming
  Allows a TV to configure a timer on a recorder to start recording a given source at a specific time
OSD display
  Allows a device to print a message on the TV, between 1 and 13 ASCII characters long
Dynamic Auto Lipsync
  Allows a TV to broadcast changes in presentation latency to the the audio sink, which a source that has its own speakers (like a PC) can use for latency compensation with the image

Tip: Not listed: Device Menu Control (deprecated in CEC 2.0), OSD name transfer (handled by cec-ctl), System information, Vendor-specific command (no standardized messages), Audio Rate Control (TV-AV only), Audio Return Channel Control (TV-AV only)

For a device like a PC, the most useful one among these is going to be Remote Control Passthrough. System Standby may be useful for HTPCs, but would be of questionable use on more general-purpose machines, which are not usually expected to go to sleep when the screen turns off. Routing Control could be used to wake up the system when the the TV attempts to display that input, provided the connected PC has a way to listen to CEC traffic while suspended. System Audio Control would be convenient for some HDMI sound outputs, but does not currently work as a mean of volume control with either PipeWire or PulseAudio.

## CEC hardware setup

The Linux Kernel already has a built-in subsystem to automatically respond to queries and handle CEC events, but the hardware may need to be configured first in order to work.

### Native CEC

This article or section needs expansion.

Reason: Someone with qualifying hardware should write this, if there even is anything to be done. (Discuss in Talk:HDMI-CEC)

### CEC adapter

#### PulseEight USB adapter

The PulseEight USB-CEC adapter works by passively extending all the pins of the HDMI connector on from the "PC side" connector to the "TV side" connector, save for the CEC pin, which is intercepted. The data going through that pin is instead exposed over a USB serial interface to let a PC control and monitor CEC traffic. The serial device needs to have its line discipline (a flag to signal to the kernel that a TTY is of a specific known type and requires a driver to work) configured manually before the kernel takes over and acknowledges it as a CEC adapter. This cannot be done automatically due to limitations around serial device APIs, so it is currently best achieved with a udev rule paired with a systemd unit (as udev rules cannot launch long-running or forking processes) to run `inputattach --pulse8-cec ...` when the device is plugged.

This serial interface appears as device node `/dev/ttyACMX`, and the inputattach utility is needed to set the line discipline and let the kernel drivers take over to create the `/dev/cecX` device that will be needed later. This requires the linuxconsole package.

Note: Do not modify `@$devnode` in the following rule, it is a udev string substitution.

    /etc/udev/rules.d/pulse8-cec-autoattach.rules

    SUBSYSTEM=="tty" ACTION=="add" ATTRS{manufacturer}=="Pulse-Eight" ATTRS{product}=="CEC Adapter" TAG+="systemd" ENV{SYSTEMD_WANTS}="pulse8-cec-attach@$devnode.service"

    /etc/systemd/system/pulse8-cec-attach@.service

    [Unit]
    # Should be called as "pulse8-cec-attach@-dev-ttyACM0.service" or similar
    Description=Configure USB Pulse-Eight serial device at %I
    ConditionPathExists=%I

    [Service]
    Type=forking
    # inputattach is built without systemd daemon support by default, so systemd will have to guess the PID.
    # https://sourceforge.net/p/linuxconsole/code/ci/a3366c0d5f82485e6aae7b005ec7a2d9a93bf458/tree/utils/inputattach.c#l1233

    ExecStart=/usr/bin/inputattach --daemon --pulse8-cec %I

However, USB device connections are usually reset when the system wakes up from sleep (a step known as reset-resume) , meaning the serial connection will be lost if the computer is ever suspended, on top of serial connections usually hanging up on resume anyway. This means the above rule has to be triggered again somehow.

Unfortunately, the `cdc_acm` driver in charge of the `ttyACM*` object that the above rule reacts to does not raise any uevent about the connection being reset and the line discipline being lost, and the rule cannot be hooked on the USB device directly. Instead, the most reliable way to get the used rule above to trigger again at the right time is to delete and recreate the `ttyACM*` object by forcing the USB device to be reconfigured when it resets. In order to react to this and ensure the the connection is reopened, udev can keep track of when the USB device is reset and enumerated, as evidenced by the `DEVNUM` property being zeroed and later restored, and touching the `bConfigurationValue` sysfs attribute.

    /etc/udev/rules.d/pulse8-cec-autoattach.rules

    SUBSYSTEM=="tty" ACTION=="add" ATTRS{manufacturer}=="Pulse-Eight" ATTRS{product}=="CEC Adapter" TAG+="systemd" ENV{SYSTEMD_WANTS}="pulse8-cec-attach@$devnode.service"

    # Force device to be reconfigured when reset after suspend, otherwise the ttyACM link is lost but udev will not notice.
    # A usb_dev_uevent with DEVNUM=000 is a sign that the device is being reset before enumeration.
    # Re-configuring causes ttyACM to be removed and re-added instead.
    SUBSYSTEM=="usb" ACTION=="change" ATTR{manufacturer}=="Pulse-Eight" ATTR{product}=="CEC Adapter" ENV{DEVNUM}=="000" ATTR{bConfigurationValue}=="1" ATTR{bConfigurationValue}="1"

This essentially acts as if the USB adapter had been unplugged and re-plugged immediately upon coming out of sleep, ensuring the `SUBSYSTEM=="tty" ACTION=="add"` rule from before gets to run again. This ensures that the systemd service will be restarted as soon as the device is back to a usable state.

### Tunneling over DisplayPort

This article or section needs expansion.

Reason: Someone with qualifying hardware should write this. (Discuss in Talk:HDMI-CEC)

The DisplayPort 1.3 standard allows DisplayPort-to-HDMI adapters to use the auxiliary channel to forward CEC signals. This is the sort of feature that adapters do not usually support unless mentioned, and is not commonly found, but it can counter-intuitively be cheaper and easier to use CEC tunneling over DisplayPort than to work with a CEC adapter. The kernel documentation page for the CEC submodule has a list of such adapters which have been confirmed to work.

## CEC subsystem configuration

Now that the CEC subsystem has something to bind on and that `/dev/cec0` has been created, it is now possible to configure the PC so other CEC devices know about it. When using the command-line, CEC devices are normally controlled via `cec-ctl`, which is part of v4l-utils.

One thing to be aware of is that the CEC pin alone does not have enough information on its own to send a valid CEC message. A CEC adapter that only monitors pin 13 (CEC) cannot know its "physical address" (its position in terms of port numbers in the "tree" of HDMI devices, such as `3.1.0.0`), which it needs to be aware of in order to complete the logical address allocation procedure. Without a logical address, a device can only receive and send broadcast messages. The physical address is communicated over pin 16 (DDC/EDID), so configuring the CEC subsystem includes specifying which display output port is supposed to be associated with with that CEC object, in order for the physical address to be extracted from the display's EDID.

One way to find the name of the active connectors is to use `xrandr --query` (which also works on Wayland):

    $ xrandr --query

    Screen 0: minimum 16 x 16, current 3840 x 2160, maximum 32767 x 32767
    DP-1 connected primary 3840x2160+0+0 (normal left inverted right x axis y axis) 600mm x 340mm
       3840x2160     59.98*+
       2048x1536     59.95
       ...
    HDMI-A-1 connected 3840x2160+0+0 (normal left inverted right x axis y axis) 1440mm x 810mm
       3840x2160     59.98*+
       2048x1536     59.95
       ...

Once the correct port has been identified (for example `HDMI-A-1`), then the sysfs port name can be found by using `ls -1d /sys/class/drm/card*-HDMI-A-1` (such as `card1-HDMI-A-1`). In this case, the corresponding display's EDID data would be kept at `/sys/class/drm/card1-HDMI-A-1/edid`.

Given how CEC configuration must be performed every time the `cec` device node is re-created, this is best handled with another udev rule that fires when the `cec` object appears.

Note: Be sure to replace `card1-HDMI-A-1` in the following rule by your connector name.

    /etc/udev/rules.d/cec-configure-autostart.rules

    SUBSYSTEM=="cec" KERNEL=="cec0" ACTION=="add" TAG+="systemd" ENV{SYSTEMD_WANTS}="cec0-configure@card1-HDMI-A-1.service"

    /etc/systemd/system/cec0-configure@.service

    [Unit]
    # Should be called as "cec0-configure@card1-HDMI-A-1.service" or similar
    Description=Configure CEC adapter cec0 assuming it runs on output %i
    AssertPathExists=/sys/class/drm/%i/edid
    BindsTo=dev-cec0.device

    [Service]
    Type=exec
    # --phys-addr-from-edid-poll checks EDID every tenth of a second
    # https://git.linuxtv.org/v4l-utils.git/tree/utils/cec-ctl/cec-ctl.cpp?id=0a195181d771090f3c99d4a6ddb8151352509061#n1977
    # Use `Type=oneshot` if using `--phys-addr-from-edid` instead
    ExecStart=/usr/bin/cec-ctl --device=0 "--osd-name=%H" --playback "--phys-addr-from-edid-poll=/sys/class/drm/%i/edid"

There are three device classes that an HDMI source can try to advertise itself as, which are "Recording device" (3 max), "Tuner" (4 max) and "Playback device" (3 max). This is important because HDMI devices do not use their physical address when communicating with each other over CEC, but a 4 bit "logical address", which identify devices as "Tuner #3" or "Playback Device #1", with a finite number of each. If address allocation fails because too many devices of one type are present, it may be assigned the "Backup" (2 max) role instead. These roles are intended to relate to the CEC features mentioned earlier, namely:

- "Tuner" is supposed to support "Tuner Control"
- "Recording device" is the only type that can use One Touch Record, as TVs are supposed to ignore related messages coming from other addresses
- "Playback device" is for general purpose video sources. Computers, like video game consoles, are considered "Playback devices".

The above `cec0-configure@.service` unit uses `--playback` to configure a Playback device. It is, however, generally OK to set the device class to Tuner (`--tuner`) or Recorder (`--record`), whether because there are no more unused playback addresses, or simply to have the PC stand out in the list on TVs that visually set apart each device class in their input menus.

## See also

- HDMI CEC: What? Why? How?, by Hans Verkuil, who wrote most of the CEC subsystem
- CEC-O-Matic, which allows to create raw CEC messages and gives an overview of what makes up a valid CEC frame
- The documentation for the CEC subsystem

Category:

- Hardware

Hidden category:

- Pages or sections flagged with Template:Expansion