dwww Home | Manual pages | Find package

CEC-CTL(1)                       User Commands                       CEC-CTL(1)

NAME
       cec-ctl - An application to control cec devices

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

DESCRIPTION
       The  cec-ctl  tool is used to control cec devices. It is able to control
       almost any aspect of such devices covering the full CEC API.

       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 would use if the HDMI output of  your  device  supports
       CEC: your device will play back video, so it is a CEC Playback device.

       And for an HDMI input:

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

       This  is  what  you  would use if your device has an HDMI input, i.e. it
       acts like a TV.

       Both commands configure the CEC adapter and show the CEC topology.   The
       '--playback'  and  '--tv'  options  configure  your device, they are not
       about what device you will be talking to.

       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 (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

       Instead  of '-d/dev/cecX' you can also write this as '-dX'.  And instead
       of '--to 0' you can also write this as '-t0'.

OPTIONS
       -A, --list-devices
              List all cec devices.

       -d, --device <dev>
              Use device <dev> as the CEC device. If <dev> is  a  number,  then
              /dev/cec<dev> is used.

       -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 de-
              vice node number.

       -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.

       -v, --verbose
              Turn on verbose reporting.

       --version
              Show version information.

       -w, --wall-clock
              Show  timestamps  as  wall-clock time. This also turns on verbose
              reporting.

       -h, --help
              Prints the help message.

       -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).

       -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.

       -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).

       -o, --osd-name <name>
              Use this OSD name. The maximum length is 14 characters.

       -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.

       -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.

       -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.

       -s, --skip-info
              Skip the Driver Info output section.

       -S, --show-topology
              Show the CEC topology, detecting which other CEC devices  are  on
              the CEC bus.

       -P, --poll
              Send a poll message.

       -T, --trace
              Trace all called ioctls. Useful for debugging.

       --cec-version-1.4
              Use CEC Version 1.4 instead of 2.0 (the default).

       --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  mes-
              sages are passed on as input keystrokes (the CEC_LOG_ADDRS_FL_AL-
              LOW_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.

       --timeout <ms>
              Set the reply timeout in milliseconds (default is 1000 ms).

       --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 mes-
              sages, messages directed to this CEC adapter and messages  trans-
              mitted  by  this CEC adapter. Directed messages between other CEC
              devices are not monitored. This option requires root.

       -M, --monitor-all
              Start monitoring all CEC traffic. This will monitor all CEC  mes-
              sages,  including  directed  messages  between other CEC devices.
              This option requires root.  Not all CEC devices support this mon-
              itoring mode. It will fallback to regular monitoring mode  if  it
              is not supported.

       --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.

       --monitor-time <secs>
              Monitor for the given number of seconds, then exit.  The  default
              (0) is to monitor forever.

       --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>.

       --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.

       --analyze-pin <from>
              Read and analyze the CEC pin events from the given file. Use - to
              read from stdin instead of from a file.

       --test-reliability <secs>
              This option tests the CEC reliability by transmitting <Give Phys-
              ical  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.

       --test-standby-wakeup-cycle
       [polls=<n>][,sleep=<secs>][,hpd-may-be-low=<0/1>]
              This  option  tests the standby-wakeup cycle behavior of the dis-
              play. 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.

       --stress-test-standby-wakeup-cycle cnt=<count>[,polls=<n>][,max-
       sleep=<maxsecs>][,min-sleep=<minsecs>][,seed=<seed>][,re-
       peats=<reps>][,sleep-before-on=<secs1>][,sleep-before-
       off=<secs2>][,hpd-may-be-low=<0/1>]
              This  option  performs a stress test for a display: it cycles the
              display <count> times in and out of standby using the CEC Standby
              and Image View On commands.  If <count> is 0,  then  never  stop.
              It  polls  up  to  <n>  times  (default  30), waiting for a state
              change.  If <maxsecs> is non-zero (0 is the default), then  sleep
              for  a  random  number of seconds between <minsecs> (0 is the de-
              fault) and <maxsecs> before each <Standby>  or  <Image  View  On>
              message.  If <seed> is specified, then set the randomizer seed to
              that  value instead of using the current time as seed.  If <reps>
              is specified, then repeat the <Image View On> and <Standby> up to
              <reps> times. Note that this test should  work  without  any  re-
              peats. If a non-zero <reps> value is needed in order to pass this
              test,  then  that  indicates a problem.  If <secs1> is specified,
              then sleep for <secs1> seconds before  transmitting  <Image  View
              On>.  If <secs2> is specified, then sleep for <secs2> seconds be-
              fore  transmitting <Standby>.  If <hpd-may-be-low> is 1, then the
              HPD is allowed to be low when in standby.

       --stress-test-random-standby-wakeup-cycle cnt=<count>[,max-
       sleep=<maxsecs>][,min-sleep=<min-
       secs>][,seed=<seed>][,hpd-may-be-low=<0/1>]
              This option performs a stress test for a display: it  cycles  the
              display <count> times in and out of standby using the CEC Standby
              and  Image  View  On  commands.   After each command wait between
              <minsecs> (default is 0) and <maxsecs> (default is  10)  seconds.
              This  test  does  not check if the display reached the new state,
              this test is meant to check  if  the  display  can  handle  state
              change  commands while still transitioning to a new state.  After
              every 10 cycles it attempts to properly wake up the  display  and
              check  if  that works. If not, this test fails.  If <count> is 0,
              then never stop.  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 options.

       --help-audio-rate-control
              Show help for the Audio Rate Control feature.

       --help-audio-return-channel-control
              Show help for the Audio Return Channel Control feature.

       --help-capability-discovery-and-control
              Show help for the Capability Discovery and Control feature.

       --help-deck-control
              Show help for the Deck Control feature.

       --help-device-menu-control
              Show help for the Device Menu Control feature.

       --help-device-osd-transfer
              Show help for the Device OSD Transfer feature.

       --help-dynamic-audio-lipsync
              Show help for the Dynamic Audio Lipsync feature.

       --help-htng
              Show  help  for  the Hospitality Profile Next Generation feature.
              This is an optional CEC extension for Hotel displays and  is  not
              generally available for regular displays. See http://www.htng.org
              for more information.

       --help-osd-display
              Show help for the OSD Display feature.

       --help-one-touch-play
              Show help for the One Touch Play feature.

       --help-one-touch-record
              Show help for the One Touch Record feature.

       --help-power-status
              Show help for the Power Status feature.

       --help-remote-control-passthrough
              Show help for the Remote Control Passthrough feature.

       --help-routing-control
              Show help for the Routing Control feature.

       --help-standby
              Show help for the Standby feature.

       --help-system-audio-control
              Show help for the System Audio Control feature.

       --help-system-information
              Show help for the System Information feature.

       --help-timer-programming
              Show help for the Timer Programming feature.

       --help-tuner-control
              Show help for the Tuner Control feature.

       --help-vendor-specific-commands
              Show help for the Vendor Specific Commands feature.

EXIT STATUS
       On success, it returns 0. Otherwise, it will return the error code.

BUGS
       This manual page is a work in progress.

       Bug reports or questions about this utility should be sent to the linux-
       media@vger.kernel.org mailinglist.

v4l-utils 1.30.1                  August 2016                        CEC-CTL(1)

Generated by dwww version 1.16 on Fri Oct 23 19:54:12 CEST 2026.