CEC-CTL(1)

✨ CEC-CTL ✨

okay bestie, gather round, because this is the manual page for cec-ctl — that's the CEC-CTL(1) girlies, User Commands section, and she is long but she is iconic 💅

---

🎀 NAME 🎀

cec-ctl — an application to control cec devices. that's it. that's the job. she controls cec devices 💖

---

🌸 SYNOPSIS 🌸

cec-ctl [-h] [-d <dev>] [many other options]

yes, "many other options" is literally what the page says, and honestly? she's not wrong, we're about to get into all of them 🫶

---

🦋 DESCRIPTION 🦋

so the tea is: the cec-ctl tool controls cec devices. and when we say controls, we mean she can mess with almost any aspect of them — like, she covers the full CEC API. full. entire. no crumbs. 😤

the easiest way to quickly test a CEC adapter of an HDMI output is:

cec-ctl -d/dev/cecX --playback -S

this is what you'd use if the HDMI output of your device supports CEC — because your device plays back video, so it's a CEC Playback device. makes sense, right? the device plays stuff back. playback. slay.

and for an HDMI input:

cec-ctl -d/dev/cecX --tv -S

this one's for when your device has an HDMI input, i.e. it acts like a TV. main character TV energy 👑

both commands configure the CEC adapter and show the CEC topology. important note bestie, don't skip this part: the --playback and --tv options configure your device — they are not about what device you will be talking to. it's giving "know thyself" 🪞

to put a display to standby use:

cec-ctl -d/dev/cecX --to 0 --standby

to wake up the display:

cec-ctl -d/dev/cecX --to 0 --image-view-on

to switch the TV to our HDMI output (and yeah, replace the physical address with what cec-ctl -d/dev/cecX reported):

cec-ctl -d/dev/cecX --to 0 --active-source phys-addr=1.0.0.0

and here's a lil shortcut for you 💅 instead of -d/dev/cecX you can also write this as -dX. and instead of --to 0 you can also write this as -t0. shorter, cuter, same energy.

---

🌈 OPTIONS 🌈

strap in. she's thorough. (as she should be.)

• -A, --list-devices — list all cec devices. window shopping, but for adapters 🛍️
• -d, --device <dev> — use device <dev> as the CEC device. if <dev> is a number, then /dev/cec<dev> is used. so like, -d0 secretly means /dev/cec0. sneaky. love that.
• -D, --driver <drv> — use a cec device that has driver name <drv>, as returned by the CEC_ADAP_G_CAPS ioctl. this option can be combined with -a to uniquely identify a CEC device without having to rely on the device node number. no node numbers needed, we're classy 💖
• -a, --adapter <adap-name> — use a cec device that has adapter name <adap-name>, as returned by the CEC_ADAP_G_CAPS ioctl. this option can be combined with -D to uniquely identify a CEC device without having to rely on the device node number. yeah, it's the partner-in-crime to -D. power couple 🫶
• -v, --verbose — turn on verbose reporting. she will talk. 💬
• --version — show version information.
• -w, --wall-clock — show timestamps as wall-clock time. this also turns on verbose reporting. two for one, we love a bundle ✨
• -h, --help — prints the help message. when in doubt, -h it out 🙈
• -p, --phys-addr <addr> — use this physical address. the address can be a number (e.g. 0 or 0x11b1) or formatted as a.b.c.d where each component is a hex value from 0-f (e.g. 0.0.0.0 or 1.1.b.1). two formats, one icon 💅
• -e, --phys-addr-from-edid <path> — parse the given EDID file (in raw binary format) and extract the physical address. if the EDID file does not exist or does not contain a physical address, then invalidate the physical address. no edid, no address, periodt.
• -E, --phys-addr-from-edid-poll <path> — parse the given EDID file (in raw binary format) and extract the physical address. if the EDID file does not exist or does not contain a physical address, then invalidate the physical address. poll for changes in this EDID file every 100 ms and, if changed, update the physical address.

