1.. SPDX-License-Identifier: GPL-2.0
2
3========
4HDMI CEC
5========
6
7Supported hardware in mainline
8==============================
9
10HDMI Transmitters:
11
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
30
31
32HDMI Receivers:
33
34- adv7604/11/12
35- adv7842
36- tc358743
37
38USB Dongles (see below for additional information on how to use these
39dongles):
40
41- Pulse-Eight: the pulse8-cec driver implements the following module option:
42  ``persistent_config``: by default this is off, but when set to 1 the driver
43  will store the current settings to the device's internal eeprom and restore
44  it the next time the device is connected to the USB port.
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 :-)
48
49Miscellaneous:
50
51- vivid: emulates a CEC receiver and CEC transmitter.
52  Can be used to test CEC applications without actual CEC hardware.
53
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
56  injection as well.
57
58
59Utilities
60=========
61
62Utilities are available here: https://git.linuxtv.org/v4l-utils.git
63
64``utils/cec-ctl``: control a CEC device
65
66``utils/cec-compliance``: test compliance of a remote CEC device
67
68``utils/cec-follower``: emulate a CEC follower device
69
70Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is
71used in some hotel displays. See http://www.htng.org.
72
73Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports
74the linux CEC framework.
75
76If you want to get the CEC specification, then look at the References of
77the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part
78of the HDMI specification. HDMI 1.3 is freely available (very similar to
79HDMI 1.4 w.r.t. CEC) and should be good enough for most things.
80
81
82DisplayPort to HDMI Adapters with working CEC
83=============================================
84
85Background: most adapters do not support the CEC Tunneling feature,
86and of those that do many did not actually connect the CEC pin.
87Unfortunately, this means that while a CEC device is created, it
88is actually all alone in the world and will never be able to see other
89CEC devices.
90
91This is a list of known working adapters that have CEC Tunneling AND
92that properly connected the CEC pin. If you find adapters that work
93but are not in this list, then drop me a note.
94
95To test: hook up your DP-to-HDMI adapter to a CEC capable device
96(typically a TV), then run::
97
98	cec-ctl --playback	# Configure the PC as a CEC Playback device
99	cec-ctl -S		# Show the CEC topology
100
101The ``cec-ctl -S`` command should show at least two CEC devices,
102ourselves and the CEC device you are connected to (i.e. typically the TV).
103
104General note: I have only seen this work with the Parade PS175, PS176 and
105PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support,
106I have never seen it work.
107
108USB-C to HDMI
109-------------
110
111Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/
112
113Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF
114
115Club3D CAC-2504: https://www.club-3d.com/en/detail/2449/usb_3.1_type_c_to_hdmi_2.0_uhd_4k_60hz_active_adapter/
116
117DisplayPort to HDMI
118-------------------
119
120Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/
121
122CableCreation (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr
123
124HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayport-to-hdmi-true-4k-adapter
125
126Mini-DisplayPort to HDMI
127------------------------
128
129Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/
130
131Note that passive adapters will never work, you need an active adapter.
132
133The Club3D adapters in this list are all MegaChips 2900 based. Other Club3D adapters
134are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D
135adapters above are known to work.
136
137I suspect that MegaChips 2900 based designs in general are likely to work
138whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is
139likely to have the CEC pin hooked up, it looks like they changed the reference
140design for that chipset.
141
142
143USB CEC Dongles
144===============
145
146These dongles appear as ``/dev/ttyACMX`` devices and need the ``inputattach``
147utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight
148has been added to ``inputattach`` 1.6.0. Support for the Rainshadow Tech has
149been added to ``inputattach`` 1.6.1.
150
151You also need udev rules to automatically start systemd services::
152
153	SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service"
154	SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service"
155	SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="rainshadow-cec-inputattach@%k.service"
156
157and these systemd services:
158
159For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service::
160
161	[Unit]
162	Description=inputattach for pulse8-cec device on %I
163
164	[Service]
165	Type=simple
166	ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I
167
168For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service::
169
170	[Unit]
171	Description=inputattach for rainshadow-cec device on %I
172
173	[Service]
174	Type=simple
175	ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I
176
177
178For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service::
179
180	[Unit]
181	Description=restart inputattach for cec devices
182	After=suspend.target
183
184	[Service]
185	Type=forking
186	ExecStart=/bin/bash -c 'for d in /dev/serial/by-id/usb-Pulse-Eight*; do /usr/bin/inputattach --daemon --pulse8-cec $d; done; for d in /dev/serial/by-id/usb-RainShadow_Tech*; do /usr/bin/inputattach --daemon --rainshadow-cec $d; done'
187
188	[Install]
189	WantedBy=suspend.target
190
191And run ``systemctl enable restart-cec-inputattach``.
192
193To automatically set the physical address of the CEC device whenever the
194EDID changes, you can use ``cec-ctl`` with the ``-E`` option::
195
196	cec-ctl -E /sys/class/drm/card0-DP-1/edid
197
198This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell
199you which output is used) and it will poll for changes to the EDID and update
200the Physical Address whenever they occur.
201
202To automatically run this command you can use cron. Edit crontab with
203``crontab -e`` and add this line::
204
205	@reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid
206
207This only works for display drivers that expose the EDID in ``/sys/class/drm``,
208such as the i915 driver.
209
210
211CEC Without HPD
212===============
213
214Some displays when in standby mode have no HDMI Hotplug Detect signal, but
215CEC is still enabled so connected devices can send an <Image View On> CEC
216message in order to wake up such displays. Unfortunately, not all CEC
217adapters can support this. An example is the Odroid-U3 SBC that has a
218level-shifter that is powered off when the HPD signal is low, thus
219blocking the CEC pin. Even though the SoC can use CEC without a HPD,
220the level-shifter will prevent this from functioning.
221
222There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``.
223If set, then the hardware cannot wake up displays with this behavior.
224
225Note for CEC application implementers: the <Image View On> message must
226be the first message you send, don't send any other messages before.
227Certain very bad but unfortunately not uncommon CEC implementations
228get very confused if they receive anything else but this message and
229they won't wake up.
230
231When writing a driver it can be tricky to test this. There are two
232ways to do this:
233
2341) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your
235   device to the Pulse-Eight, but do not connect the Pulse-Eight to
236   the display.
237
238   Now configure the Pulse-Eight dongle::
239
240	cec-ctl -p0.0.0.0 --tv
241
242   and start monitoring::
243
244	sudo cec-ctl -M
245
246   On the device you are testing run::
247
248	cec-ctl --playback
249
250   It should report a physical address of f.f.f.f. Now run this
251   command::
252
253	cec-ctl -t0 --image-view-on
254
255   The Pulse-Eight should see the <Image View On> message. If not,
256   then something (hardware and/or software) is preventing the CEC
257   message from going out.
258
259   To make sure you have the wiring correct just connect the
260   Pulse-Eight to a CEC-enabled display and run the same command
261   on your device: now there is a HPD, so you should see the command
262   arriving at the Pulse-Eight.
263
2642) If you have another linux device supporting CEC without HPD, then
265   you can just connect your device to that device. Yes, you can connect
266   two HDMI outputs together. You won't have a HPD (which is what we
267   want for this test), but the second device can monitor the CEC pin.
268
269   Otherwise use the same commands as in 1.
270
271If CEC messages do not come through when there is no HPD, then you
272need to figure out why. Typically it is either a hardware restriction
273or the software powers off the CEC core when the HPD goes low. The
274first cannot be corrected of course, the second will likely required
275driver changes.
276
277
278Microcontrollers & CEC
279======================
280
281We have seen some CEC implementations in displays that use a microcontroller
282to sample the bus. This does not have to be a problem, but some implementations
283have timing issues. This is hard to discover unless you can hook up a low-level
284CEC debugger (see the next section).
285
286You will see cases where the CEC transmitter holds the CEC line high or low for
287a longer time than is allowed. For directed messages this is not a problem since
288if that happens the message will not be Acked and it will be retransmitted.
289For broadcast messages no such mechanism exists.
290
291It's not clear what to do about this. It is probably wise to transmit some
292broadcast messages twice to reduce the chance of them being lost. Specifically
293<Standby> and <Active Source> are candidates for that.
294
295
296Making a CEC debugger
297=====================
298
299By using a Raspberry Pi 2B/3/4 and some cheap components you can make
300your own low-level CEC debugger.
301
302Here is a picture of my setup:
303
304https://hverkuil.home.xs4all.nl/rpi3-cec.jpg
305
306It's a Raspberry Pi 3 together with a breadboard and some breadboard wires:
307
308http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-356089#.WYLOOXWGN7I
309
310Finally on of these HDMI female-female passthrough connectors (full soldering type 1):
311
312https://elabbay.myshopify.com/collections/camera/products/hdmi-af-af-v1a-hdmi-type-a-female-to-hdmi-type-a-female-pass-through-adapter-breakout-board?variant=45533926147
313
314We've tested this and it works up to 4kp30 (297 MHz). The quality is not high
315enough to pass-through 4kp60 (594 MHz).
316
317I also added an RTC and a breakout shield:
318
319https://www.amazon.com/Makerfire%C2%AE-Raspberry-Module-DS1307-Battery/dp/B00ZOXWHK4
320
321https://www.dx.com/p/raspberry-pi-gpio-expansion-board-breadboard-easy-multiplexing-board-one-to-three-with-screw-for-raspberry-pi-2-3-b-b-2729992.html#.YGRCG0MzZ7I
322
323These two are not needed but they make life a bit easier.
324
325If you want to monitor the HPD line as well, then you need one of these
326level shifters:
327
328https://www.adafruit.com/product/757
329
330(This is just where I got these components, there are many other places you
331can get similar things).
332
333The CEC pin of the HDMI connector needs to be connected to these pins:
334CE0/IO8 and CE1/IO7 (pull-up GPIOs). The (optional) HPD pin of the HDMI
335connector should be connected (via a level shifter to convert the 5V
336to 3.3V) to these pins: IO17 and IO27. The (optional) 5V pin of the HDMI
337connector should be connected (via a level shifter) to these pins: IO22
338and IO24. Monitoring the HPD an 5V lines is not necessary, but it is helpful.
339
340This kernel patch will hook up the cec-gpio driver correctly to
341e.g. ``arch/arm/boot/dts/bcm2837-rpi-3-b-plus.dts``::
342
343	cec-gpio@7 {
344		compatible = "cec-gpio";
345		cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
346		hpd-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>;
347		v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
348	};
349
350	cec-gpio@8 {
351		compatible = "cec-gpio";
352		cec-gpios = <&gpio 8 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
353		hpd-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
354		v5-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>;
355	};
356
357This dts change will enable two cec GPIO devices: I typically use one to
358send/receive CEC commands and the other to monitor. If you monitor using
359an unconfigured CEC adapter then it will use GPIO interrupts which makes
360monitoring very accurate.
361
362The documentation on how to use the error injection is here: :ref:`cec_pin_error_inj`.
363
364``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis.
365You can also store the CEC traffic to file using ``--store-pin`` and analyze
366it later using ``--analyze-pin``.
367
368You can also use this as a full-fledged CEC device by configuring it
369using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``.
370