-.TH SIGROK\-CLI 1 "January 19, 2011"
+.TH SIGROK\-CLI 1 "March 18, 2012"
.SH "NAME"
sigrok\-cli \- Command-line client for the sigrok logic analyzer 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\-O\fR|\fB\-\-output-format\fR format] [\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 list] [\fB\-s\fR|\fB\-\-protocol\-decoder\-stack\fR stack] [\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
save them in various file formats.
.SH "OPTIONS"
.TP
-.B "\-V, \-\-version"
-Show version, driver and module information.
-.TP
.B "\-h, \-\-help"
Show a help text and exit.
.TP
-.B "\-D, \-\-list\-devices"
-List all logic analyzer devices found on the system.
-.TP
-.BR "\-i, \-\-input\-file " <filename>
-Load input from a file instead of a device. If the
-.B \-\-input\-format
-option is not supplied, sigrok-cli attempts to autodetect the file format of
-the input file.
+.B "\-V, \-\-version"
+Show
+.B sigrok-cli
+version, and information about supported hardware drivers, input file
+formats, output file formats, and protocol decoders.
.TP
-.BR "\-I, \-\-input\-format " <format>
-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.
+.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
-.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 \-\-output\-format
-option, below.
+.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
.sp
.RB " $ " "sigrok\-cli \-d 0:samplerate=1m"
.sp
-Samplerate is a option common to most devices. The argument specifies the
+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
.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
+option is not supplied, sigrok-cli attempts to autodetect the file format of
+the input file.
+.TP
+.BR "\-I, \-\-input\-format " <format>
+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.
+.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 \-\-output\-format
+option.
+.TP
+.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
+.BR "key=value" .
+.sp
+Supported formats currently include
+.BR bits ,
+.BR hex ,
+.BR ascii ,
+.BR binary ,
+.BR vcd ,
+.BR ols ,
+.BR gnuplot ,
+.BR chronovu-la8 ", and"
+.BR csv .
+.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:
+.sp
+ 1:ffff ffff ffff ffff ffff ffff ffff ffff
+ 2: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 "\-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 "\-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
+.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
-Supported formats currently include
-.BR bits ,
-.BR hex ,
-.BR ascii ,
-.BR binary ,
-.BR vcd ,
-.BR ols ", and"
-.BR gnuplot .
+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> \-a 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
- 1:11111111 11111111 11111111 11111111 [...]
- 2:11111111 00000000 11111111 00000000 [...]
+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.
+.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 "\-\-time " <ms>
Sample for
.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 \-f 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