-.TH SIGROK\-CLI 1 "March 28, 2019"
+.TH SIGROK\-CLI 1 "April 07, 2023"
.SH "NAME"
sigrok\-cli \- Command-line client for the sigrok software
.SH "SYNOPSIS"
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
+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
.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
.BR "\-c, \-\-config " <deviceoption>
A colon-separated list of device options, where each option takes the form
.BR key=value .
+Multiple occurances of the
+.B \-\-config
+option are supported.
+The first item in the list of options can take the form
+.B channel_group=<name>
+which would override the
+.B \-\-channel\-group
+specification for this list of options. Other option lists in other
+.B \-\-config
+occurances are not affected by this list's channel group name.
+.sp
For example, to set the samplerate to 1MHz on a device supported by the
fx2lafw driver, you might specify
.sp
.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config samplerate=1m" " [...]"
.sp
.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config \(dqsamplerate=1 MHz\(dq" " [...]"
+.sp
+These examples specify options within a channel group.
+The first two are equivalent.
+.sp
+.RB " $ " "sigrok\-cli \-d demo \-\-channel\-group Logic \-\-config pattern=random [...]"
+.sp
+.RB " $ " "sigrok\-cli \-d demo \-\-config channel_group=Logic:pattern=random [...]"
+.sp
+.RB " $ " "sigrok\-cli \-d demo \-\-config samplerate=1m \-\-config channel_group=Logic:pattern=random [...]"
.TP
.BR "\-i, \-\-input\-file " <filename>
Load input from a file instead of a hardware device. You can specify
.RB " $ " "sigrok\-cli \-g CH1" " [...]"
.sp
.RB " $ " "sigrok\-cli \-d demo \-g Logic \-c pattern=graycode" " [...]"
+.sp
+Channel group specifications in
+.B \-\-get
+or
+.B \-\-config
+options take precedence over channel group names in
+.B \-\-channel\-group
+so that a single
+.B sigrok\-cli
+invocation can support the query or manipulation of multiple device options
+which reside in different channel groups.
.TP
.BR "\-t, \-\-triggers " <triggerlist>
A comma-separated list of triggers to use, of the form
$
.B "sigrok\-cli \-i <file.sr> "
.br
-.B " \-P uart:baudrate=115200:parity_type=odd"
+.B " \-P uart:baudrate=115200:parity=odd"
.sp
The list of supported options depends entirely on the protocol decoder. Every
protocol decoder has different options it supports.
.B wordsize
is an option supported by the
.B spi
-protocol decoder. Additionally, the user tells sigrok to decode the SPI
+protocol decoder. Additionally, the user requests 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.
.sp
-Notice that the
+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.
+application can automatically assign logic channels to decoder inputs
+in their strict channel index order (by means of the
+.B auto_index
+keyword), or can automatically assign logic channels to decoder inputs
+when their names match (case insensitive match,
+.B auto_names
+keyword). Users need to explicitly request this assignment, the default
+behaviour is to not automatically assign any signals.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr>"
+.br
+.B " \-P ieee488:assign_channels=auto_names"
.br
.sp
When multiple decoders are specified in the same
When given, decoder annotations will include sample numbers, too.
This allows consumers to receive machine readable timing information.
.TP
+.BR "\-\-protocol\-decoder\-ann\-class
+When given, decoder annotations will include annotation class names.
+.TP
+.BR "\-\-protocol\-decoder\-jsontrace
+When given, decoder output uses the Google Trace Event format (JSON).
+Which can be inspected in web browsers or other viewers.
+.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 \-\-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.
Get the value of
.B <variable>
from the specified device and print it.
+Multiple variable names can be specified and get separated by colon.
+The list of variable names optionally can be preceeded by
+.B "channel_group=<name>"
+which would override the
+.B \-\-channel\-group
+specification.
+Multiple
+.B \-\-get
+occurances are supported in a single
+.B sigrok\-cli
+invocation.
+.sp
+ $
+.B sigrok\-cli \-d demo \-\-get samplerate:averaging \-\-get channel_group=Logic:pattern
.TP
.BR "\-\-set"
Set one or more variables specified with the \fB\-\-config\fP option, without
.SH "EXIT STATUS"
.B sigrok\-cli
exits with 0 on success, 1 on most failures.
+.SH "ENVIRONMENT"
+.TP
+.B SIGROK_FIRMWARE_DIR
+A single path where to search for firmware images, in addition to a
+builtin list of locations.
+.TP
+.B SIGROK_FIRMWARE_PATH
+Multiple path entries where to search for firmware images, in addition
+to builtin locations.
+.TP
+When decoder support was enabled in the application's configuration:
+.TP
+.B SIGROKDECODE_DIR
+A single path where to search for protocol decoders, in addition to
+a builtin list of locations.
+.TP
+.B SIGROKDECODE_PATH
+Multiple path entries where to search for protocol decoders, in addition
+to builtin locations.
.SH "SEE ALSO"
\fBpulseview\fP(1)
.SH "BUGS"
projects / sigrok-cli.git / blobdiff