X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=8437d91f3b76ef0ea84fb25ddb5fa93c994052a3;hp=2150a8451ddb6ba2b2803e18bdefadd414c12a42;hb=d80c8dd0c8b6a7507ff8e16ba46734da394acecf;hpb=7949dca0e7c6e4e5ff285733eaf5b957ba32504f diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index 2150a84..8437d91 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,22 +1,20 @@ -.TH SIGROK\-CLI 1 "March 18, 2012" +.TH SIGROK\-CLI 1 "Feb 05, 2013" .SH "NAME" -sigrok\-cli \- Command-line client for the sigrok logic analyzer software +sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" -.B sigrok\-cli \fR[\fB\-hVDiIoOdptwa\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-triggers\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR sequence] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR] +.B sigrok\-cli [OPTIONS] [COMMAND] .SH "DESCRIPTION" -.B sigrok\-cli -is a cross-platform command line utility for the -.B sigrok -logic analyzer software. +\fBsigrok\-cli\fP is a cross-platform command line utility for the +\fBsigrok\fP software. .PP -The command-line frontend for sigrok cannot display graphical output, but is -still sufficient to run through the whole process of hardware initialization, -acquisition, protocol analysis and saving the session. +It cannot display graphical output, but is still sufficient to run through +the whole process of hardware initialization, acquisition, protocol decoding +and saving the session. .PP It is useful for running on remote or embedded systems, netbooks, PDAs, and for various other use-cases. It can display samples on standard output or save them in various file formats. -.SH "OPTIONS" +.SH OPTIONS .TP .B "\-h, \-\-help" Show a help text and exit. @@ -27,9 +25,42 @@ Show version, and information about supported hardware drivers, input file formats, output file formats, and protocol decoders. .TP -.B "\-D, \-\-list\-devices" -List all logic analyzer devices found on the system. This actively scans for -devices (USB, serial port, and others). +\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. +.sp +Drivers can take options, in the form \fBkey=value\fP +separated by colons. +.sp +Drivers communicating with hardware via a serial port always need the port +specified as the \fBconn\fP option. For example, to use the +Openbench Logic Sniffer: +.sp +.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: +.sp +.RB " $ " "sigrok\-cli \-\-driver=nexus-osciprime:conn=04b4.8613" +.TP +.BR "\-c, \-\-config " +A colon-separated list of device options, where each option takes the form +.BR key=value . +For example, to set the samplerate to 1MHz on a device supported by the +fx2lafw driver, you might specify +.sp +.RB " $ " "sigrok\-cli \-\-driver=fx2lafw \-\-config samplerate=1m" +.sp +Samplerate is an option common to most logic analyzers. The argument specifies +the samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. +The following are all equivalent: +.sp +.RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-config samplerate=1000000" +.sp +.RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-config samplerate=1m" +.sp +.RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-config \(dqsamplerate=1 MHz\(dq" .TP .BR "\-i, \-\-input\-file " Load input from a file instead of a hardware device. If the @@ -41,7 +72,13 @@ the input file. 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. +sigrok-cli attempts to autodetect the file format of the input file. Use the +.B \-V +option to see a list of available input formats. +.sp +The format name may optionally be followed by a colon-separated list of +options, where each option takes the form +.BR "key=value" . .TP .BR "\-o, \-\-output\-file " Save output to a file instead of writing it to stdout. The default format @@ -53,9 +90,10 @@ option. .BR "\-O, \-\-output\-format " Set the output format to use. Use the .B \-V -option to see a list of available output formats. The format name may -optionally be followed by a colon-separated list of options, where each -option takes the form +option to see a list of available output formats. +.sp +The format name may optionally be followed by a colon-separated list of +options, where each option takes the form .BR "key=value" . .sp Supported formats currently include @@ -64,8 +102,11 @@ Supported formats currently include .BR ascii , .BR binary , .BR vcd , -.BR ols ", and" -.BR gnuplot . +.BR ols , +.BR gnuplot , +.BR chronovu-la8 , +.BR csv ", and" +.BR analog . .sp The .B bits @@ -75,42 +116,25 @@ formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" optio .B hex:width=128 will display 128 bits per line, in hexadecimal: .sp - 1:ffff ffff ffff ffff ffff ffff ffff ffff - 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 + 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 .BR bits:width=64 , like this: .sp - 1:11111111 11111111 11111111 11111111 [...] - 2:11111111 00000000 11111111 00000000 [...] -.TP -.BR "\-d, \-\-device " -The device to use for acquisition. It can be specified by ID as reported by -.BR "\-\-list\-devices" , -or by the name of the driver as reported by -.BR \-\-version . -.sp -A device can optionally be followed by a colon-separated list of device -options, where each option takes the form -.BR key=value . -For example, to set the samplerate on the first device you might specify -.sp -.RB " $ " "sigrok\-cli \-d 0:samplerate=1m" -.sp -Samplerate is an option common to most devices. The argument specifies the -samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. -The following are all equivalent: -.sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000" -.sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m" -.sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz"" + 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. .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 +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. +.sp The default is to use all the probes available on a device. You can name a probe like this: .BR "1=CLK" . @@ -119,8 +143,9 @@ A range of probes can also be given, in the form .sp Example: .sp - $ -.B "sigrok\-cli \-\-samples 100 \-\-probes 1=CLK,2\-4,7" +.RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-samples 100" +.br +.B " \-\-probes 1=CLK,2\-4,7" .br CLK:11111111 11111111 11111111 11111111 [...] 2:11111111 11111111 11111111 11111111 [...] @@ -160,25 +185,200 @@ effectively corresponds to .BR 01 . .br .BR "c" : -Any kind of change on a pin. +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 -.B "\-d " -argument (with no other arguments) to see which triggers your device supports. +Not every device supports all of these trigger types. Use the \fB\-\-show\fP +command to see which triggers your device supports. .TP .BR "\-w, \-\-wait-trigger" -Don't output any sample data (even if it's actually received from the logic -analyzer) before the trigger condition is met. In other words, do not output +Don't output any sample data (even if it's actually received from the +hardware) before the trigger condition is met. In other words, do not output any pre-trigger data. This option is useful if you don't care about the data -that came before the trigger (but the logic analyzer hardware delivers this -data to sigrok nonetheless). +that came before the trigger (but the hardware delivers this data to sigrok +nonetheless). +.TP +.BR "\-P, \-\-protocol\-decoders " +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 +output. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-i \-P i2c" +.sp +Each protocol decoder can optionally be followed by a colon-separated list +of options, where each option takes the form +.BR "key=value" . +.sp +Example: +.sp + $ +.B "sigrok\-cli \-i \-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. +.sp +Any "options" specified for a protocol decoder which are not actually +supported options, will be interpreted as being probe name/number assignments. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-i " +.br +.B " \-P spi:wordsize=9:miso=1:mosi=5:sck=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. +.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 probe name/number assignments +must be given using the +.B \-P +option (you cannot specify them in the +.B \-S +option). +.TP +.BR "\-A, \-\-protocol\-decoder\-annotations " +By default, only the stack's topmost protocol decoder's annotation output is +shown. With this option another decoder's annotation can be selected for +display, by specifying its ID: +.sp + $ +.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: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" +.br +.B " \-A i2c=rawhex" +.sp +You can also select multiple protocol decoders, with an optional selected +annotation format each, by separating them with commas: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" +.br +.B " \-A i2c=rawhex,edid" +.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 +number, the more debug output will be printed. Valid loglevels are: +.sp +\fB0\fP None +.br +\fB1\fP Error +.br +\fB2\fP Warnings +.br +\fB3\fP Informational +.br +\fB4\fP Debug +.br +\fB5\fP Spew +.TP +.B "\-\-show" +.br +Show information about the selected option. For example, to see options for a +connected fx2lafw device: +.sp + $ +.B "sigrok\-cli \-\-driver fx2lafw \-\-show +.sp +In order to properly get device options for your hardware, some drivers might +need a serial port specified: +.sp + $ +.B "sigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-show +.sp +To view the documentation for a protocol decoder: +.sp + $ +.B "sigrok\-cli \-\-protocol-decoders i2c \-\-show +.TP +.B "\-\-scan" +Scan for devices that can be detected automatically. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-\-scan +.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 +.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 +.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. +.sp + $ +.B "sigrok\-cli \-\-driver digitek-dt4000zc:conn=/dev/ttyUSB0 \-\-scan +.br + The following devices were found: +.br + Digitek DT4000ZC with 1 probe: P1 .TP .BR "\-\-time " Sample for .B -milliseconds, then quit. You can optionally follow the number by -.B s -to state the number of seconds to sample instead. For example, +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. +.sp +For example, .B "\-\-time 2s" will sample for two seconds. .TP @@ -186,35 +386,56 @@ will sample for two seconds. Acquire .B samples, then quit. +.sp +You can optionally follow the number by \fBk\fP, \fBm\fP, or \fBg\fP to +specify the number of samples in kilosamples, megasamples, or gigasamples, +respectively. +.sp +For example, +.B "\-\-samples 3m" +will acquire 3000000 samples. .TP .BR "\-\-continuous" Sample continuously until stopped. Not all devices support this. -.SH "EXAMPLES" -In order to get exactly 100 samples from the (only) detected logic analyzer -hardware, run the following command: .TP -.B " sigrok\-cli \-\-samples 100" +.BR "\-\-set" +Set one or more variables specified with the \fB\-\-config\fP option, without +doing any acquisition. +.SH EXAMPLES +In order to get exactly 100 samples from the connected fx2lafw-supported logic +analyzer hardware, run the following command: .TP -If you want to sample data for 3 seconds, use: +.B " sigrok\-cli \-\-driver fx2lafw \-\-samples 100" .TP -.B " sigrok\-cli \-\-time 3000" +If you want to sample data for 3 seconds (3000 ms), use: +.TP +.B " sigrok\-cli \-\-driver fx2lafw \-\-time 3000" .TP Alternatively, you can also use: .TP -.B " sigrok\-cli \-\-time 3s" +.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 +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\-\-triggers 0=1,1=r,2=0,3=1 \-\-time 100\fP .TP -To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use: +To turn on internal logging on a Lascar EL-USB series device: .TP -.B " sigrok\-cli \-O bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\" -.B " \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 " +\fBsigrok\-cli \-\-driver lascar\-el\-usb:conn=10c4.0002 \\\fP +\fB\-\-config datalog=on \-\-set\fP .SH "EXIT STATUS" .B sigrok\-cli exits with 0 on success, 1 on most failures. .SH "SEE ALSO" -\fBsigrok\-qt\fP(1), -\fBsigrok\-gtk\fP(1) +\fBpulseview\fP(1) .SH "BUGS" -Please report any bugs on the sigrok\-devel mailing list +Please report any bugs via Bugzilla +.RB "(" http://sigrok.org/bugzilla ")" +or on the sigrok\-devel mailing list .RB "(" sigrok\-devel@lists.souceforge.net ")." .SH "LICENSE" .B sigrok\-cli