.TH "CEC-FOLLOWER" "1" "August 2016" "v4l-utils @PACKAGE_VERSION@" "User Commands"
.SH NAME
cec-follower - An application to emulate CEC followers
.SH SYNOPSIS
.B cec-follower
[\fI-h\fR] [\fI-d <dev>\fR] [other options]
.SH DESCRIPTION
The \fBcec-follower\fR tool is used to emulate CEC followers. Based on the configured
logical address(es) of the CEC device it will emulate the CEC behavior
accordingly.

Configuring the CEC device is done using \fBcec-ctl\fR. Certain CEC functionalities
are only emulated if the corresponding Device Features flag is set (these are set
when configuring with \fBcec-ctl\fR). These are:

    - Audio Return Channel (RX and TX)
    - Audio Rate Control
    - Deck Control
    - Record TV screen

\fBcec-follower\fR is basically a message loop, waiting for messages to arrive
and taking the appropriate action for each message (incoming messages can be
shown with the \fI--show-msgs\fR option). The follower maintains an internal
state with appropriate parameters such as volume, current active source, power
state and so on (state changes can be shown with the \fI--show-state\fR option).

It also aims to be a reference implementation on how a follower should behave.

\fBcec-follower\fR will keep track of incoming messages and look for violations
of the CEC specification with regards to timings. For example, it will warn if
it receives the same message again within 200ms after it replied <Feature Abort>
["Unrecognized Opcode"] to that message, and it will check that press and hold
behavior is done properly.

\fBcec-follower\fR will periodically send out polling messages to discover when
a remote device is removed or a new one has appeared. When a device is removed,
the recorded information about it is cleared. Each logical address is polled
about once every 15 seconds. In between polls, removing a remote device or
replacing it with a new one is not detected.

When running compliance tests with \fBcec-compliance\fR, \fBcec-follower\fR
should be run on the same device to act on incoming messages that are not replies
to messages sent by the compliance tool. Before each test-run \fBcec-follower\fR
should be restarted if it is running, to initialize the emulated device with a
clean and known initial state.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-device\fR \fI<dev>\fR
Use device <dev> as the CEC device. If <dev> is a number, then /dev/cec<dev> is used.
.TP
\fB\-D\fR, \fB\-\-driver\fR \fI<drv>\fR
Use a cec device that has driver name \fI<drv>\fR, as returned by the CEC_ADAP_G_CAPS ioctl.
This option can be combined with \fB\-a\fR to uniquely identify a CEC device without
having to rely on the device node number.
.TP
\fB\-a\fR, \fB\-\-adapter\fR \fI<adap-name>\fR
Use a cec device that has adapter name \fI<adap-name>\fR, as returned by the CEC_ADAP_G_CAPS ioctl.
This option can be combined with \fB\-D\fR to uniquely identify a CEC device without
having to rely on the device node number.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Turn on verbose reporting.
.TP
\fB\-\-version\fR
Show version information.
.TP
\fB\-w\fR, \fB\-\-wall\-clock\fR
Show timestamps as wall-clock time. This also turns on verbose reporting. 
.TP
\fB\-T\fR, \fB\-\-trace\fR
Trace all called ioctls. Useful for debugging.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints the help message.
.TP
\fB\-n\fR, \fB\-\-no\-warnings\fR
Turn off warning messages.
.TP
\fB\-m\fR, \fB\-\-show\-msgs\fR
Show received messages.
.TP
\fB\-s\fR, \fB\-\-show\-state\fR
Show state changes from the emulated device.
.TP
\fB\-\-service\-by\-dig\-id\fR
Report digital services by digital ID instead of by channel.
.TP
\fB\-\-standby\fR
Start the follower in the Standby status.
.TP
\fB\-\-toggle\-power\-status\fR \fI<secs>\fR
Toggle the power status every <secs> seconds. Only supported if the follower
is emulating a TV.
.TP
\fB\-i\fR, \fB\-\-ignore\fR \fI<la>,<opcode>\fR
Ignore messages from logical address \fI<la>\fR and opcode
\fI<opcode>\fR. 'all' can be used for \fI<la>\fR or \fI<opcode>\fR to match
all logical addresses or opcodes.
.TP
\fB\-\-ignore\-standby\fR \fI<n>\fR
Ignore every <n>th received Standby message.
.TP
\fB\-\-ignore\-view\-on\fR \fI<n>\fR
Ignore every <n>th received Image/Text View On message.

.SH EXIT STATUS
On success, it returns 0. Otherwise, it will return the error code.
.SH 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.
.SH SEE ALSO
\fBcec-compliance\fR(1), \fBcec-ctl\fR(1)
