X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=4258009bd7a507b282911d78a2bdf6d2e50a82c5;hp=54fb285227826ee6d080c6bf7019c0cdb7f43dae;hb=HEAD;hpb=b7360ee68139ab6377876ba72e2a9fd56135db7f diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index 54fb285..33174cd 100644 --- 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" @@ -34,7 +34,10 @@ 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 -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 @@ -48,8 +51,10 @@ Openbench Logic Sniffer: .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 @@ -59,9 +64,25 @@ USB \fBbus.address\fP example: .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 " 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= +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 @@ -76,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 " Load input from a file instead of a hardware device. You can specify @@ -201,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 " A comma-separated list of triggers to use, of the form @@ -251,7 +292,7 @@ Example: $ .B "sigrok\-cli \-i " .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. @@ -270,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 " +.br +.B " \-P ieee488:assign_channels=auto_names" .br .sp When multiple decoders are specified in the same @@ -385,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 " Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok\-cli\fP doesn't support setting the two loglevels independently. The higher the @@ -424,6 +484,13 @@ This also works for protocol decoders, input modules and output modules: .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 \-\-show + $ +.B "sigrok\-cli \-\-input\-file \-\-input\-format vcd \-\-show .TP .B "\-\-scan" Scan for devices that can be detected automatically. @@ -486,6 +553,20 @@ Sample continuously until stopped. Not all devices support this. Get the value of .B 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=" +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 @@ -519,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"