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

EXIT STATUS

372       On success, it returns 0. Otherwise, it will return the error code.
373

BUGS

375       This manual page is a work in progress.
376
377       Bug  reports  or  questions  about  this  utility should be sent to the
378       linux-media@vger.kernel.org mailinglist.
379
380
381
382v4l-utils 1.20.0                  August 2016                       CEC-CTL(1)
Impressum