-.TH SIGROK\-CLI 1 "March 18, 2012"
+.TH SIGROK\-CLI 1 "May 29, 2012"
.SH "NAME"
sigrok\-cli \- Command-line client for the sigrok logic analyzer 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 \fR[\fB\-hVlDdiIoOptwas\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-l\fR|\fB\-\-loglevel\fR level] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-d\fR|\fB\-\-device\fR device] [\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\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-trigger\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR decoderlist] [\fB\-s\fR|\fB\-\-protocol\-decoder\-stack\fR stack] [\fB\-\-protocol\-decoder\-annotation\fR annlist] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]
.SH "DESCRIPTION"
.B sigrok\-cli
is a cross-platform command line utility for the
.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.
+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
version, and information about supported hardware drivers, input file
formats, output file formats, and protocol decoders.
.TP
+.BR "\-l, \-\-loglevel " <level>
+Set the libsigrok and libsigrokdecode loglevel. At the moment
+.B sigrok-cli
+doesn't support setting the two loglevels independently. The higher the
+number, the more debug output will be printed. Valid loglevels are
+.BR 0 " (NONE),"
+.BR 1 " (ERR),"
+.BR 2 " (WARN),"
+.BR 3 " (INFO),"
+.BR 4 " (DBG), and"
+.BR 5 " (SPEW)."
+.TP
.B "\-D, \-\-list\-devices"
List all logic analyzer devices found on the system. This actively scans for
devices (USB, serial port, and others).
.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 .
+.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""
+.TP
.BR "\-i, \-\-input\-file " <filename>
Load input from a file instead of a hardware device. If the
.B \-\-input\-format
.BR ascii ,
.BR binary ,
.BR vcd ,
-.BR ols ", and"
-.BR gnuplot .
+.BR ols ,
+.BR gnuplot ,
+.BR chronovu-la8 ", and"
+.BR csv .
.sp
The
.B bits
1:11111111 11111111 11111111 11111111 [...]
2:11111111 00000000 11111111 00000000 [...]
.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 .
-.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""
-.TP
.BR "\-p, \-\-probes " <probelist>
A comma-separated list of probes to be used in the session.
.sp
.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>"
that came before the trigger (but the logic analyzer 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
+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> \-a 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 <file.sr> \-a 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 <file.sr>"
+.br
+.B " \-a 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 " <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 \-a
+option (you cannot specify them in the
+.B \-s
+option).
+.TP
+.BR "\-\-protocol\-decoder\-annotation " <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> \-a i2c,i2cfilter,edid"
+.br
+.B " \-\-protocol\-decoder\-annotation 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> \-a i2c,i2cfilter,edid"
+.br
+.B " \-\-protocol\-decoder\-annotation 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> \-a i2c,i2cfilter,edid"
+.br
+.B " \-\-protocol\-decoder\-annotation i2c=rawhex,edid"
+.TP
.BR "\-\-time " <ms>
Sample for
.B <ms>
.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:
.TP
-.B " sigrok\-cli \-O bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\"
+.B " sigrok\-cli -d 0:samplerate=10m \-O bits \-p 1\-4 \-\-time 100 \\\\"
.B " \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 "
.SH "EXIT STATUS"
.B sigrok\-cli
projects / sigrok-cli.git / blobdiff