Adjust to libsigrokdecode API changes
[sigrok-cli.git] / doc / sigrok-cli.1
index bbd138de82c0d39be7c37b0b4114f4ab8a3c7ae2..8437d91f3b76ef0ea84fb25ddb5fa93c994052a3 100644 (file)
@@ -1,34 +1,69 @@
-.TH SIGROK\-CLI 1 "January 19, 2011"
+.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\-hVDiIodptwaf\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\-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\-f\fR|\fB\-\-format\fR format] [\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"
-.TP
-.B "\-V, \-\-version"
-Show version, driver and module information.
+.SH OPTIONS
 .TP
 .B "\-h, \-\-help"
 Show a help text and exit.
 .TP
-.B "\-D, \-\-list\-devices"
-List all logic analyzer devices found on the system.
+.B "\-V, \-\-version"
+Show
+.B sigrok-cli
+version, and information about supported hardware drivers, input file
+formats, output file formats, and protocol decoders.
+.TP
+\fB\-d, \-\-driver\fP <drivername>
+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 " <device>
+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 " <filename>
-Load input from a file instead of a device. If the
+Load input from a file instead of a hardware device. If the
 .B \-\-input\-format
 option is not supplied, sigrok-cli attempts to autodetect the file format of
 the input file.
@@ -37,41 +72,69 @@ 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 " <filename>
 Save output to a file instead of writing it to stdout. The default format
 used when saving is the sigrok session file format. This can be changed with
 the
-.B \-\-format
-option, below.
+.B \-\-output\-format
+option.
 .TP
-.BR "\-d, \-\-device " <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 .
+.BR "\-O, \-\-output\-format " <formatname>
+Set the output format to use. Use the
+.B \-V
+option to see a list of available output formats.
 .sp
-A device can optionally be followed by a colon-separated list of device
+The format name may optionally be followed by a colon-separated list of
 options, where each option takes the form
-.BR key=value .
-For example, to set the samplerate on the first device you might specify
+.BR "key=value" .
 .sp
-.RB "  $ " "sigrok\-cli \-d 0:samplerate=1m"
+Supported formats currently include
+.BR bits ,
+.BR hex ,
+.BR ascii ,
+.BR binary ,
+.BR vcd ,
+.BR ols ,
+.BR gnuplot ,
+.BR chronovu-la8 ,
+.BR csv ", and"
+.BR analog .
 .sp
-Samplerate is a 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:
+The
+.B bits
+or
+.B hex
+formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" option, specifying the number of samples (in bits) to display per line. Thus
+.B hex:width=128
+will display 128 bits per line, in hexadecimal:
 .sp
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000"
+ 0:ffff ffff ffff ffff ffff ffff ffff ffff
+ 1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
 .sp
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m"
+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
-.RB "  $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz""
+ 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.
+.sp
 The default is to use all the probes available on a device. You can name
 a probe like this:
 .BR "1=CLK" .
@@ -80,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 [...]
@@ -121,61 +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 <device>"
-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 "\-f, \-\-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
+.BR "\-P, \-\-protocol\-decoders " <list>
+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 <file.sr> \-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
-Supported formats currently include
-.BR bits ,
-.BR hex ,
-.BR ascii ,
-.BR binary ,
-.BR vcd ,
-.BR ols ,
-.BR gnuplot ", and"
-.BR analog .
+Example:
 .sp
-The
-.B bits
-or
-.B hex
-formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" option, specifying the number of samples (in bits) to display per line. Thus
-.B hex:width=128
-will display 128 bits per line, in hexadecimal:
+ $
+.B "sigrok\-cli \-i <file.sr> \-P uart:baudrate=115200:parity=odd"
 .sp
- 1:ffff ffff ffff ffff ffff ffff ffff ffff
- 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
+The list of supported options depends entirely on the protocol decoder. Every
+protocol decoder has different options it supports.
 .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:
+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 <file.sr>"
+.br
+.B "              \-P spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0"
 .sp
- 1:11111111 11111111 11111111 11111111 [...]
- 2:11111111 00000000 11111111 00000000 [...]
+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 " <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 <file.sr> \-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 " <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 <file.sr> \-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 <file.sr> \-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 <file.sr> \-P i2c,i2cfilter,edid"
+.br
+.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
+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 " <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
@@ -183,35 +386,56 @@ 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.
-.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
+.B "  sigrok\-cli \-\-driver fx2lafw \-\-samples 100"
 .TP
-If you want to sample data for 3 seconds, use:
+If you want to sample data for 3 seconds (3000 ms), use:
 .TP
-.B "  sigrok\-cli \-\-time 3000"
+.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 \-f 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