From 10d98b47bfc37a898b09224fdf9264c37a84c04e Mon Sep 17 00:00:00 2001 From: Uwe Hermann Date: Tue, 5 Feb 2013 18:23:02 +0100 Subject: [PATCH] Update, fix, and extend manpage. - Probe indices start at 0 now (not 1). - Update manpage date. - Mention the 'analog' output format. - Various smaller cosmetic fixes. - Add more examples for some options. - Document all possible suffixes for --time/--samples values. - Mention the PulseView(1) manpage in "SEE ALSO". - Mention Bugzilla for bugreports. --- doc/sigrok-cli.1 | 136 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 101 insertions(+), 35 deletions(-) diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index a562e81..58f86e7 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,14 +1,15 @@ -.TH SIGROK\-CLI 1 "May 29, 2012" +.TH SIGROK\-CLI 1 "Feb 05, 2013" .SH "NAME" sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" .B sigrok\-cli [OPTIONS] [COMMAND] .SH "DESCRIPTION" -\fBsigrok\-cli\fP is a cross-platform command line utility for the \fBsigrok\fP 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 decoding 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 @@ -25,21 +26,29 @@ version, and information about supported hardware drivers, input file formats, output file formats, and protocol decoders. .TP \fB\-\-driver\fP -A driver must always be selected. Use the \fB-V\fP option to get a list of available drivers. Drivers can take options, in the form \fBkey=value\fP separated by colons. +A driver must always be selected. Use the \fB-V\fP option to get a list of +available drivers. .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: +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: +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 "\-d, \-\-device " A colon-separated list of device options, where each option takes the form .BR key=value . -For example, to set the samplerate on a device supported by the fx2lafw -driver, you might specify +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 \-\-device samplerate=1m" .sp @@ -65,9 +74,10 @@ 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 -option to see a list of available input 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 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 " @@ -80,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 @@ -93,8 +104,9 @@ Supported formats currently include .BR vcd , .BR ols , .BR gnuplot , -.BR chronovu-la8 ", and" -.BR csv . +.BR chronovu-la8 , +.BR csv ", and" +.BR analog . .sp The .B bits @@ -104,20 +116,24 @@ 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 [...] + 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. +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: @@ -127,8 +143,9 @@ A range of probes can also be given, in the form .sp Example: .sp - $ -.B "sigrok\-cli \-\-driver fx2lafw \-\-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 [...] @@ -170,10 +187,15 @@ effectively corresponds to .BR "c" : 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 command 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 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 hardware delivers this data to sigrok nonetheless). +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 hardware delivers this data to sigrok +nonetheless). .TP .BR "\-a, \-\-protocol\-decoders " This option allows the user to specify a comma-separated list of protocol @@ -284,7 +306,8 @@ annotation format each, by separating them with commas: .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 +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 @@ -301,12 +324,14 @@ number, the more debug output will be printed. Valid loglevels are: .TP .B "\-\-show" .br -Show information about the selected option. For example, to see options for a connected fx2lafw device: +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: +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 @@ -317,14 +342,44 @@ To view the documentation for a protocol decoder: .B "sigrok\-cli \-\-protocol-decoders i2c \-\-show .TP .B "\-D, \-\-list\-devices" -List all devices found on the system. This actively scans for devices that can be detected automatically. +List all devices found on the system. This actively scans for devices that +can be detected automatically. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-D +.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 \-D +.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 @@ -332,6 +387,14 @@ 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. @@ -360,10 +423,13 @@ To capture data from the first 4 probes using the Openbench Logic Sniffer lastin .B sigrok\-cli exits with 0 on success, 1 on most failures. .SH "SEE ALSO" +\fBpulseview\fP(1), \fBsigrok\-qt\fP(1), \fBsigrok\-gtk\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 -- 2.30.2