admin-guide/media/cec.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 HDMI CEC
10 HDMI Transmitters:
12 - Exynos4
13 - Exynos5
14 - STIH4xx HDMI CEC
15 - V4L2 adv7511 (same HW, but a different driver from the drm adv7511)
16 - stm32
17 - Allwinner A10 (sun4i)
18 - Raspberry Pi
19 - dw-hdmi (Synopsis IP)
20 - amlogic (meson ao-cec and ao-cec-g12a)
21 - drm adv7511/adv7533
22 - omap4
23 - tegra
24 - rk3288, rk3399
25 - tda998x
26 - DisplayPort CEC-Tunneling-over-AUX on i915, nouveau and amdgpu
27 - ChromeOS EC CEC
28 - CEC for SECO boards (UDOO x86).
29 - Chrontel CH7322
32 HDMI Receivers:
34 - adv7604/11/12
35 - adv7842
36 - tc358743
41 - Pulse-Eight: the pulse8-cec driver implements the following module option:
45 - RainShadow Tech. Note: this driver does not support the persistent_config
46   module option of the Pulse-Eight driver. The hardware supports it, but I
47   have no plans to add this feature. But I accept patches :-)
51 - vivid: emulates a CEC receiver and CEC transmitter.
52   Can be used to test CEC applications without actual CEC hardware.
54 - cec-gpio. If the CEC pin is hooked up to a GPIO pin then
55   you can control the CEC line through this driver. This supports error
58 - cec-gpio and Allwinner A10 (or any other driver that uses the CEC pin
59   framework to drive the CEC pin directly): the CEC pin framework uses
60   high-resolution timers. These timers are affected by NTP daemons that
63   1/12th. This will cause the CEC timings to go out of spec. To fix this,
65   frequency change to 1/25th, which keeps the CEC timings within spec.
71 Utilities are available here: https://git.linuxtv.org/v4l-utils.git
73 ``utils/cec-ctl``: control a CEC device
75 ``utils/cec-compliance``: test compliance of a remote CEC device
77 ``utils/cec-follower``: emulate a CEC follower device
79 Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is
82 Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports
83 the linux CEC framework.
85 If you want to get the CEC specification, then look at the References of
86 the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part
87 of the HDMI specification. HDMI 1.3 is freely available (very similar to
88 HDMI 1.4 w.r.t. CEC) and should be good enough for most things.
91 DisplayPort to HDMI Adapters with working CEC
94 Background: most adapters do not support the CEC Tunneling feature,
95 and of those that do many did not actually connect the CEC pin.
96 Unfortunately, this means that while a CEC device is created, it
98 CEC devices.
100 This is a list of known working adapters that have CEC Tunneling AND
101 that properly connected the CEC pin. If you find adapters that work
104 To test: hook up your DP-to-HDMI adapter to a CEC capable device
107 	cec-ctl --playback	# Configure the PC as a CEC Playback device
108 	cec-ctl -S		# Show the CEC topology
110 The ``cec-ctl -S`` command should show at least two CEC devices,
111 ourselves and the CEC device you are connected to (i.e. typically the TV).
114 PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support,
117 USB-C to HDMI
118 -------------
120 Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/
122 Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF
124 Club3D CAC-2504: https://www.club-3d.com/en/detail/2449/usb_3.1_type_c_to_hdmi_2.0_uhd_4k_60hz_acti…
126 DisplayPort to HDMI
127 -------------------
129 Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/
131 …ion (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr
133 HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayp…
135 Mini-DisplayPort to HDMI
136 ------------------------
138 Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/
143 are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D
147 whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is
148 likely to have the CEC pin hooked up, it looks like they changed the reference
152 USB CEC Dongles
156 utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight
162 …ERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="sys…
163 …ERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="sys…
164 …NEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="syste…
168 For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service::
171 	Description=inputattach for pulse8-cec device on %I
175 	ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I
177 For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service::
180 	Description=inputattach for rainshadow-cec device on %I
184 	ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I
187 For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service::
190 	Description=restart inputattach for cec devices
195 …-c 'for d in /dev/serial/by-id/usb-Pulse-Eight*; do /usr/bin/inputattach --daemon --pulse8-cec $d;…
200 And run ``systemctl enable restart-cec-inputattach``.
202 To automatically set the physical address of the CEC device whenever the
203 EDID changes, you can use ``cec-ctl`` with the ``-E`` option::
205 	cec-ctl -E /sys/class/drm/card0-DP-1/edid
207 This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell
212 ``crontab -e`` and add this line::
214 	@reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid
220 CEC Without HPD
223 Some displays when in standby mode have no HDMI Hotplug Detect signal, but
224 CEC is still enabled so connected devices can send an <Image View On> CEC
225 message in order to wake up such displays. Unfortunately, not all CEC
226 adapters can support this. An example is the Odroid-U3 SBC that has a
227 level-shifter that is powered off when the HPD signal is low, thus
228 blocking the CEC pin. Even though the SoC can use CEC without a HPD,
229 the level-shifter will prevent this from functioning.
231 There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``.
234 Note for CEC application implementers: the <Image View On> message must
236 Certain very bad but unfortunately not uncommon CEC implementations
243 1) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your
244    device to the Pulse-Eight, but do not connect the Pulse-Eight to
247    Now configure the Pulse-Eight dongle::
249 	cec-ctl -p0.0.0.0 --tv
253 	sudo cec-ctl -M
257 	cec-ctl --playback
262 	cec-ctl -t0 --image-view-on
264    The Pulse-Eight should see the <Image View On> message. If not,
265    then something (hardware and/or software) is preventing the CEC
269    Pulse-Eight to a CEC-enabled display and run the same command
271    arriving at the Pulse-Eight.
273 2) If you have another linux device supporting CEC without HPD, then
275    two HDMI outputs together. You won't have a HPD (which is what we
276    want for this test), but the second device can monitor the CEC pin.
280 If CEC messages do not come through when there is no HPD, then you
282 or the software powers off the CEC core when the HPD goes low. The
287 Microcontrollers & CEC
290 We have seen some CEC implementations in displays that use a microcontroller
292 have timing issues. This is hard to discover unless you can hook up a low-level
293 CEC debugger (see the next section).
295 You will see cases where the CEC transmitter holds the CEC line high or low for
305 Making a CEC debugger
309 your own low-level CEC debugger.
311 The critical component is one of these HDMI female-female passthrough connectors
314 ….com/collections/camera/products/hdmi-af-af-v1a-hdmi-type-a-female-to-hdmi-type-a-female-pass-thro…
316 The video quality is variable and certainly not enough to pass-through 4kp60
318 be limited to 1080p60 (148.5 MHz). But for CEC testing that is fine.
322 http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-3560…
332 The ground pin of the HDMI connector needs to be connected to a ground
335 The CEC pin of the HDMI connector needs to be connected to these pins:
336 GPIO 6 and GPIO 7. The optional HPD pin of the HDMI connector should
338 The optional 5V pin of the HDMI connector should be connected via the
342 This device tree addition in ``arch/arm/boot/dts/bcm2711-rpi-4-b.dts``
343 will hook up the cec-gpio driver correctly::
345 	cec@6 {
346 		compatible = "cec-gpio";
347 		cec-gpios = <&gpio 6 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
348 		hpd-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>;
349 		v5-gpios = <&gpio 25 GPIO_ACTIVE_HIGH>;
352 	cec@7 {
353 		compatible = "cec-gpio";
354 		cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
355 		hpd-gpios = <&gpio 12 GPIO_ACTIVE_HIGH>;
356 		v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
362 This dts change will enable two cec GPIO devices: I typically use one to
363 send/receive CEC commands and the other to monitor. If you monitor using
364 an unconfigured CEC adapter then it will use GPIO interrupts which makes
368 The minimum configuration is one HDMI female-female passthrough connector
369 and two female-female breadboard wires: one for connecting the HDMI ground
370 pin to a ground pin on the Raspberry Pi, and the other to connect the HDMI
371 CEC pin to GPIO 6 on the Raspberry Pi.
375 ``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis.
376 You can also store the CEC traffic to file using ``--store-pin`` and analyze
377 it later using ``--analyze-pin``.
379 You can also use this as a full-fledged CEC device by configuring it
380 using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``.