-.TH SIGROK\-CLI 1 "May 04, 2014"
+.TH SIGROK\-CLI 1 "September 13, 2017"
.SH "NAME"
sigrok\-cli \- Command-line client for the sigrok software
.SH "SYNOPSIS"
.B "\-V, \-\-version"
Show
.B sigrok-cli
-version, and information about supported hardware drivers, input file
+version and the versions of libraries used.
+.TP
+.B "\-L, \-\-list-supported"
+Show information about supported hardware drivers, input file
formats, output file formats, and protocol decoders.
.TP
\fB\-d, \-\-driver\fP <drivername>
A driver must always be selected (unless doing a global scan). Use the
-\fB-V\fP option to get a list of available drivers.
+.BR "\-L " ( "\-\-list-supported" ")"
+option to get a list of available drivers.
.sp
Drivers can take options, in the form \fBkey=value\fP
separated by colons.
option is not supplied (in addition to
.BR \-\-input\-file ),
sigrok-cli attempts to autodetect the file format of the input file. Use the
-.B \-V
+.BR "\-L " ( "\-\-list-supported" ")"
option to see a list of available input formats.
.sp
The format name may optionally be followed by a colon-separated list of
.TP
.BR "\-O, \-\-output\-format " <formatname>
Set the output format to use. Use the
-.B \-V
+.BR "\-L " ( "\-\-list-supported" ")"
option to see a list of available output formats.
.sp
The format name may optionally be followed by a colon-separated list of
options, where each option takes the form
.BR "key=value" .
.sp
-Supported formats currently include
-.BR bits ,
-.BR hex ,
-.BR ascii ,
-.BR binary ,
-.BR vcd ,
-.BR ols ,
-.BR gnuplot ,
-.BR chronovu-la8 ,
-.BR csv ", and"
-.BR analog .
-.sp
-The
+For example, the
.B bits
or
.B hex
This option allows the user to specify a comma-separated list of protocol
decoders to be used in this session. The decoders are specified by their
ID, as shown in the
-.B \-\-version
+.BR "\-L " ( "\-\-list-supported" ")"
output.
.sp
Example:
protocol decoder. Additionally, the user tells sigrok to decode the SPI
protocol using channel 1 as MISO signal for SPI, channel 5 as MOSI, channel 3
as CLK, and channel 0 as CS# signal.
-.TP
-.BR "\-S, \-\-protocol\-decoder\-stack " <stack>
-This option allows the user to specify a protocol decoder stack, i.e.
-the way in which one protocol decoder's output gets piped into another
-protocol decoder. If not specified, the stack will be set up in the same
-order in which the protocol decoders were given with the
-.B \-\-protocol-decoders
-option.
.sp
-The decoders are specified by their ID, as shown in the
-.B \-\-version
-output. In addition to the
-.B \-S
-option, all protocol decoders that are used in a stack, must also be specified
-(together with their options, if any) using the
-.B \-P
-parameter.
+Notice that the
+.B sigrok\-cli
+application does not support "name matching". Instead it's assumed that the
+traces in the input stream match the order of the decoder's input signals,
+or that users explicitly specify the input channel to decoder signal mapping.
+.br
+.sp
+When multiple decoders are specified in the same
+.BR -P
+option, they will be stacked on top of each other in the specified order.
.sp
Example:
.sp
$
-.B "sigrok\-cli \-i <file.sr> \-P i2c:sda=4:scl=7,rtc8564"
+.B "sigrok\-cli \-i <file.sr> \-P i2c,eeprom24xx"
.br
-.B " \-S i2c,rtc8564"
-.sp
-In this example, the
-.B \-S
-option specifies that the output of the
-.BR i2c " decoder"
-is piped into the
-.BR rtc8564 " decoder,"
-i.e., the
-.BR rtc8564 " decoder"
-is stacked on top of the
-.BR i2c " decoder."
-.sp
-The respective protocol decoder options and channel name/number assignments
-must be given using the
-.B \-P
-option (you cannot specify them in the
-.B \-S
-option).
+ $
+.B "sigrok\-cli \-i <file.sr> \-P uart:baudrate=31250,midi"
+.sp
+When multiple
+.BR -P
+options are specified, each of them creates one decoder stack, which
+executes in parallel to other decoder stacks.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-P uart:tx=D0:rx=D1 \-P timing:data=D2"
+.sp
.TP
.BR "\-A, \-\-protocol\-decoder\-annotations " <annotations>
By default, only the stack's topmost protocol decoder's annotation output is
.sp
Not every decoder generates binary output.
.TP
+.BR "\-\-protocol\-decoder\-samplenum
+When given, decoder annotations will include sample numbers, too.
+This allows consumers to receive machine readable timing information.
+.TP
.BR "\-l, \-\-loglevel " <level>
Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok-cli\fP
doesn't support setting the two loglevels independently. The higher the
$
.B "sigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-show
.sp
-This also works for protocol decoders and output modules:
+This also works for protocol decoders, input modules and output modules:
.sp
$
.B "sigrok\-cli \-\-protocol\-decoders i2c \-\-show
$
+.B "sigrok\-cli \-\-input\-format csv \-\-show
+ $
.B "sigrok\-cli \-\-output\-format bits \-\-show
.TP
.B "\-\-scan"
.BR "\-\-continuous"
Sample continuously until stopped. Not all devices support this.
.TP
+.BR "\-\-get " <variable>
+Get the value of
+.B <variable>
+from the specified device and print it.
+.TP
.BR "\-\-set"
Set one or more variables specified with the \fB\-\-config\fP option, without
doing any acquisition.