X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=b1592bd6ba8b36c855c18fe8ceba6444a94d7842;hp=ffbe06504b9374d4cfa50f8042e7a5aaa480f9e1;hb=ad6520c433602a426e4e55fec2d5aef8fe11a5b5;hpb=ec3d44c892c006baa6c2bf39017fc76181bbe8bf diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index ffbe065..b1592bd 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,4 +1,4 @@ -.TH SIGROK\-CLI 1 "Feb 05, 2013" +.TH SIGROK\-CLI 1 "May 04, 2014" .SH "NAME" sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" @@ -42,7 +42,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 @@ -119,33 +119,33 @@ will display 128 bits per line, in hexadecimal: 0:ffff ffff ffff ffff ffff ffff ffff ffff 1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 .sp -The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to +The lines always start with the channel number (or name, if defined), followed by a colon. If no format is specified, it defaults to .BR bits:width=64 , like this: .sp 0:11111111 11111111 11111111 11111111 [...] 1:11111111 00000000 11111111 00000000 [...] .TP -.BR "\-p, \-\-probes " -A comma-separated list of probes to be used in the session. +.BR "\-C, \-\-channels " +A comma-separated list of channels to be used in the session. .sp -Note that sigrok always names the probes according to how they're shown on -the enclosure of the hardware. If your logic analyzer numbers the probes 0-15, -that's how you must specify them with this option. An oscilloscope's probes +Note that sigrok always names the channels according to how they're shown on +the enclosure of the hardware. If your logic analyzer numbers the channels 0-15, +that's how you must specify them with this option. An oscilloscope's channels would generally be referred to as "CH1", "CH2", and so on. -Use the \fB\-\-show\fP option to see a list of probe names for your device. +Use the \fB\-\-show\fP option to see a list of channel names for your device. .sp -The default is to use all the probes available on a device. You can name -a probe like this: +The default is to use all the channels available on a device. You can name +a channel like this: .BR "1=CLK" . -A range of probes can also be given, in the form +A range of channels can also be given, in the form .BR "1\-5" . .sp 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,31 +155,21 @@ 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" -will set the name of probe 1 to +.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 probes 5 and 6, and set their names to MISO and MOSI, the -command line -.B "5=MOSI,6=MISO,1\-8" -will select probes 1\-8 (including 5 and 6, of course), but the names specified -for probes 5 and 6 will be reset to the defaults by the -.B "1\-8" -probe selection. -.TP -.BR "\-g, \-\-probe\-group " -Specify the probe group to operate on. +.TP +.BR "\-g, \-\-channel\-group " +Specify the channel group to operate on. -Some devices organize probes into groups, the settings of which can -only be changed as a group. The list of probe groups, if any, is displayed -with the \-\-show command. +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 \fB\-\-show\fP command. .TP .BR "\-t, \-\-triggers " A comma-separated list of triggers to use, of the form -.BR "=" . -You can use the name or number of the probe, and the trigger itself is a +.BR "=" . +You can use the name or number of the channel, and the trigger itself is a series of characters: .sp .BR "0 or 1" : @@ -223,28 +213,30 @@ of options, where each option takes the form Example: .sp $ -.B "sigrok\-cli \-i \-P uart:baudrate=115200:parity_type=odd" +.B "sigrok\-cli \-i " +.br +.B " \-P uart:baudrate=115200:parity_type=odd" .sp The list of supported options depends entirely on the protocol decoder. Every protocol decoder has different options it supports. .sp Any "options" specified for a protocol decoder which are not actually -supported options, will be interpreted as being probe name/number assignments. +supported options, will be interpreted as being channel name/number assignments. .sp Example: .sp $ .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 is an option supported by the .B spi protocol decoder. Additionally, the user tells sigrok to decode the SPI -protocol using probe 1 as MISO signal for SPI, probe 5 as MOSI, probe 3 -as SCK, and probe 0 as CS# signal. +protocol using channel 1 as MISO signal for SPI, channel 5 as MOSI, channel 3 +as CLK, 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. @@ -260,13 +252,13 @@ 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 +.B \-P parameter. .sp Example: .sp $ -.B "sigrok\-cli \-i \-A i2c:sda=4:scl=7,rtc8564" +.B "sigrok\-cli \-i \-P i2c:sda=4:scl=7,rtc8564" .br .B " \-S i2c,rtc8564" .sp @@ -281,7 +273,7 @@ i.e., the is stacked on top of the .BR i2c " decoder." .sp -The respective protocol decoder options and probe name/number assignments +The respective protocol decoder options and channel name/number assignments must be given using the .B \-P option (you cannot specify them in the @@ -296,21 +288,65 @@ display, by specifying its ID: $ .B "sigrok\-cli \-i \-P i2c,i2cfilter,edid -A i2c" .sp -If a protocol decoder has multiple annotation formats, you can also specify -which of them to show by specifying its short description like this: +If a protocol decoder has multiple annotations, you can also specify +which one of them to show by specifying its short description like this: .sp $ .B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" .br -.B " \-A i2c=rawhex" +.B " \-A i2c=data-read" +.sp +Select multiple annotations 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 format each, by separating them with commas: +annotation each, by separating them with commas: .sp $ .B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" .br -.B " \-A i2c=rawhex,edid" +.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 "\-l, \-\-loglevel " Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok-cli\fP @@ -343,10 +379,12 @@ 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 and output modules: .sp $ -.B "sigrok\-cli \-\-protocol-decoders i2c \-\-show +.B "sigrok\-cli \-\-protocol\-decoders i2c \-\-show + $ +.B "sigrok\-cli \-\-output\-format bits \-\-show .TP .B "\-\-scan" Scan for devices that can be detected automatically. @@ -358,13 +396,9 @@ Example: .br The following devices were found: .br - Demo device with 8 probes: 0 1 2 3 4 5 6 7 -.br - ChronoVu LA8 with 8 probes: 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 probes: Ch_0 Ch_1 -.br - Saleae Logic with 8 probes: 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. @@ -374,16 +408,15 @@ For those you'll have to provide a \fBconn\fP option, see above. .br The following devices were found: .br - Digitek DT4000ZC with 1 probe: P1 + Digitek DT4000ZC with 1 channel: P1 .TP .BR "\-\-time " 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" @@ -402,6 +435,11 @@ 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 @@ -422,12 +460,12 @@ Alternatively, you can also use: .TP .B " sigrok\-cli \-\-driver fx2lafw \-\-time 3s" .TP -To capture data from the first 4 probes using the Openbench Logic Sniffer lasting 100ms at 10 MHz starting at the trigger condition +To capture data from the first 4 channels using the Openbench Logic Sniffer lasting 100ms at 10 MHz starting at the trigger condition 0:high, 1:rising, 2:low, 3:high, use: .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: