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 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, pro‐
       tocol 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.

       --driver <drivername>
	      A driver must always be selected. 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  combina‐
	      tion,  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

       -d, --device <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 --device 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 equiv‐
	      alent:

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

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

		$ sigrok-cli --driver fx2lafw --device "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 for‐
	      mats.

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

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

       -A, --protocol-decoder-annotations <annotations>
	      By  default, only the stack's topmost protocol decoder's annota‐
	      tion output is shown. With this option another decoder's annota‐
	      tion can be selected for display, by specifying its ID:

	       $ sigrok-cli -i <file.sr> -a 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> -a 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> -a 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 indepen‐
	      dently. 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

       -D, --list-devices
	      List  all  devices  found on the system. This actively scans for
	      devices that can be detected automatically.

	      Example:

	       $ sigrok-cli -D
	       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 -D
	       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, microsec‐
	      onds, 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 gigasam‐
	      ples, 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  --device  option,
	      without doing any acquisition.

EXAMPLES
       In  order  to  get  exactly 100 samples from the connected fx2lafw-sup‐
       ported 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 Snif‐
       fer 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 --device samplerate=10m \
	      --output-format bits --probes 0-3 --time 100 \
	      --wait-trigger --triggers 0=1,1=r,2=0,3=1

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

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


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

SEE ALSO
       pulseview(1), sigrok-qt(1), sigrok-gtk(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)