this provides a way for Pulse-Eight (or similar) USB CEC dongles to become aware of HDMI disconnect and reconnect events. 👀

polling happens in the background while cec-ctl processes other requested actions (i.e. transmitting messages, waiting for replies, etc.) and when that is all done cec-ctl will keep polling until the user kills cec-ctl (Ctrl-C). so she's nosy and she does not stop. multitasking queen 👑

• -o, --osd-name <name> — use this OSD name. the maximum length is 14 characters. fourteen. not fifteen. don't test her.
• -V, --vendor-id <id> — use this vendor ID. the vendor ID is a number from 0x0 to 0xffffff.
• -x, --physical-address — show the physical address. if invalid, the physical address will be reported as f.f.f.f. useful for scripts, e.g.: la=cec-ctl -s -x``
• -l, --logical-address — show first configured logical address or nothing if the device is unconfigured. useful for scripts, e.g.: la=cec-ctl -s -l``
• -L, --logical-addresses — show all configured logical addresses or nothing if the device is unconfigured. useful for scripts, e.g.: las=cec-ctl -s -L``
• -C, --clear — clear all logical addresses, leaving the CEC device unconfigured. clean slate bestie 🧼
• -n, --no-reply — by default when sending a CEC message that expects a reply this utility will wait for that reply. with this option it will just send it without waiting for the reply. this option applies to the messages following this option. it acts as a toggle, so after you specify it a second time then the following messages will wait for a reply again. flip flop flip flop 🦋
• -N, --non-blocking — transmit messages in non-blocking mode.
• -t, --to <la> — send the message to the given logical address (0-15).
• -f, --from <la> — send message from the given logical address. it is only necessary to use this option if multiple logical addresses are claimed. by default the first assigned logical address will be used.
• -r, --show-raw — show the raw CEC message in hex. the raw tea ☕
• -s, --skip-info — skip the Driver Info output section. we're skipping the intros, getting straight to the plot 📖
• -S, --show-topology — show the CEC topology, detecting which other CEC devices are on the CEC bus. who's on the bus? let's find out 🔍
• -P, --poll — send a poll message.
• -T, --trace — trace all called ioctls. useful for debugging. she's showing her work ✍️
• --cec-version-1.4 — use CEC Version 1.4 instead of 2.0 (the default). throwback era 💜
• --allow-unreg-fallback — allow fallback to Unregistered if all logical addresses are claimed. by default the adapter will remain unconfigured.
• --no-rc-passthrough — disable the RC passthrough. by default remote control CEC messages are passed on as input keystrokes (the CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU flag is set when calling the CEC_ADAP_S_LOG_ADDRS ioctl), but this can be blocked by using this option.
• --reply-to-followers — the reply will be sent to followers as well. by default the reply will only go to the follower that initiated the CEC message. but if you have other followers running as well, then by giving this option they will also receive the reply. group chat, not a DM 💬
• --timeout <ms> — set the reply timeout in milliseconds (default is 1000 ms). one whole second of patience. generous fr fr.
• --tv — configure the CEC adapter as a TV.
• --record — configure the CEC adapter as a recording and playback device.
• --tuner — configure the CEC adapter as a tuner device.
• --playback — configure the CEC adapter as a playback device.
• --audio — configure the CEC adapter as an audio system device.
• --processor — configure the CEC adapter as a processor device.
• --switch — configure the CEC adapter as a pure CEC switch.
• --cdc-only — configure the CEC adapter as a CDC-only device.
• --unregistered — configure the CEC adapter as an unregistered device.
• --feat-record-tv-screen — signal the Record TV Screen feature.
• --feat-set-osd-string — signal the Set OSD String feature.
• --feat-deck-control — signal the Deck Control feature.
• --feat-set-audio-rate — signal the Set Audio Rate feature.
• --feat-sink-has-arc-tx — signal the sink ARC Tx feature.
• --feat-source-has-arc-rx — signal the source ARC Rx feature.
• --rc-tv-profile-1 — signal RC TV Profile 1.
• --rc-tv-profile-2 — signal RC TV Profile 2.
• --rc-tv-profile-3 — signal RC TV Profile 3.
• --rc-tv-profile-4 — signal RC TV Profile 4.
• --rc-src-dev-root — signal that the RC source has a Dev Root Menu.
• --rc-src-dev-setup — signal that the RC source has a Dev Setup Menu.
• --rc-src-contents — signal that the RC source has a Contents Menu.
• --rc-src-media-top — signal that the RC source has a Media Top Menu.
• --rc-src-media-context — signal that the RC source has a Media Context Menu.
• -m, --monitor — start monitoring CEC traffic. this will monitor broadcast messages, messages directed to this CEC adapter and messages transmitted by this CEC adapter. directed messages between other CEC devices are not monitored. this option requires root. so she sees some things, not everything. boundaries! 🚧
• -M, --monitor-all — start monitoring all CEC traffic. this will monitor all CEC messages, including directed messages between other CEC devices. this option requires root. not all CEC devices support this monitoring mode. it will fallback to regular monitoring mode if it is not supported. now that's the full surveillance era 👁️
• --monitor-pin — start monitoring and analyzing the low-level CEC pin transitions. this is only possible if the device has the CEC_CAP_MONITOR_PIN capability. this option requires root. when in pin monitoring mode all 0->1 and 1->0 CEC pin transitions are monitored and analysed. this is effectively a cheap CEC bus analyzer. cheap and effective, we love a budget icon 💅
• --monitor-time <secs> — monitor for the given number of seconds, then exit. the default (0) is to monitor forever. forever is a long time bestie 😭
• --ignore <la>,<opcode> — ignore messages from logical address <la> and opcode <opcode> when monitoring. "all" can be used for <la> or <opcode> to match all logical addresses or opcodes. to ignore poll messages use "poll" as <opcode>. mute button, but make it precise 🔇
• --store-pin <to> — store the CEC pin events to the given file. this can be read and analyzed later via the --analyze-pin option. use - to write to stdout instead of to a file. save it for later, scrapbook style 📸
• --analyze-pin <from> — read and analyze the CEC pin events from the given file. use - to read from stdin instead of from a file. then the forensic era begins 🔬
• --test-reliability <secs> — this option tests the CEC reliability by transmitting <Give Physical Addr> up to <secs> seconds (or forever if <secs> is 0) and check if the reply is always the same. since the reply is a broadcast message, it is in practice never Nacked and so any bit errors due to poor CEC signal quality will clearly show up. the message will be sent to the logical address specified by --to. stress test but make it CEC 🔥
• --test-standby-wakeup-cycle [polls=<n>][,sleep=<secs>][,hpd-may-be-low=<0/1>] — this option tests the standby-wakeup cycle behavior of the display. it polls up to <n> times (default 15), waiting for a state change. if that fails then it waits <secs> seconds (default 10) before retrying this. if <hpd-may-be-low> is 1, then the HPD is allowed to be low when in standby. nap time, wake up, repeat 💤

