1CEC-CTL(1)                         1.25.0""                         CEC-CTL(1)
2
3
4

NAME

6       cec-ctl - An application to control cec devices
7

SYNOPSIS

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

DESCRIPTION

12       The  cec-ctl tool is used to control cec devices. It is able to control
13       almost any aspect of such devices covering the full CEC API.
14
15       The easiest way to quickly test a CEC adapter of an HDMI output is:
16
17            cec-ctl -d/dev/cecX --playback -S
18
19       And for an HDMI input:
20
21            cec-ctl -d/dev/cecX --tv -S
22
23       Both commands configure the CEC adapter and show the CEC topology.
24
25       To put a display to standby use:
26
27            cec-ctl -d/dev/cecX --to 0 --standby
28
29       To wake up the display:
30
31            cec-ctl -d/dev/cecX --to 0 --image-view-on
32
33       To switch the TV to our HDMI output (replace the physical address  with
34       what cec-ctl -d/dev/cecX reported):
35
36            cec-ctl -d/dev/cecX --to 0 --active-source phys-addr=1.0.0.0
37
38       Instead of '-d/dev/cecX' you can also write this as '-dX'.  And instead
39       of '--to 0' you can also write this as '-t0'.
40
41

OPTIONS

43       -d, --device <dev>
44              Use device <dev> as the CEC device. If <dev> is a  number,  then
45              /dev/cec<dev> is used.
46
47       -D, --driver <drv>
48              Use  a cec device that has driver name <drv>, as returned by the
49              CEC_ADAP_G_CAPS ioctl.  This option can be combined with  -a  to
50              uniquely identify a CEC device without having to rely on the de‐
51              vice node number.
52
53       -a, --adapter <adap-name>
54              Use a cec device that has adapter name <adap-name>, as  returned
55              by  the CEC_ADAP_G_CAPS ioctl.  This option can be combined with
56              -D to uniquely identify a CEC device without having to  rely  on
57              the device node number.
58
59       -v, --verbose
60              Turn on verbose reporting.
61
62       --version
63              Show version information.
64
65       -w, --wall-clock
66              Show  timestamps  as wall-clock time. This also turns on verbose
67              reporting.
68
69       -h, --help
70              Prints the help message.
71
72       -p, --phys-addr <addr>
73              Use this physical address. The address can be a number  (e.g.  0
74              or 0x11b1) or formatted as a.b.c.d where each component is a hex
75              value from 0-f (e.g. 0.0.0.0 or 1.1.b.1).
76
77       -e, --phys-addr-from-edid <path>
78              Parse the given EDID file (in raw binary format) and extract the
79              physical  address.  If  the EDID file does not exist or does not
80              contain a physical address, then  invalidate  the  physical  ad‐
81              dress.
82
83       -E, --phys-addr-from-edid-poll <path>
84              Parse the given EDID file (in raw binary format) and extract the
85              physical address. If the EDID file does not exist  or  does  not
86              contain  a  physical  address,  then invalidate the physical ad‐
87              dress. Poll for changes in this EDID file every 100 ms  and,  if
88              changed, update the physical address.
89
90              This provides a way for Pulse-Eight (or similar) USB CEC dongles
91              to become aware of HDMI disconnect and reconnect events.
92
93              Polling happens in the background while cec-ctl processes  other
94              requested  actions  (i.e.  transmitting  messages,  waiting  for
95              replies, etc.) and when that  is  all  done  cec-ctl  will  keep
96              polling until the user kills cec-ctl (Ctrl-C).
97
98       -o, --osd-name <name>
99              Use this OSD name. The maximum length is 14 characters.
100
101       -V, --vendor-id <id>
102              Use  this  vendor  ID.  The  vendor  ID  is a number from 0x0 to
103              0xffffff.
104
105       -l, --logical-address
106              Show first configured logical address or nothing if  the  device
107              is unconfigured.  Useful for scripts, e.g.: la=`cec-ctl -s -l`
108
109       -L, --logical-addresses
110              Show  all  configured logical addresses or nothing if the device
111              is unconfigured.  Useful for scripts, e.g.: las=`cec-ctl -s -L`
112
113       -C, --clear
114              Clear all logical addresses, leaving the  CEC  device  unconfig‐
115              ured.
116
117       -n, --no-reply
118              By  default when sending a CEC message that expects a reply this
119              utility will wait for that reply. With this option it will  just
120              send  it  without  waiting for the reply. This option applies to
121              the messages following this option.  It acts as a toggle, so af‐
122              ter  you  specify  it  a second time then the following messages
123              will wait for a reply again.
124
125       -N, --non-blocking
126              Transmit messages in non-blocking mode.
127
128       -t, --to <la>
129              Send the message to the given logical address (0-15).
130
131       -f, --from <la>
132              Send message from the given logical address. It is  only  neces‐
133              sary  to  use  this  option  if  multiple  logical addresses are
134              claimed. By default the first assigned logical address  will  be
135              used.
136
137       -r, --show-raw
138              Show the raw CEC message in hex.
139
140       -s, --skip-info
141              Skip the Driver Info output section.
142
143       -S, --show-topology
144              Show  the CEC topology, detecting which other CEC devices are on
145              the CEC bus.
146
147       -P, --poll
148              Send a poll message.
149
150       -T, --trace
151              Trace all called ioctls. Useful for debugging.
152
153       --cec-version-1.4
154              Use CEC Version 1.4 instead of 2.0 (the default).
155
156       --allow-unreg-fallback
157              Allow fallback to Unregistered  if  all  logical  addresses  are
158              claimed.  By default the adapter will remain unconfigured.
159
160       --no-rc-passthrough
161              Disable  the  RC passthrough. By default remote control CEC mes‐
162              sages  are  passed  on  as  input  keystrokes  (the  CEC_LOG_AD‐
163              DRS_FL_ALLOW_RC_PASSTHRU   flag   is   set   when   calling  the
164              CEC_ADAP_S_LOG_ADDRS ioctl), but this can be  blocked  by  using
165              this option.
166
167       --reply-to-followers
168              The  reply will be sent to followers as well. By default the re‐
169              ply will only go to the follower that initiated the CEC message.
170              But  if you have other followers running as well, then by giving
171              this option they will also receive the reply.
172
173       --timeout <ms>
174              Set the reply timeout in milliseconds (default is 1000 ms).
175
176       --tv   Configure the CEC adapter as a TV.
177
178       --record
179              Configure the CEC adapter as a recording and playback device.
180
181       --tuner
182              Configure the CEC adapter as a tuner device.
183
184       --playback
185              Configure the CEC adapter as a playback device.
186
187       --audio
188              Configure the CEC adapter as an audio system device.
189
190       --processor
191              Configure the CEC adapter as a processor device.
192
193       --switch
194              Configure the CEC adapter as a pure CEC switch.
195
196       --cdc-only
197              Configure the CEC adapter as a CDC-only device.
198
199       --unregistered
200              Configure the CEC adapter as an unregistered device.
201
202       --feat-record-tv-screen
203              Signal the Record TV Screen feature.
204
205       --feat-set-osd-string
206              Signal the Set OSD String feature.
207
208       --feat-deck-control
209              Signal the Deck Control feature.
210
211       --feat-set-audio-rate
212              Signal the Set Audio Rate feature.
213
214       --feat-sink-has-arc-tx
215              Signal the sink ARC Tx feature.
216
217       --feat-source-has-arc-rx
218              Signal the source ARC Rx feature.
219
220       --rc-tv-profile-1
221              Signal RC TV Profile 1.
222
223       --rc-tv-profile-2
224              Signal RC TV Profile 2.
225
226       --rc-tv-profile-3
227              Signal RC TV Profile 3.
228
229       --rc-tv-profile-4
230              Signal RC TV Profile 4.
231
232       --rc-src-dev-root
233              Signal that the RC source has a Dev Root Menu.
234
235       --rc-src-dev-setup
236              Signal that the RC source has a Dev Setup Menu.
237
238       --rc-src-contents
239              Signal that the RC source has a Contents Menu.
240
241       --rc-src-media-top
242              Signal that the RC source has a Media Top Menu.
243
244       --rc-src-media-context
245              Signal that the RC source has a Media Context Menu.
246
247       -m, --monitor
248              Start monitoring CEC traffic. This will monitor  broadcast  mes‐
249              sages, messages directed to this CEC adapter and messages trans‐
250              mitted by this CEC adapter. Directed messages between other  CEC
251              devices are not monitored. This option requires root.
252
253       -M, --monitor-all
254              Start monitoring all CEC traffic. This will monitor all CEC mes‐
255              sages, including directed messages between  other  CEC  devices.
256              This  option  requires  root.   Not all CEC devices support this
257              monitoring mode. It will fallback to regular monitoring mode  if
258              it is not supported.
259
260       --monitor-pin
261              Start  monitoring  and  analyzing  the low-level CEC pin transi‐
262              tions. This is only possible if the device has the CEC_CAP_MONI‐
263              TOR_PIN capability. This option requires root.  When in pin mon‐
264              itoring mode all 0->1 and 1->0 CEC pin transitions are monitored
265              and analysed. This is effectively a cheap CEC bus analyzer.
266
267       --monitor-time <secs>
268              Monitor  for the given number of seconds, then exit. The default
269              (0) is to monitor forever.
270
271       --ignore <la>,<opcode>
272              Ignore messages from logical address <la>  and  opcode  <opcode>
273              when  monitoring.   "all"  can  be  used for <la> or <opcode> to
274              match all logical addresses or opcodes.  To ignore poll messages
275              use "poll" as <opcode>.
276
277       --store-pin <to>
278              Store the CEC pin events to the given file. This can be read and
279              analyzed later via the --analyze-pin option. Use - to  write  to
280              stdout instead of to a file.
281
282       --analyze-pin <from>
283              Read  and  analyze the CEC pin events from the given file. Use -
284              to read from stdin instead of from a file.
285
286       --test-power-cycle [polls=<n>][,sleep=<secs>]
287              This option tests the power cycle behavior of  the  display.  It
288              polls  up to <n> times (default 15), waiting for a state change.
289              If that fails then it waits <secs> seconds (default  10)  before
290              retrying this.
291
292       --stress-test-power-cycle                 cnt=<count>[,polls=<n>][,max-
293       sleep=<maxsecs>][,min-sleep=<minsecs>][,seed=<seed>][,re‐
294       peats=<reps>][,sleep-before-on=<secs1>][,sleep-before-off=<secs2>]
295              This  option  performs a stress test for a display: it power cy‐
296              cles the display <count> times using the CEC Standby  and  Image
297              View On commands. If <count> is 0, then never stop.  It polls up
298              to <n> times (default 30),  waiting  for  a  state  change.   If
299              <maxsecs>  is non-zero (0 is the default), then sleep for a ran‐
300              dom number of seconds between <minsecs> (0 is the  default)  and
301              <maxsecs>  before each <Standby> or <Image View On> message.  If
302              <seed> is specified, then set the randomizer seed to that  value
303              instead  of using the current time as seed.  If <reps> is speci‐
304              fied, then repeat the <Image View On> and <Standby> up to <reps>
305              times. Note that this test should work without any repeats. If a
306              non-zero <reps> value is needed in order to pass this test, then
307              that  indicates  a problem.  If <secs1> is specified, then sleep
308              for <secs1> seconds before transmitting  <Image  View  On>.   If
309              <secs2>  is  specified,  then  sleep  for <secs2> seconds before
310              transmitting <Standby>.
311
312       --help-all
313              Prints the help message for all options.
314
315       --help-audio-rate-control
316              Show help for the Audio Rate Control feature.
317
318       --help-audio-return-channel-control
319              Show help for the Audio Return Channel Control feature.
320
321       --help-capability-discovery-and-control
322              Show help for the Capability Discovery and Control feature.
323
324       --help-deck-control
325              Show help for the Deck Control feature.
326
327       --help-device-menu-control
328              Show help for the Device Menu Control feature.
329
330       --help-device-osd-transfer
331              Show help for the Device OSD Transfer feature.
332
333       --help-dynamic-audio-lipsync
334              Show help for the Dynamic Audio Lipsync feature.
335
336       --help-htng
337              Show help for the Hospitality Profile Next  Generation  feature.
338              This  is an optional CEC extension for Hotel displays and is not
339              generally    available     for     regular     displays.     See
340              http://www.htng.org for more information.
341
342       --help-osd-display
343              Show help for the OSD Display feature.
344
345       --help-one-touch-play
346              Show help for the One Touch Play feature.
347
348       --help-one-touch-record
349              Show help for the One Touch Record feature.
350
351       --help-power-status
352              Show help for the Power Status feature.
353
354       --help-remote-control-passthrough
355              Show help for the Remote Control Passthrough feature.
356
357       --help-routing-control
358              Show help for the Routing Control feature.
359
360       --help-standby
361              Show help for the Standby feature.
362
363       --help-system-audio-control
364              Show help for the System Audio Control feature.
365
366       --help-system-information
367              Show help for the System Information feature.
368
369       --help-timer-programming
370              Show help for the Timer Programming feature.
371
372       --help-tuner-control
373              Show help for the Tuner Control feature.
374
375       --help-vendor-specific-commands
376              Show help for the Vendor Specific Commands feature.
377

EXIT STATUS

379       On success, it returns 0. Otherwise, it will return the error code.
380

BUGS

382       This manual page is a work in progress.
383
384       Bug  reports  or  questions  about  this  utility should be sent to the
385       linux-media@vger.kernel.org mailinglist.
386
387
388
389v4l-utils                         August 2016                       CEC-CTL(1)
Impressum