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

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

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

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

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

       --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>]
	      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
	      default) 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 repeats. 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 before 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=<minsecs>][,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)