---

part 1 done bestie, more is coming — don't go anywhere 💖

• --stress-test-standby-wakeup-cycle cnt=<count>[,polls=<n>][,max-sleep=<maxsecs>][,min-sleep=<minsecs>][,seed=<seed>][,repeats=<reps>][,sleep-before-on=<secs1>][,sleep-before-off=<secs2>][,hpd-may-be-low=<0/1>] — okay so this is the big girl stress test 💅 it puts a display through its paces by cycling it in and out of standby <count> times, using the CEC Standby and Image View On commands. And if <count> is 0? bestie it literally never stops 😭

Here's the full tea, no skipping:

• It polls up to <n> times (default 30), just sitting there waiting for a state change like 👀
• If <maxsecs> is non-zero (0 is the default, so it's off unless you say otherwise), it sleeps for a random number of seconds between <minsecs> (0 is the default) and <maxsecs> before each Standby or Image View On message. Random naps, iconic ✨
• If <seed> is specified, it sets the randomizer seed to that value instead of using the current time as the seed. Reproducible chaos, we love her 🎀
• If <reps> is specified, it repeats the Image View On and Standby up to <reps> times.

⚠️ Not me having to say this: this test should work without any repeats. If a non-zero <reps> value is needed in order to pass this test, then that indicates a problem. Like, a real one. fr fr 🚩

• If <secs1> is specified, it sleeps for <secs1> seconds before transmitting Image View On.
• If <secs2> is specified, it sleeps for <secs2> seconds before transmitting Standby.
• If <hpd-may-be-low> is 1, then the HPD is allowed to be low when in standby. Permission granted, slay 🫶

• --stress-test-random-standby-wakeup-cycle cnt=<count>[,max-sleep=<maxsecs>][,min-sleep=<minsecs>][,seed=<seed>][,hpd-may-be-low=<0/1>] — the chaos goblin sibling of the test above 🔥 same energy (stress test for a display, cycles it in and out of standby <count> times using the CEC Standby and Image View On commands), but the vibe is different:
  • After each command it waits between <minsecs> (default is 0) and <maxsecs> (default is 10) seconds.
  • It does not check whether the display reached the new state. That's literally the point — this test is meant to check whether the display can handle state change commands while it's still transitioning to a new state. Poking the bear mid-transition, highkey rude but that's the assignment 💀
  • After every 10 cycles it attempts to properly wake up the display and check if that works. If not, this test fails. Periodt.
  • If <count> is 0, then it never stops. Ever. 🌀
  • If <seed> is specified, then set the randomizer seed to that value instead of using the current time as seed.
  • If <hpd-may-be-low> is 1, then the HPD is allowed to be low when in standby.
• --help-all — prints the help message for all the options. Everything, all at once, main character energy 👑
• --help-audio-rate-control — shows help for the Audio Rate Control feature.
• --help-audio-return-channel-control — shows help for the Audio Return Channel Control feature.
• --help-capability-discovery-and-control — shows help for the Capability Discovery and Control feature.
• --help-deck-control — shows help for the Deck Control feature.
• --help-device-menu-control — shows help for the Device Menu Control feature.
• --help-device-osd-transfer — shows help for the Device OSD Transfer feature.
• --help-dynamic-audio-lipsync — shows help for the Dynamic Audio Lipsync feature.
• --help-htng — shows help for the Hospitality Profile Next Generation feature. Heads up bestie: this is an optional CEC extension for Hotel displays and it's not generally available for regular displays 🙈 More info lives at http://www.htng.org if you're curious.
• --help-osd-display — shows help for the OSD Display feature.
• --help-one-touch-play — shows help for the One Touch Play feature.
• --help-one-touch-record — shows help for the One Touch Record feature.
• --help-power-status — shows help for the Power Status feature.
• --help-remote-control-passthrough — shows help for the Remote Control Passthrough feature.
• --help-routing-control — shows help for the Routing Control feature.
• --help-standby — shows help for the Standby feature.
• --help-system-audio-control — shows help for the System Audio Control feature.
• --help-system-information — shows help for the System Information feature.
• --help-timer-programming — shows help for the Timer Programming feature.
• --help-tuner-control — shows help for the Tuner Control feature.
• --help-vendor-specific-commands — shows help for the Vendor Specific Commands feature.

---

🌈 EXIT STATUS 🌈

Okay so when everything goes right, it returns 0 — the sweetest little green flag ever 💚

Otherwise, it will return the error code. So if you see a number that is not zero, that's your sign, go read it 😤

---

🦋 BUGS 🦋

Real talk: this manual page is a work in progress. She's growing, she's evolving, she's not done yet 🌱

Bug reports or questions about this utility should be sent to the linux-media@vger.kernel.org mailinglist. Yes, the mailing list, that's where the homies hang out 📬

---

And that's a wrap on CEC-CTL(1), bestie. 💖 This whole page is riding with v4l-utils 1.32.0, dated August 2016 — a certified classic that still eats 💅✨ go forth and control your CEC devices responsibly, mwah 🫶👑