Provided by: sigrok-cli_0.4.0-2_amd64 bug

NAME

       sigrok-cli - Command-line client for the sigrok software

SYNOPSIS

       sigrok-cli [OPTIONS] [COMMAND]

DESCRIPTION

       sigrok-cli is a cross-platform command line utility for the sigrok software.

       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.

       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.

OPTIONS

       -h, --help
              Show a help text and exit.

       -V, --version
              Show sigrok-cli version, and information about supported  hardware  drivers,  input
              file formats, output file formats, and protocol decoders.

       -d, --driver <drivername>
              A driver must always be selected (unless doing a global scan). Use the -V option to
              get a list of available drivers.

              Drivers can take options, in the form key=value separated by colons.

              Drivers communicating with  hardware  via  a  serial  port  always  need  the  port
              specified as the conn option. For example, to use the Openbench Logic Sniffer:

                $ sigrok-cli --driver=ols:conn=/dev/ttyACM0

              Some  USB  devices don't use a unique VendorID/ProductID combination, and thus need
              that  specified  as  well.  This  also  uses  the   conn   option,   using   either
              VendorID.ProductID or bus.address:

                $ sigrok-cli --driver=nexus-osciprime:conn=04b4.8613

       -c, --config <device>
              A  colon-separated  list  of  device  options,  where  each  option  takes the form
              key=value.  For example, to set the samplerate to 1MHz on a device supported by the
              fx2lafw driver, you might specify

                $ sigrok-cli --driver=fx2lafw --config samplerate=1m

              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:

                $ sigrok-cli --driver fx2lafw --config samplerate=1000000

                $ sigrok-cli --driver fx2lafw --config samplerate=1m

                $ sigrok-cli --driver fx2lafw --config "samplerate=1 MHz"

       -i, --input-file <filename>
              Load  input  from a file instead of a hardware device. If the --input-format option
              is not supplied, sigrok-cli attempts to autodetect the file  format  of  the  input
              file.

       -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 --input-file), sigrok-cli attempts to  autodetect  the
              file  format  of the input file. Use the -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 key=value.

       -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
              --output-format option.

       -O, --output-format <formatname>
              Set  the  output format to use. Use the -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 key=value.

              Supported  formats  currently  include bits, hex, ascii, binary, vcd, ols, gnuplot,
              chronovu-la8, csv, and analog.

              The bits or 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 hex:width=128 will display 128 bits per line, in hexadecimal:

               0:ffff ffff ffff ffff ffff ffff ffff ffff
               1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00

              The lines always start with the probe number (or name, if defined), followed  by  a
              colon. If no format is specified, it defaults to bits:width=64, like this:

               0:11111111 11111111 11111111 11111111 [...]
               1:11111111 00000000 11111111 00000000 [...]

       -p, --probes <probelist>
              A comma-separated list of probes to be used in the session.

              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 --show option to  see
              a list of probe names for your device.

              The  default  is  to use all the probes available on a device. You can name a probe
              like this: 1=CLK.  A range of probes can also be given, in the form 1-5.

              Example:

                $ sigrok-cli --driver fx2lafw --samples 100
                             --probes 1=CLK,2-4,7
               CLK:11111111 11111111 11111111 11111111 [...]
                 2:11111111 11111111 11111111 11111111 [...]
                 3:11111111 11111111 11111111 11111111 [...]
                 4:11111111 11111111 11111111 11111111 [...]
                 7:11111111 11111111 11111111 11111111 [...]

              The comma-separated list is processed from left to right, i.e. items farther to the
              right override previous items. For example 1=CS,1=MISO will set the name of probe 1
              to MISO.

              Also, while 5=MOSI,6=MISO will only select probes 5 and 6, and set their  names  to
              MISO and MOSI, the command line 5=MOSI,6=MISO,1-8 will select probes 1-8 (including
              5 and 6, of course), but the names specified for probes 5 and 6 will  be  reset  to
              the defaults by the 1-8 probe selection.

       -t, --triggers <triggerlist>
              A  comma-separated list of triggers to use, of the form <probe>=<trigger>.  You can
              use the name or number of the  probe,  and  the  trigger  itself  is  a  series  of
              characters:

              0 or 1: A low or high value on the pin.
              r or f: A rising or falling value on the pin. An r effectively corresponds to 01.
              c: Any kind of change on a pin (either a rising or a falling edge).

              Not every device supports all of these trigger types. Use the --show command to see
              which triggers your device supports.

       -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).

       -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
              --version output.

              Example:

               $ sigrok-cli -i <file.sr> -P i2c

              Each  protocol  decoder  can  optionally  be  followed by a colon-separated list of
              options, where each option takes the form key=value.

              Example:

               $ sigrok-cli -i <file.sr> -P uart:baudrate=115200:parity=odd

              The list of supported options depends  entirely  on  the  protocol  decoder.  Every
              protocol decoder has different options it supports.

              Any  "options"  specified  for  a protocol decoder which are not actually supported
              options, will be interpreted as being probe name/number assignments.

              Example:

               $ sigrok-cli -i <file.sr>
                            -P spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0

              In this example, wordsize is an option  supported  by  the  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.

       -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 --protocol-decoders option.

              The  decoders  are  specified  by  their  ID,  as shown in the --version output. In
              addition to the -S option, all protocol decoders that are used  in  a  stack,  must
              also be specified (together with their options, if any) using the -A parameter.

              Example:

               $ sigrok-cli -i <file.sr> -A i2c:sda=4:scl=7,rtc8564
                            -S i2c,rtc8564

              In  this  example,  the  -S  option specifies that the output of the i2c decoder is
              piped into the rtc8564 decoder, i.e., the rtc8564 decoder is stacked on top of  the
              i2c decoder.

              The  respective  protocol decoder options and probe name/number assignments must be
              given using the -P option (you cannot specify them in the -S option).

       -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:

               $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid -A i2c

              If a protocol decoder has multiple annotation formats, you can also  specify  which
              of them to show by specifying its short description like this:

               $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
                            -A i2c=rawhex

              You  can  also  select  multiple  protocol  decoders,  with  an  optional  selected
              annotation format each, by separating them with commas:

               $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
                            -A i2c=rawhex,edid

       -l, --loglevel <level>
              Set the libsigrok and libsigrokdecode loglevel. At the  moment  sigrok-cli  doesn't
              support  setting  the  two loglevels independently. The higher the number, the more
              debug output will be printed. Valid loglevels are:

              0   None
              1   Error
              2   Warnings
              3   Informational
              4   Debug
              5   Spew

       --show
              Show information about the selected option. For  example,  to  see  options  for  a
              connected fx2lafw device:

               $ sigrok-cli --driver fx2lafw --show

              In  order to properly get device options for your hardware, some drivers might need
              a serial port specified:

               $ sigrok-cli --driver ols:conn=/dev/ttyACM0 --show

              To view the documentation for a protocol decoder:

               $ sigrok-cli --protocol-decoders i2c --show

       --scan Scan for devices that can be detected automatically.

              Example:

               $ sigrok-cli --scan
               The following devices were found:
               Demo device with 8 probes: 0 1 2 3 4 5 6 7
               ChronoVu LA8 with 8 probes: 0 1 2 3 4 5 6 7
               ALSA: HDA ATI SB ALC270 Analog with 2 probes: Ch_0 Ch_1
               Saleae Logic with 8 probes: 0 1 2 3 4 5 6 7

              However, not all devices are auto-detectable (e.g. serial port  based  ones).   For
              those you'll have to provide a conn option, see above.

               $ sigrok-cli --driver digitek-dt4000zc:conn=/dev/ttyUSB0 --scan
               The following devices were found:
               Digitek DT4000ZC with 1 probe: P1

       --time <ms>
              Sample for <ms> milliseconds, then quit.

              You  can  optionally  follow  the number by s, ms, us, or ns to specify the time to
              sample in seconds, milliseconds, microseconds, or nanoseconds, respectively.

              For example, --time 2s will sample for two seconds.

       --samples <numsamples>
              Acquire <numsamples> samples, then quit.

              You can optionally follow the number by k, m, or g to specify the number of samples
              in kilosamples, megasamples, or gigasamples, respectively.

              For example, --samples 3m will acquire 3000000 samples.

       --continuous
              Sample continuously until stopped. Not all devices support this.

       --set  Set  one  or  more  variables specified with the --config option, without doing any
              acquisition.

