Update, fix, and extend manpage.
authorUwe Hermann <uwe@hermann-uwe.de>
Tue, 5 Feb 2013 17:23:02 +0000 (18:23 +0100)
committerUwe Hermann <uwe@hermann-uwe.de>
Tue, 5 Feb 2013 17:23:02 +0000 (18:23 +0100)
 - 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

index a562e81f1934881b21d22bf123f49ec1f9567707..58f86e734d272836818c1f4354e58ac60cb85b68 100644 (file)
@@ -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 <drivername>
-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 " <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 " <filename>
@@ -80,9 +90,10 @@ option.
 .BR "\-O, \-\-output\-format " <formatname>
 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 " <probelist>
 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 " <list>
 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 " <level>
-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 " <ms>
 Sample for
 .B <ms>
-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 <numsamples>
 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