doc: update sigrok-cli(1) for channel assignment to decoder inputs

[sigrok-cli.git] / doc / sigrok-cli.1

diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1
index 3ec6768e57484a43d3e9d252a348cda99594f7f2..33174cdbe4a6ec545e48a370bb4efd7cb52d0ee5 100644 (file)
--- a/doc/sigrok-cli.1
+++ b/doc/sigrok-cli.1
@@ -1,4 +1,4 @@
-.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"
@@ -72,6 +72,17 @@ specification.
 .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
@@ -86,6 +97,15 @@ The following are all equivalent:
 .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
@@ -211,6 +231,17 @@ Examples:
 .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
@@ -261,7 +292,7 @@ Example:
  $
 .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.
@@ -280,15 +311,27 @@ In this example,
 .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
@@ -395,6 +438,13 @@ Not every decoder generates binary output.
 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
@@ -503,6 +553,20 @@ Sample continuously until stopped. Not all devices support this.
 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
@@ -536,6 +600,25 @@ To turn on internal logging on a Lascar EL-USB series device:
 .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"