-.TH SIGROK\-CLI 1 "October 22, 2018"
+.TH SIGROK\-CLI 1 "March 28, 2019"
.SH "NAME"
sigrok\-cli \- Command-line client for the sigrok software
.SH "SYNOPSIS"
Show information about supported hardware drivers, input file
formats, output file formats, and protocol decoders.
.TP
+.B "\-\-list\-supported\-wiki"
+Show information about supported protocol decoders in MediaWiki syntax.
+This is generally only used by developers to easily update the list of
+supported protocol decoders in the sigrok wiki.
+.TP
\fB\-d, \-\-driver\fP <drivername>
-A driver must always be selected (unless doing a global scan). Use the
-.BR "\-L " ( "\-\-list-supported" ")"
+Unless doing a global scan, users typically select one of the available
+drivers. This can speedup program start, and can avoid false matches for
+ambiguous configurations. Selecting a driver also allows to pass more
+driver specific options. Use the
+.BR "\-L " ( "\-\-list\-supported" ")"
option to get a list of available drivers.
.sp
Drivers can take options, in the form \fBkey=value\fP
.RB " $ " "sigrok\-cli \-\-driver=ols:conn=/dev/ttyACM0" " [...]"
.sp
Some USB devices don't use a unique VendorID/ProductID combination, and thus
-need that specified as well. This also uses the \fBconn\fP option, using
-either \fBVendorID.ProductID\fP or \fBbus.address\fP:
+need that specified as well. Notice that colons are used to separate the
+driver name from the \fBconn\fP option, thus colons cannot be used within the
+\fBconn\fP option's argument. To select a specific USB device, use either
+\fBVendorID.ProductID\fP or \fBbus.address\fP:
.sp
USB \fBVendorID.ProductID\fP example:
.sp
.sp
.RB " $ " "sigrok\-cli \-\-driver=uni\-t\-ut61e:conn=4.6" " [...]"
.TP
+.B "\-D, \-\-dont\-scan"
+Do not automatically scan for device drivers in the absence of a
+.BR "\-d " ( "\-\-driver" )
+specification.
+.TP
.BR "\-c, \-\-config " <deviceoption>
A colon-separated list of device options, where each option takes the form
.BR key=value .
0:11111111 11111111 11111111 11111111 [...]
1:11111111 00000000 11111111 00000000 [...]
.sp
-Example for saving data in the VCD format with options:
+Example for saving data in the CSV format with options:
+.sp
+.RB " $ " "sigrok\-cli " "[...] " "\-o example.csv \-O csv:dedup:header=false"
.sp
-.RB " $ " "sigrok\-cli " "[...] " "\-o example.vcd \-O vcd:downsample=4"
+Notice that boolean options are \fBtrue\fP when no value gets specified.
.TP
.BR "\-C, \-\-channels " <channellist>
A comma-separated list of channels to be used in the session.
groups, the settings of which can only be changed as a group. The list of
channel groups, if any, is displayed with the \fB\-\-show\fP command.
.sp
-Example:
+Examples:
.sp
.RB " $ " "sigrok\-cli \-g CH1" " [...]"
+.sp
+.RB " $ " "sigrok\-cli \-d demo \-g Logic \-c pattern=graycode" " [...]"
.TP
.BR "\-t, \-\-triggers " <triggerlist>
A comma-separated list of triggers to use, of the form
.sp
.TP
.BR "\-A, \-\-protocol\-decoder\-annotations " <annotations>
-By default, only the stack's topmost protocol decoder's annotation output is
-shown. With this option another decoder's annotation can be selected for
-display, by specifying its ID:
+By default, all annotation output of all protocol decoders is
+shown. With this option a specific decoder's annotations can be selected for
+display, by specifying the decoder ID:
.sp
$
.B "sigrok\-cli \-i <file.sr> \-P i2c,i2cfilter,edid \-A i2c"
.sp
-If a protocol decoder has multiple annotations, you can also specify
+If a protocol decoder has multiple annotation classes, you can also specify
which one of them to show by specifying its short description like this:
.sp
$
.br
.B " \-A i2c=data\-read"
.sp
-Select multiple annotations by separating them with a colon:
+Select multiple annotation classes by separating them with a colon:
.sp
$
.B "sigrok\-cli \-i <file.sr> \-P i2c,i2cfilter,edid"
.br
.B " \-A i2c=data\-read:data\-write"
.sp
-You can also select multiple protocol decoders, with an optional selected
-annotation each, by separating them with commas:
+Annotation row names will resolve to their respective list of classes.
+Row and class names can be used in combination. When names are ambiguous
+then class names take precedence.
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-P i2c"
+.br
+.B " \-A i2c=addr\-data:warnings"
+.sp
+You can also select multiple protocol decoders, with optionally selected
+annotation classes each, by separating them with commas:
.sp
$
.B "sigrok\-cli \-i <file.sr> \-P i2c,i2cfilter,edid"
.B "sigrok\-cli \-\-input\-format csv \-\-show
$
.B "sigrok\-cli \-\-output\-format bits \-\-show
+.sp
+This also works for input files, including optional input format specifications:
+.sp
+ $
+.B "sigrok\-cli \-\-input\-file <file.sr> \-\-show
+ $
+.B "sigrok\-cli \-\-input\-file <file.vcd> \-\-input\-format vcd \-\-show
.TP
.B "\-\-scan"
Scan for devices that can be detected automatically.