EXAMPLES

       In order to get exactly 100 samples from the connected  fx2lafw-supported  logic  analyzer
       hardware, run the following command:

         sigrok-cli --driver fx2lafw --samples 100

       If you want to sample data for 3 seconds (3000 ms), use:

         sigrok-cli --driver fx2lafw --time 3000

       Alternatively, you can also use:

         sigrok-cli --driver fx2lafw --time 3s

       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:

       sigrok-cli --driver ols:conn=/dev/ttyACM0 --config samplerate=10m \
              --output-format bits --probes 0-3 --wait-trigger \
              --triggers 0=1,1=r,2=0,3=1 --time 100

       To turn on internal logging on a Lascar EL-USB series device:

       sigrok-cli --driver lascar-el-usb:conn=10c4.0002 \
              --config datalog=on --set

EXIT STATUS

       sigrok-cli exits with 0 on success, 1 on most failures.

SEE ALSO

       pulseview(1)

BUGS

       Please report any bugs via Bugzilla (http://sigrok.org/bugzilla) or  on  the  sigrok-devel
       mailing list (sigrok-devel@lists.souceforge.net).

LICENSE

       sigrok-cli  is covered by the GNU General Public License (GPL). Some portions are licensed
       under the "GPL v2 or later", some under "GPL v3 or later".

AUTHORS

       Please see the individual source code files.

       This manual page was written by Uwe Hermann <uwe@hermann-uwe.de>.  It  is  licensed  under
       the terms of the GNU GPL (version 2 or later).

                                           Feb 05, 2013                             SIGROK-CLI(1)