X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=4258009bd7a507b282911d78a2bdf6d2e50a82c5;hp=0990534a7c4c87e35d725fd71fd4d3078d65bb15;hb=HEAD;hpb=87d526cf9c6adad817fee8f6d28597222cac91e3 diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index 0990534..33174cd 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,4 +1,4 @@ -.TH SIGROK\-CLI 1 "October 22, 2018" +.TH SIGROK\-CLI 1 "April 07, 2023" .SH "NAME" sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" @@ -28,9 +28,17 @@ version and the versions of libraries used. 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 -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 @@ -43,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 @@ -54,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 @@ -71,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 @@ -196,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 @@ -246,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. @@ -265,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 @@ -307,7 +365,7 @@ display, by specifying the decoder ID: $ .B "sigrok\-cli \-i \-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 $ @@ -315,15 +373,24 @@ which one of them to show by specifying its short description like this: .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 \-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 \-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 \-P i2c,i2cfilter,edid" @@ -371,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 @@ -410,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. @@ -472,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 @@ -505,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"