X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=f44c35cc6e920300d7575d01a792e6a8cc2fe132;hp=e8d98b062db20ce05c11ae5fc338fa9a4997d142;hb=7c765fcb39bb3487eda4cac97811a165cf9dcddc;hpb=029d73fe03db2656ceb2ca0f5a3fea57393fdfda diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index e8d98b0..f44c35c 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,4 +1,4 @@ -.TH SIGROK\-CLI 1 "Jan 31, 2014" +.TH SIGROK\-CLI 1 "September 13, 2017" .SH "NAME" sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" @@ -22,12 +22,15 @@ Show a help text and exit. .B "\-V, \-\-version" Show .B sigrok-cli -version, and information about supported hardware drivers, input file +version and the versions of libraries used. +.TP +.B "\-L, \-\-list-supported" +Show information about supported hardware drivers, input file formats, output file formats, and protocol decoders. .TP \fB\-d, \-\-driver\fP A driver must always be selected (unless doing a global scan). Use the -\fB-V\fP option to get a list of available drivers. +\fB-L\fP option to get a list of available drivers. .sp Drivers can take options, in the form \fBkey=value\fP separated by colons. @@ -42,7 +45,7 @@ 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: .sp -.RB " $ " "sigrok\-cli \-\-driver=nexus-osciprime:conn=04b4.8613" +.RB " $ " "sigrok\-cli \-\-driver=uni-t-ut61e:conn=1a86.e008" .TP .BR "\-c, \-\-config " A colon-separated list of device options, where each option takes the form @@ -73,7 +76,7 @@ When loading an input file, assume it's in the specified format. If this option is not supplied (in addition to .BR \-\-input\-file ), sigrok-cli attempts to autodetect the file format of the input file. Use the -.B \-V +.B \-L option to see a list of available input formats. .sp The format name may optionally be followed by a colon-separated list of @@ -89,7 +92,7 @@ option. .TP .BR "\-O, \-\-output\-format " Set the output format to use. Use the -.B \-V +.B \-L option to see a list of available output formats. .sp The format name may optionally be followed by a colon-separated list of @@ -126,7 +129,7 @@ like this: 0:11111111 11111111 11111111 11111111 [...] 1:11111111 00000000 11111111 00000000 [...] .TP -.BR "\-p, \-\-probes " +.BR "\-C, \-\-channels " A comma-separated list of channels to be used in the session. .sp Note that sigrok always names the channels according to how they're shown on @@ -145,7 +148,7 @@ Example: .sp .RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-samples 100" .br -.B " \-\-probes 1=CLK,2\-4,7" +.B " \-\-channels 1=CLK,2\-4,7" .br CLK:11111111 11111111 11111111 11111111 [...] 2:11111111 11111111 11111111 11111111 [...] @@ -155,26 +158,16 @@ Example: .sp The comma-separated list is processed from left to right, i.e. items farther to the right override previous items. For example -.B "1=CS,1=MISO" +.B "1=CS,CS=MISO" will set the name of channel 1 to .BR "MISO" . -.sp -Also, while -.B "5=MOSI,6=MISO" -will only select channels 5 and 6, and set their names to MISO and MOSI, the -command line -.B "5=MOSI,6=MISO,1\-8" -will select channels 1\-8 (including 5 and 6, of course), but the names specified -for channels 5 and 6 will be reset to the defaults by the -.B "1\-8" -channel selection. .TP .BR "\-g, \-\-channel\-group " Specify the channel group to operate on. Some devices organize channels into groups, the settings of which can only be changed as a group. The list of channel groups, if any, is displayed -with the \-\-show command. +with the \fB\-\-show\fP command. .TP .BR "\-t, \-\-triggers " A comma-separated list of triggers to use, of the form @@ -191,7 +184,7 @@ A rising or falling value on the pin. An effectively corresponds to .BR 01 . .br -.BR "c" : +.BR "e" : Any kind of change on a pin (either a rising or a falling edge). .sp Not every device supports all of these trigger types. Use the \fB\-\-show\fP @@ -208,7 +201,7 @@ nonetheless). This option allows the user to specify a comma-separated list of protocol decoders to be used in this session. The decoders are specified by their ID, as shown in the -.B \-\-version +.B \-L output. .sp Example: @@ -238,7 +231,7 @@ Example: $ .B "sigrok\-cli \-i " .br -.B " \-P spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0" +.B " \-P spi:wordsize=9:miso=1:mosi=5:clk=3:cs=0" .sp In this example, .B wordsize @@ -246,49 +239,7 @@ is an option supported by the .B spi protocol decoder. Additionally, the user tells sigrok to decode the SPI protocol using channel 1 as MISO signal for SPI, channel 5 as MOSI, channel 3 -as SCK, and channel 0 as CS# signal. -.TP -.BR "\-S, \-\-protocol\-decoder\-stack " -This option allows the user to specify a protocol decoder stack, i.e. -the way in which one protocol decoder's output gets piped into another -protocol decoder. If not specified, the stack will be set up in the same -order in which the protocol decoders were given with the -.B \-\-protocol-decoders -option. -.sp -The decoders are specified by their ID, as shown in the -.B \-\-version -output. In addition to the -.B \-S -option, all protocol decoders that are used in a stack, must also be specified -(together with their options, if any) using the -.B \-A -parameter. -.sp -Example: -.sp - $ -.B "sigrok\-cli \-i \-A i2c:sda=4:scl=7,rtc8564" -.br -.B " \-S i2c,rtc8564" -.sp -In this example, the -.B \-S -option specifies that the output of the -.BR i2c " decoder" -is piped into the -.BR rtc8564 " decoder," -i.e., the -.BR rtc8564 " decoder" -is stacked on top of the -.BR i2c " decoder." -.sp -The respective protocol decoder options and channel name/number assignments -must be given using the -.B \-P -option (you cannot specify them in the -.B \-S -option). +as CLK, and channel 0 as CS# signal. .TP .BR "\-A, \-\-protocol\-decoder\-annotations " By default, only the stack's topmost protocol decoder's annotation output is @@ -321,6 +272,47 @@ annotation each, by separating them with commas: .br .B " \-A i2c=data-read:data-write,edid" .TP +.BR "\-M, \-\-protocol\-decoder\-meta " +When given, show protocol decoder meta output instead of annotations. +The argument is the name of the decoder whose meta output to show. +.sp + $ +.B "sigrok\-cli \-i \-M i2c" +.sp +Not every decoder generates meta output. +.TP +.BR "\-B, \-\-protocol\-decoder\-binary " +When given, decoder "raw" data of various kinds is written to stdout instead +of annotations (this could be raw binary UART/SPI bytes, or WAV files, PCAP +files, PNG files, or anything else; this is entirely dependent on the +decoder and what kinds of binary output make sense for that decoder). +.sp +No other information is printed to stdout, so this is +suitable for piping into other programs or saving to a file. +.sp +Protocol decoders that support binary output publish a list of binary +classes, for example the UART decoder might have "TX" and "RX". To +select TX for output, the argument to this option would be: +.sp + $ +.B "sigrok\-cli \-i \-B uart=tx" +.br +.sp +If only the protocol decoder is specified, without binary class, all classes +are written to stdout: +.sp + $ +.B "sigrok\-cli \-i \-B uart" +.sp +(this is only useful in rare cases, generally you would specify a certain +binary class you're interested in) +.sp +Not every decoder generates binary output. +.TP +.BR "\-\-protocol\-decoder\-samplenum +When given, decoder annotations will include sample numbers, too. +This allows consumers to receive machine readable timing information. +.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 @@ -352,10 +344,14 @@ need a serial port specified: $ .B "sigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-show .sp -To view the documentation for a protocol decoder: +This also works for protocol decoders, input modules and output modules: .sp $ -.B "sigrok\-cli \-\-protocol-decoders i2c \-\-show +.B "sigrok\-cli \-\-protocol\-decoders i2c \-\-show + $ +.B "sigrok\-cli \-\-input\-format csv \-\-show + $ +.B "sigrok\-cli \-\-output\-format bits \-\-show .TP .B "\-\-scan" Scan for devices that can be detected automatically. @@ -367,13 +363,9 @@ Example: .br The following devices were found: .br - Demo device with 8 channels: 0 1 2 3 4 5 6 7 -.br - ChronoVu LA8 with 8 channels: 0 1 2 3 4 5 6 7 + demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0 A1 A2 A3 .br - ALSA: HDA ATI SB ALC270 Analog with 2 channels: Ch_0 Ch_1 -.br - Saleae Logic with 8 channels: 0 1 2 3 4 5 6 7 + fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 0 1 2 3 4 5 6 7 .sp However, not all devices are auto-detectable (e.g. serial port based ones). For those you'll have to provide a \fBconn\fP option, see above. @@ -390,9 +382,8 @@ Sample for .B milliseconds, then quit. .sp -You can optionally follow the number by \fBs\fP, \fBms\fP, \fBus\fP, or -\fBns\fP to specify the time to sample in seconds, milliseconds, microseconds, -or nanoseconds, respectively. +You can optionally follow the number by \fBs\fP to specify the time to +sample in seconds. .sp For example, .B "\-\-time 2s" @@ -411,9 +402,19 @@ For example, .B "\-\-samples 3m" will acquire 3000000 samples. .TP +.BR "\-\-frames " +Acquire +.B +frames, then quit. +.TP .BR "\-\-continuous" Sample continuously until stopped. Not all devices support this. .TP +.BR "\-\-get " +Get the value of +.B +from the specified device and print it. +.TP .BR "\-\-set" Set one or more variables specified with the \fB\-\-config\fP option, without doing any acquisition. @@ -436,7 +437,7 @@ To capture data from the first 4 channels using the Openbench Logic Sniffer last .TP .nf \fBsigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-config samplerate=10m \\\fP -\fB\-\-output\-format bits \-\-probes 0\-3 \-\-wait\-trigger \\\fP +\fB\-\-output\-format bits \-\-channels 0\-3 \-\-wait\-trigger \\\fP \fB\-\-triggers 0=1,1=r,2=0,3=1 \-\-time 100\fP .TP To turn on internal logging on a Lascar EL-USB series device: