Sigrok-cli

sigrok-cli is a command-line frontend for sigrok.

manpage

SIGROK-CLI(1)                                                    SIGROK-CLI(1)



NAME
       sigrok-cli - Command-line client for the sigrok logic analyzer software

SYNOPSIS
       sigrok-cli  [-hVlDdiIoOptwas] [-h|--help] [-V|--version] [-l|--loglevel
       level] [-D|--list-devices] [-d|--device device] [-i|--input-file  file‐
       name] [-I|--input-format format] [-o|--output-file filename] [-O|--out‐
       put-format format] [-p|--probes probelist] [-t|--triggers  triggerlist]
       [-w|--wait-trigger]    [-a|--protocol-decoders    list]    [-s|--proto‐
       col-decoder-stack stack] [--time ms] [--samples numsamples] [--continu‐
       ous]

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

       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 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  hard‐
              ware  drivers, input file formats, output file formats, and pro‐
              tocol decoders.

       -l, --loglevel <level>
              Set the libsigrok and libsigrokdecode loglevel.  At  the  moment
              sigrok-cli  doesn't  support  setting the two loglevels indepen‐
              dently. The higher the number, the more  debug  output  will  be
              printed.  Valid  loglevels  are  0  (NONE), 1 (ERR), 2 (WARN), 3
              (INFO), 4 (DBG), and 5 (SPEW).

       -D, --list-devices
              List all logic  analyzer  devices  found  on  the  system.  This
              actively scans for devices (USB, serial port, and others).

       -d, --device <device>
              The  device to use for acquisition. It can be specified by ID as
              reported by --list-devices, or by the  name  of  the  driver  as
              reported by --version.

              A device can optionally be followed by a colon-separated list of
              device options, where each option takes the form key=value.  For
              example,  to  set  the  samplerate on the first device you might
              specify

                $ sigrok-cli -d 0:samplerate=1m

              Samplerate is an option common to  most  devices.  The  argument
              specifies  the  samplerate  in Hz. You can also specify the sam‐
              plerate in kHz, MHz or GHz.  The following are all equivalent:

                $ sigrok-cli --samples 100 -d 0:samplerate=1000000

                $ sigrok-cli --samples 100 -d 0:samplerate=1m

                $ sigrok-cli --samples 100 -d "0: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.

       -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  for‐
              mat. 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 fol‐
              lowed  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, and csv.

              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:

               1:ffff ffff ffff ffff ffff ffff ffff ffff
               2: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:

               1:11111111 11111111 11111111 11111111 [...]
               2:11111111 00000000 11111111 00000000 [...]

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

              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 --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 -d
              <device>  argument  (with no other arguments) to see which trig‐
              gers your device supports.

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

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

              Example:

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

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

              Example:

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

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

              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>
                            -a spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0

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

              The decoders are specified by their ID, as shown in  the  --ver‐
              sion 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 -a option (you cannot  spec‐
              ify them in the -s option).

       --time <ms>
              Sample for <ms> milliseconds, then quit. You can optionally fol‐
              low the number by s to state the number  of  seconds  to  sample
              instead. For example, --time 2s will sample for two seconds.

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

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

EXAMPLES
       In order to get exactly 100 samples from the (only) detected logic ana‐
       lyzer hardware, run the following command:

         sigrok-cli --samples 100

       If you want to sample data for 3 seconds, use:

         sigrok-cli --time 3000

       Alternatively, you can also use:

         sigrok-cli --time 3s

       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:

         sigrok-cli -d 0:samplerate=10m -O bits -p 1-4 --time 100 \
                    --wait-trigger --triggers 1=1,2=r,3=0,4=1

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

SEE ALSO
       sigrok-qt(1), sigrok-gtk(1)

BUGS
       Please   report   any   bugs   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).



                                March 18, 2012                   SIGROK-CLI(1)