sigrok - User contributions [en]

Sigrok-cli

2023-07-07T08:09:31Z

AtomicFS: /* Usage tips */

{{DISPLAYTITLE:sigrok-cli}}
'''sigrok-cli''' (sometimes abbreviated as "cli") is a command-line frontend for sigrok.

It is licensed under the terms of the '''GNU GPL, version 3 or later'''.

== Getting the code ==

$ '''git clone git://sigrok.org/sigrok-cli'''

You can also [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=tree browse the source code] via gitweb.

== Distribution packages ==

See [[Downloads#Binaries_and_distribution_packages|Downloads]].

== Building from source ==

See [[Building]].

== Usage tips ==

It is recommended to capture the data first and process them later. sigrok-cli is single-threaded application and too much load will overwhelm it resulting in early termination. For capturing, use binary output format (especially for high sample-rates). This is because other formats pose too big overhead.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-file <file>.bin --output-format binary --config samplerate=50m --continuous

Even better, consider to use a buffer instead of direct write (even on SSD) and also compression.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-format binary --config samplerate=50m --continuous | mbuffer | lz4 | pv > data.lz4q

== Manpage ==
<div class="toccolours mw-collapsible mw-collapsed" overflow:auto;">

<pre>
SIGROK-CLI(1) General Commands Manual 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 the versions of libraries used.

-L, --list-supported
Show 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 -L (--list-supported) 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:

USB VendorID.ProductID example:

$ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]

USB bus.address example:

$ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]

-c, --config <deviceoption>
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 -d 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 equiv-
alent:

$ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]

$ sigrok-cli -d fx2lafw --config samplerate=1m [...]

$ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]

-i, --input-file <filename>
Load input from a file instead of a hardware device. You can
specify "-" to use stdin as input. If the --input-format option
is not supplied, sigrok-cli attempts to autodetect the file for-
mat of the input file.

Example for loading a sigrok session file:

$ sigrok-cli -i example.sr [...]

Example for loading a WAV file (autodetection of input format):

$ sigrok-cli -i example.wav [...]

Example for loading a VCD file from stdin (autodetection of
input format):

$ cat example.vcd | sigrok-cli -i - [...]

-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 -L (--list-supported) 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.

Example for loading a binary file with options:

$ sigrok-cli -i example.bin
-I binary:numchannels=4:samplerate=1mhz [...]

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

Example for saving data in the sigrok session format:

$ sigrok-cli [...] -o example.sr

-O, --output-format <format>
Set the output format to use. Use the -L (--list-supported)
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.

For example, 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 -O
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 channel 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 [...]

Example for saving data in the CSV format with options:

$ sigrok-cli [...] -o example.csv -O csv:dedup:header=false

Notice that boolean options are true when no value gets speci-
fied.

-C, --channels <channellist>
A comma-separated list of channels to be used in the session.

Note that sigrok always names the channels according to how
they're shown on the enclosure of the hardware. If your logic
analyzer numbers the channels 0-15, that's how you must specify
them with this option. An oscilloscope's channels would gener-
ally be referred to as "CH1", "CH2", and so on. Use the --show
option to see a list of channel names for your device.

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

Example:

$ sigrok-cli --driver fx2lafw --samples 100
--channels 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,CS=MISO will set the name of channel 1 to MISO.

-g, --channel-group <channel group>
Specify the channel group to operate on. Some devices organize
channels into groups, the settings of which can only be changed
as a group. The list of channel groups, if any, is displayed
with the --show command.

Examples:

$ sigrok-cli -g CH1 [...]

$ sigrok-cli -d demo -g Logic -c pattern=graycode [...]

-t, --triggers <triggerlist>
A comma-separated list of triggers to use, of the form <chan-
nel>=<trigger>. You can use the name or number of the channel,
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.
e: 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 -L (--list-supported)
output.

Example:

$ sigrok-cli -i <file.sr> -P 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>
-P uart:baudrate=115200:parity_type=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 channel
name/number assignments.

Example:

$ sigrok-cli -i <file.sr>
-P spi:wordsize=9:miso=1:mosi=5:clk=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 channel 1 as MISO signal for SPI, channel 5
as MOSI, channel 3 as CLK, and channel 0 as CS# signal.

Notice that the sigrok-cli application does not support "name
matching". Instead it's assumed that the traces in the input
stream match the order of the decoder's input signals, or that
users explicitly specify the input channel to decoder signal
mapping.

When multiple decoders are specified in the same -P option, they
will be stacked on top of each other in the specified order.

Example:

$ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
$ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi

When multiple -P options are specified, each of them creates one
decoder stack, which executes in parallel to other decoder
stacks.

Example:

$ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2

-A, --protocol-decoder-annotations <annotations>
By default, all annotation output of all protocol decoders is
shown. With this option a specific decoder's annotations can be
selected for display, by specifying the decoder ID:

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

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

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

Select multiple annotation classes by separating them with a
colon:

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write

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

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write,edid

-M, --protocol-decoder-meta <pdname>
When given, show protocol decoder meta output instead of annota-
tions. The argument is the name of the decoder whose meta out-
put to show.

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

Not every decoder generates meta output.

-B, --protocol-decoder-binary <binaryspec>
When given, decoder "raw" data of various kinds is written to
stdout instead of annotations (this could be raw binary UART/SPI
bytes, or WAV files, PCAP files, PNG files, or anything else;
this is entirely dependent on the decoder and what kinds of
binary output make sense for that decoder).

No other information is printed to stdout, so this is suitable
for piping into other programs or saving to a file.

Protocol decoders that support binary output publish a list of
binary classes, for example the UART decoder might have "TX" and
"RX". To select TX for output, the argument to this option would
be:

$ sigrok-cli -i <file.sr> -B uart=tx

If only the protocol decoder is specified, without binary class,
all classes are written to stdout:

$ sigrok-cli -i <file.sr> -B uart

(this is only useful in rare cases, generally you would specify
a certain binary class you're interested in)

Not every decoder generates binary output.

--protocol-decoder-samplenum
When given, decoder annotations will include sample numbers,
too. This allows consumers to receive machine readable timing
information.

-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

This also works for protocol decoders, input modules and output
modules:

$ sigrok-cli --protocol-decoders i2c --show
$ sigrok-cli --input-format csv --show
$ sigrok-cli --output-format bits --show

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

Example:

$ sigrok-cli --scan
The following devices were found:
demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
A1 A2 A3
fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 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 channel: P1

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

You can optionally follow the number by s to specify the time to
sample in seconds.

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.

--frames <numframes>
Acquire <numframes> frames, then quit.

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

--get <variable>
Get the value of <variable> from the specified device and print
it.

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

October 22, 2018 SIGROK-CLI(1)
</pre>
</div>

== Screenshots ==

=== sigrok-cli in action: logic data, decoder output, analog data ===

[[File:Sigrok-cli-screenshot-1.png]]

Sigrok-cli

2023-07-07T08:06:33Z

AtomicFS: /* Usage tips */

{{DISPLAYTITLE:sigrok-cli}}
'''sigrok-cli''' (sometimes abbreviated as "cli") is a command-line frontend for sigrok.

It is licensed under the terms of the '''GNU GPL, version 3 or later'''.

== Getting the code ==

$ '''git clone git://sigrok.org/sigrok-cli'''

You can also [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=tree browse the source code] via gitweb.

== Distribution packages ==

See [[Downloads#Binaries_and_distribution_packages|Downloads]].

== Building from source ==

See [[Building]].

== Usage tips ==

It is recommended to capture the data first and process them later. sigrok-cli is single-threaded application and too much load will overwhelm it. For capturing, use binary output format (especially for high sample-rates). This is because other formats pose too big overhead.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-file <file>.bin --output-format binary --config samplerate=50m --continuous

Even better, consider to use a buffer instead of direct write (even on SSD) and also compression.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-format binary --config samplerate=50m --continuous | mbuffer | lz4 | pv > data.lz4q

== Manpage ==
<div class="toccolours mw-collapsible mw-collapsed" overflow:auto;">

<pre>
SIGROK-CLI(1) General Commands Manual 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 the versions of libraries used.

-L, --list-supported
Show 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 -L (--list-supported) 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:

USB VendorID.ProductID example:

$ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]

USB bus.address example:

$ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]

-c, --config <deviceoption>
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 -d 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 equiv-
alent:

$ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]

$ sigrok-cli -d fx2lafw --config samplerate=1m [...]

$ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]

-i, --input-file <filename>
Load input from a file instead of a hardware device. You can
specify "-" to use stdin as input. If the --input-format option
is not supplied, sigrok-cli attempts to autodetect the file for-
mat of the input file.

Example for loading a sigrok session file:

$ sigrok-cli -i example.sr [...]

Example for loading a WAV file (autodetection of input format):

$ sigrok-cli -i example.wav [...]

Example for loading a VCD file from stdin (autodetection of
input format):

$ cat example.vcd | sigrok-cli -i - [...]

-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 -L (--list-supported) 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.

Example for loading a binary file with options:

$ sigrok-cli -i example.bin
-I binary:numchannels=4:samplerate=1mhz [...]

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

Example for saving data in the sigrok session format:

$ sigrok-cli [...] -o example.sr

-O, --output-format <format>
Set the output format to use. Use the -L (--list-supported)
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.

For example, 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 -O
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 channel 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 [...]

Example for saving data in the CSV format with options:

$ sigrok-cli [...] -o example.csv -O csv:dedup:header=false

Notice that boolean options are true when no value gets speci-
fied.

-C, --channels <channellist>
A comma-separated list of channels to be used in the session.

Note that sigrok always names the channels according to how
they're shown on the enclosure of the hardware. If your logic
analyzer numbers the channels 0-15, that's how you must specify
them with this option. An oscilloscope's channels would gener-
ally be referred to as "CH1", "CH2", and so on. Use the --show
option to see a list of channel names for your device.

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

Example:

$ sigrok-cli --driver fx2lafw --samples 100
--channels 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,CS=MISO will set the name of channel 1 to MISO.

-g, --channel-group <channel group>
Specify the channel group to operate on. Some devices organize
channels into groups, the settings of which can only be changed
as a group. The list of channel groups, if any, is displayed
with the --show command.

Examples:

$ sigrok-cli -g CH1 [...]

$ sigrok-cli -d demo -g Logic -c pattern=graycode [...]

-t, --triggers <triggerlist>
A comma-separated list of triggers to use, of the form <chan-
nel>=<trigger>. You can use the name or number of the channel,
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.
e: 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 -L (--list-supported)
output.

Example:

$ sigrok-cli -i <file.sr> -P 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>
-P uart:baudrate=115200:parity_type=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 channel
name/number assignments.

Example:

$ sigrok-cli -i <file.sr>
-P spi:wordsize=9:miso=1:mosi=5:clk=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 channel 1 as MISO signal for SPI, channel 5
as MOSI, channel 3 as CLK, and channel 0 as CS# signal.

Notice that the sigrok-cli application does not support "name
matching". Instead it's assumed that the traces in the input
stream match the order of the decoder's input signals, or that
users explicitly specify the input channel to decoder signal
mapping.

When multiple decoders are specified in the same -P option, they
will be stacked on top of each other in the specified order.

Example:

$ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
$ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi

When multiple -P options are specified, each of them creates one
decoder stack, which executes in parallel to other decoder
stacks.

Example:

$ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2

-A, --protocol-decoder-annotations <annotations>
By default, all annotation output of all protocol decoders is
shown. With this option a specific decoder's annotations can be
selected for display, by specifying the decoder ID:

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

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

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

Select multiple annotation classes by separating them with a
colon:

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write

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

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write,edid

-M, --protocol-decoder-meta <pdname>
When given, show protocol decoder meta output instead of annota-
tions. The argument is the name of the decoder whose meta out-
put to show.

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

Not every decoder generates meta output.

-B, --protocol-decoder-binary <binaryspec>
When given, decoder "raw" data of various kinds is written to
stdout instead of annotations (this could be raw binary UART/SPI
bytes, or WAV files, PCAP files, PNG files, or anything else;
this is entirely dependent on the decoder and what kinds of
binary output make sense for that decoder).

No other information is printed to stdout, so this is suitable
for piping into other programs or saving to a file.

Protocol decoders that support binary output publish a list of
binary classes, for example the UART decoder might have "TX" and
"RX". To select TX for output, the argument to this option would
be:

$ sigrok-cli -i <file.sr> -B uart=tx

If only the protocol decoder is specified, without binary class,
all classes are written to stdout:

$ sigrok-cli -i <file.sr> -B uart

(this is only useful in rare cases, generally you would specify
a certain binary class you're interested in)

Not every decoder generates binary output.

--protocol-decoder-samplenum
When given, decoder annotations will include sample numbers,
too. This allows consumers to receive machine readable timing
information.

-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

This also works for protocol decoders, input modules and output
modules:

$ sigrok-cli --protocol-decoders i2c --show
$ sigrok-cli --input-format csv --show
$ sigrok-cli --output-format bits --show

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

Example:

$ sigrok-cli --scan
The following devices were found:
demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
A1 A2 A3
fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 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 channel: P1

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

You can optionally follow the number by s to specify the time to
sample in seconds.

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.

--frames <numframes>
Acquire <numframes> frames, then quit.

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

--get <variable>
Get the value of <variable> from the specified device and print
it.

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

October 22, 2018 SIGROK-CLI(1)
</pre>
</div>

== Screenshots ==

=== sigrok-cli in action: logic data, decoder output, analog data ===

[[File:Sigrok-cli-screenshot-1.png]]

Input output formats

2023-07-07T08:04:29Z

AtomicFS: /* Supported input/output formats */

[[libsigrok]] supports a number of different input modules (a.k.a. file formats) and output modules, and has a generic API which allows easily adding more input/output modules.

== Supported input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 12em;" | Name
!Input
!Output
!Description
|-
| [[File format:analog|Analog]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Text output of analog data and types.
|-
| [[File format:ascii|ASCII]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| ASCII art.
|-
| [[File format:binary|Binary]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Raw binary data output without any metadata attached.
|-
| [[File format:bits|Bits]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| 0/1 digits.
|-
| style="white-space: nowrap;" | [[File format:chronovu_la8|ChronoVu LA8]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| [[ChronoVu LA8]] software file format (usually with .kdt file extension).
|-
| [[File format:csv|CSV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Comma-separated values (also usable for generating data and config files for gnuplot).
|-
| [[File format:hex|hex]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Hexadecimal digits.
|-
| [[File format:logicport|Intronix Logicport LA1034]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| [[Intronix Logicport LA1034]] *.lpf files.
|-
| [[File format:ols|ols]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| The file format used by the [http://www.lxtreme.nl/ols/ "Alternative" Java client] for the [[Openbench Logic Sniffer]].
|-
| [[File format:saleae|saleae]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Files exported by the Saleae Logic application.
|-
| [[File format:srzip|srzip]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The current (v2) sigrok session file format (*.sr).
|-
| [[File format:stf|STF]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| "Sigma Test File". Native format of the Asix Sigma/Omega vendor software.
|-
| [[File format:vcd|VCD]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/Value_change_dump Value Change Dump] format (can also be visualized in [http://gtkwave.sourceforge.net/ gtkwave], for instance).
|-
| [[File format:wav|WAV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/WAV waveform audio] (WAV) file format.
|-
| [[File format:raw_analog|Raw analog]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Analog signals without header (configurable sample size, format, and endianness).

|-
| [[File format:trace32_ad|Lauterbach Trace32]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| The Lauterbach Trace32 logic analyzer data file format.

|-
| [[File format:wavedrom|WaveDrom]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Digital timing diagrams in JSON syntax

|}

The output formats apply only to unprocessed raw data. Data processed by decoders can't be saved into output file by argument, only by redirection of <code>STDOUT</code>.

== Supported transform modules ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 8em;" | Name
!Description
|-
| nop
| Do nothing.
|-
| scale
| Scale analog values by a specified factor.
|-
| invert
| Invert values.
|}

== Possible candidates for future input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
!Name
!Description
|-
| Scanalogic
| Used by the [[IKALOGIC Scanalogic-2]] and [[IKALOGIC ScanaPLUS]] logic analyzers.
|-
| [[File format:rigol_rof|Rigol ROF]]
| Used by the [[Rigol DP800 series]] power supplies.
|-
| [[File format:rigol_raf|Rigol RAF]]
| Used by the Rigol DG1000Z, DG4000, and DG5000 series signal generators. See [http://www.batronix.com/pdf/Rigol/UserGuide/DG1000Z_UserGuide_EN.pdf DG1000Z User Guide] page 2-75, also [http://www.eevblog.com/forum/testgear/rigol-dg4000-series-raf-file-format/msg559443/ this post] at eevblog.
|-
| [[File format:rigol_wfm|Rigol WFM]]
| Used by the Rigol DS series oscilloscopes. See https://github.com/mabl/pyRigolWFM/blob/master/wfm.py
|-
| [[File_format:Rigol_WFM4|Rigol WFM4]]
| Used by the Rigol DS4000 series oscilloscopes.
|-
| Vector MDF (v3.3) / ASAM MDF (v4.x)
| Automotive industry standard format. Docs can be found [http://vector.com/vi_mdf_de.html here] and [http://vector.com/downloads/mdf_specification.pdf here]. Validator is [http://vector.com/downloads/MDFValidator2.1.8.zip here]. Some code is [https://code.google.com/p/mdfreader/ here] and [http://sourceforge.net/p/mdfdatafile/code/HEAD/tree/ here].
|-
| [http://en.wikipedia.org/wiki/Comtrade COMTRADE]
| File format used by devices in power engineering (e.g. protective relays, fault recorders). Can contain digital and analog data with constant or variable sample rate.
|-
| [[File format:pwl|PWL]]
| Trivial file format that can be used to define the signal of voltage/current sources in a SPICE simulation.
|-
| [[File format:tektronix_wfm|Tektronix WFM]]
| Used by the Tektronix TDS series oscilloscopes. A parser for Matlab can be found [http://www.mathworks.com/matlabcentral/fileexchange/5873-tektronix-binary-file-readers/content/wfmread.m here].
|-
| EVCD/IDX/FST/GHW
| File formats generated by hardware simulation tools. See the [http://gtkwave.sourceforge.net/gtkwave.pdf GtkWave manual] for some of them, and conversion utilities.
|-
| [https://www.ni.com/hu-hu/support/documentation/supplemental/06/the-ni-tdms-file-format.html NI TDMS]
| File formats used by various National Instruments software like LabVIEW or DAQExpress.
|-
| IMC data format
| File formats used by imc GmbH softwares. File format description can be found in the [https://www.imcdataworks.com/secure-dl/?file=fileadmin/Download-Center/Manuals/imc_FAMOS/imcSharedComponents.pdf imc Software Shared Components documentation]. (Registration required.)
|}

Input output formats

2023-07-06T16:18:06Z

AtomicFS: /* Supported input/output formats */

[[libsigrok]] supports a number of different input modules (a.k.a. file formats) and output modules, and has a generic API which allows easily adding more input/output modules.

== Supported input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 12em;" | Name
!Input
!Output
!Description
|-
| [[File format:analog|Analog]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Text output of analog data and types.
|-
| [[File format:ascii|ASCII]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| ASCII art.
|-
| [[File format:binary|Binary]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Raw binary data output without any metadata attached.
|-
| [[File format:bits|Bits]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| 0/1 digits.
|-
| style="white-space: nowrap;" | [[File format:chronovu_la8|ChronoVu LA8]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| [[ChronoVu LA8]] software file format (usually with .kdt file extension).
|-
| [[File format:csv|CSV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Comma-separated values (also usable for generating data and config files for gnuplot).
|-
| [[File format:hex|hex]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Hexadecimal digits.
|-
| [[File format:logicport|Intronix Logicport LA1034]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| [[Intronix Logicport LA1034]] *.lpf files.
|-
| [[File format:ols|ols]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| The file format used by the [http://www.lxtreme.nl/ols/ "Alternative" Java client] for the [[Openbench Logic Sniffer]].
|-
| [[File format:saleae|saleae]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Files exported by the Saleae Logic application.
|-
| [[File format:srzip|srzip]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The current (v2) sigrok session file format (*.sr).
|-
| [[File format:stf|STF]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| "Sigma Test File". Native format of the Asix Sigma/Omega vendor software.
|-
| [[File format:vcd|VCD]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/Value_change_dump Value Change Dump] format (can also be visualized in [http://gtkwave.sourceforge.net/ gtkwave], for instance).
|-
| [[File format:wav|WAV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/WAV waveform audio] (WAV) file format.
|-
| [[File format:raw_analog|Raw analog]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Analog signals without header (configurable sample size, format, and endianness).

|-
| [[File format:trace32_ad|Lauterbach Trace32]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| The Lauterbach Trace32 logic analyzer data file format.

|-
| [[File format:wavedrom|WaveDrom]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Digital timing diagrams in JSON syntax

|}

<b>WARNING:</b> The output formats apply only to unprocessed raw data. Data processed by decoders can't be saved into output file by argument, only by redirection of <code>STDOUT</code>.

== Supported transform modules ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 8em;" | Name
!Description
|-
| nop
| Do nothing.
|-
| scale
| Scale analog values by a specified factor.
|-
| invert
| Invert values.
|}

== Possible candidates for future input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
!Name
!Description
|-
| Scanalogic
| Used by the [[IKALOGIC Scanalogic-2]] and [[IKALOGIC ScanaPLUS]] logic analyzers.
|-
| [[File format:rigol_rof|Rigol ROF]]
| Used by the [[Rigol DP800 series]] power supplies.
|-
| [[File format:rigol_raf|Rigol RAF]]
| Used by the Rigol DG1000Z, DG4000, and DG5000 series signal generators. See [http://www.batronix.com/pdf/Rigol/UserGuide/DG1000Z_UserGuide_EN.pdf DG1000Z User Guide] page 2-75, also [http://www.eevblog.com/forum/testgear/rigol-dg4000-series-raf-file-format/msg559443/ this post] at eevblog.
|-
| [[File format:rigol_wfm|Rigol WFM]]
| Used by the Rigol DS series oscilloscopes. See https://github.com/mabl/pyRigolWFM/blob/master/wfm.py
|-
| [[File_format:Rigol_WFM4|Rigol WFM4]]
| Used by the Rigol DS4000 series oscilloscopes.
|-
| Vector MDF (v3.3) / ASAM MDF (v4.x)
| Automotive industry standard format. Docs can be found [http://vector.com/vi_mdf_de.html here] and [http://vector.com/downloads/mdf_specification.pdf here]. Validator is [http://vector.com/downloads/MDFValidator2.1.8.zip here]. Some code is [https://code.google.com/p/mdfreader/ here] and [http://sourceforge.net/p/mdfdatafile/code/HEAD/tree/ here].
|-
| [http://en.wikipedia.org/wiki/Comtrade COMTRADE]
| File format used by devices in power engineering (e.g. protective relays, fault recorders). Can contain digital and analog data with constant or variable sample rate.
|-
| [[File format:pwl|PWL]]
| Trivial file format that can be used to define the signal of voltage/current sources in a SPICE simulation.
|-
| [[File format:tektronix_wfm|Tektronix WFM]]
| Used by the Tektronix TDS series oscilloscopes. A parser for Matlab can be found [http://www.mathworks.com/matlabcentral/fileexchange/5873-tektronix-binary-file-readers/content/wfmread.m here].
|-
| EVCD/IDX/FST/GHW
| File formats generated by hardware simulation tools. See the [http://gtkwave.sourceforge.net/gtkwave.pdf GtkWave manual] for some of them, and conversion utilities.
|-
| [https://www.ni.com/hu-hu/support/documentation/supplemental/06/the-ni-tdms-file-format.html NI TDMS]
| File formats used by various National Instruments software like LabVIEW or DAQExpress.
|-
| IMC data format
| File formats used by imc GmbH softwares. File format description can be found in the [https://www.imcdataworks.com/secure-dl/?file=fileadmin/Download-Center/Manuals/imc_FAMOS/imcSharedComponents.pdf imc Software Shared Components documentation]. (Registration required.)
|}

Sigrok-cli

2023-07-06T16:16:05Z

AtomicFS: /* Manpage */

{{DISPLAYTITLE:sigrok-cli}}
'''sigrok-cli''' (sometimes abbreviated as "cli") is a command-line frontend for sigrok.

It is licensed under the terms of the '''GNU GPL, version 3 or later'''.

== Getting the code ==

$ '''git clone git://sigrok.org/sigrok-cli'''

You can also [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=tree browse the source code] via gitweb.

== Distribution packages ==

See [[Downloads#Binaries_and_distribution_packages|Downloads]].

== Building from source ==

See [[Building]].

== Usage tips ==

It is recommended to capture the data first and process them later. sigrok-cli is single-threaded application and too much load will crash it. For capturing, use binary output format (especially for high sample-rates). This is because other formats pose too big overhead.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-file <file>.bin --output-format binary --config samplerate=50m --continuous

Even better, consider to use a buffer instead of direct write (even on SSD) and also compression.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-format binary --config samplerate=50m --continuous | mbuffer | lz4 | pv > data.lz4q

== Manpage ==
<div class="toccolours mw-collapsible mw-collapsed" overflow:auto;">

<pre>
SIGROK-CLI(1) General Commands Manual 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 the versions of libraries used.

-L, --list-supported
Show 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 -L (--list-supported) 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:

USB VendorID.ProductID example:

$ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]

USB bus.address example:

$ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]

-c, --config <deviceoption>
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 -d 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 equiv-
alent:

$ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]

$ sigrok-cli -d fx2lafw --config samplerate=1m [...]

$ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]

-i, --input-file <filename>
Load input from a file instead of a hardware device. You can
specify "-" to use stdin as input. If the --input-format option
is not supplied, sigrok-cli attempts to autodetect the file for-
mat of the input file.

Example for loading a sigrok session file:

$ sigrok-cli -i example.sr [...]

Example for loading a WAV file (autodetection of input format):

$ sigrok-cli -i example.wav [...]

Example for loading a VCD file from stdin (autodetection of
input format):

$ cat example.vcd | sigrok-cli -i - [...]

-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 -L (--list-supported) 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.

Example for loading a binary file with options:

$ sigrok-cli -i example.bin
-I binary:numchannels=4:samplerate=1mhz [...]

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

Example for saving data in the sigrok session format:

$ sigrok-cli [...] -o example.sr

-O, --output-format <format>
Set the output format to use. Use the -L (--list-supported)
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.

For example, 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 -O
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 channel 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 [...]

Example for saving data in the CSV format with options:

$ sigrok-cli [...] -o example.csv -O csv:dedup:header=false

Notice that boolean options are true when no value gets speci-
fied.

-C, --channels <channellist>
A comma-separated list of channels to be used in the session.

Note that sigrok always names the channels according to how
they're shown on the enclosure of the hardware. If your logic
analyzer numbers the channels 0-15, that's how you must specify
them with this option. An oscilloscope's channels would gener-
ally be referred to as "CH1", "CH2", and so on. Use the --show
option to see a list of channel names for your device.

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

Example:

$ sigrok-cli --driver fx2lafw --samples 100
--channels 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,CS=MISO will set the name of channel 1 to MISO.

-g, --channel-group <channel group>
Specify the channel group to operate on. Some devices organize
channels into groups, the settings of which can only be changed
as a group. The list of channel groups, if any, is displayed
with the --show command.

Examples:

$ sigrok-cli -g CH1 [...]

$ sigrok-cli -d demo -g Logic -c pattern=graycode [...]

-t, --triggers <triggerlist>
A comma-separated list of triggers to use, of the form <chan-
nel>=<trigger>. You can use the name or number of the channel,
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.
e: 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 -L (--list-supported)
output.

Example:

$ sigrok-cli -i <file.sr> -P 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>
-P uart:baudrate=115200:parity_type=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 channel
name/number assignments.

Example:

$ sigrok-cli -i <file.sr>
-P spi:wordsize=9:miso=1:mosi=5:clk=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 channel 1 as MISO signal for SPI, channel 5
as MOSI, channel 3 as CLK, and channel 0 as CS# signal.

Notice that the sigrok-cli application does not support "name
matching". Instead it's assumed that the traces in the input
stream match the order of the decoder's input signals, or that
users explicitly specify the input channel to decoder signal
mapping.

When multiple decoders are specified in the same -P option, they
will be stacked on top of each other in the specified order.

Example:

$ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
$ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi

When multiple -P options are specified, each of them creates one
decoder stack, which executes in parallel to other decoder
stacks.

Example:

$ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2

-A, --protocol-decoder-annotations <annotations>
By default, all annotation output of all protocol decoders is
shown. With this option a specific decoder's annotations can be
selected for display, by specifying the decoder ID:

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

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

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

Select multiple annotation classes by separating them with a
colon:

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write

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

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write,edid

-M, --protocol-decoder-meta <pdname>
When given, show protocol decoder meta output instead of annota-
tions. The argument is the name of the decoder whose meta out-
put to show.

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

Not every decoder generates meta output.

-B, --protocol-decoder-binary <binaryspec>
When given, decoder "raw" data of various kinds is written to
stdout instead of annotations (this could be raw binary UART/SPI
bytes, or WAV files, PCAP files, PNG files, or anything else;
this is entirely dependent on the decoder and what kinds of
binary output make sense for that decoder).

No other information is printed to stdout, so this is suitable
for piping into other programs or saving to a file.

Protocol decoders that support binary output publish a list of
binary classes, for example the UART decoder might have "TX" and
"RX". To select TX for output, the argument to this option would
be:

$ sigrok-cli -i <file.sr> -B uart=tx

If only the protocol decoder is specified, without binary class,
all classes are written to stdout:

$ sigrok-cli -i <file.sr> -B uart

(this is only useful in rare cases, generally you would specify
a certain binary class you're interested in)

Not every decoder generates binary output.

--protocol-decoder-samplenum
When given, decoder annotations will include sample numbers,
too. This allows consumers to receive machine readable timing
information.

-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

This also works for protocol decoders, input modules and output
modules:

$ sigrok-cli --protocol-decoders i2c --show
$ sigrok-cli --input-format csv --show
$ sigrok-cli --output-format bits --show

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

Example:

$ sigrok-cli --scan
The following devices were found:
demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
A1 A2 A3
fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 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 channel: P1

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

You can optionally follow the number by s to specify the time to
sample in seconds.

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.

--frames <numframes>
Acquire <numframes> frames, then quit.

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

--get <variable>
Get the value of <variable> from the specified device and print
it.

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

October 22, 2018 SIGROK-CLI(1)
</pre>
</div>

== Screenshots ==

=== sigrok-cli in action: logic data, decoder output, analog data ===

[[File:Sigrok-cli-screenshot-1.png]]

Sigrok-cli

2023-07-06T16:08:02Z

AtomicFS:

{{DISPLAYTITLE:sigrok-cli}}
'''sigrok-cli''' (sometimes abbreviated as "cli") is a command-line frontend for sigrok.

It is licensed under the terms of the '''GNU GPL, version 3 or later'''.

== Getting the code ==

$ '''git clone git://sigrok.org/sigrok-cli'''

You can also [http://sigrok.org/gitweb/?p=sigrok-cli.git;a=tree browse the source code] via gitweb.

== Distribution packages ==

See [[Downloads#Binaries_and_distribution_packages|Downloads]].

== Building from source ==

See [[Building]].

== Usage tips ==

It is recommended to capture the data first and process them later. sigrok-cli is single-threaded application and too much load will crash it. For capturing, use binary output format (especially for high sample-rates). This is because other formats pose too big overhead.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-file <file>.bin --output-format binary --config samplerate=50m --continuous

Even better, consider to use a buffer instead of direct write (even on SSD) and also compression.

$ sigrok-cli --driver saleae-logic-pro --channels 0=Vcc,1=CS,2=MISO,3=MOSI,4=CLK --output-format binary --config samplerate=50m --continuous | mbuffer | lz4 | pv > data.lz4q

== Manpage ==

<pre>
SIGROK-CLI(1) General Commands Manual 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 the versions of libraries used.

-L, --list-supported
Show 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 -L (--list-supported) 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:

USB VendorID.ProductID example:

$ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]

USB bus.address example:

$ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]

-c, --config <deviceoption>
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 -d 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 equiv-
alent:

$ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]

$ sigrok-cli -d fx2lafw --config samplerate=1m [...]

$ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]

-i, --input-file <filename>
Load input from a file instead of a hardware device. You can
specify "-" to use stdin as input. If the --input-format option
is not supplied, sigrok-cli attempts to autodetect the file for-
mat of the input file.

Example for loading a sigrok session file:

$ sigrok-cli -i example.sr [...]

Example for loading a WAV file (autodetection of input format):

$ sigrok-cli -i example.wav [...]

Example for loading a VCD file from stdin (autodetection of
input format):

$ cat example.vcd | sigrok-cli -i - [...]

-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 -L (--list-supported) 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.

Example for loading a binary file with options:

$ sigrok-cli -i example.bin
-I binary:numchannels=4:samplerate=1mhz [...]

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

Example for saving data in the sigrok session format:

$ sigrok-cli [...] -o example.sr

-O, --output-format <format>
Set the output format to use. Use the -L (--list-supported)
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.

For example, 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 -O
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 channel 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 [...]

Example for saving data in the CSV format with options:

$ sigrok-cli [...] -o example.csv -O csv:dedup:header=false

Notice that boolean options are true when no value gets speci-
fied.

-C, --channels <channellist>
A comma-separated list of channels to be used in the session.

Note that sigrok always names the channels according to how
they're shown on the enclosure of the hardware. If your logic
analyzer numbers the channels 0-15, that's how you must specify
them with this option. An oscilloscope's channels would gener-
ally be referred to as "CH1", "CH2", and so on. Use the --show
option to see a list of channel names for your device.

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

Example:

$ sigrok-cli --driver fx2lafw --samples 100
--channels 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,CS=MISO will set the name of channel 1 to MISO.

-g, --channel-group <channel group>
Specify the channel group to operate on. Some devices organize
channels into groups, the settings of which can only be changed
as a group. The list of channel groups, if any, is displayed
with the --show command.

Examples:

$ sigrok-cli -g CH1 [...]

$ sigrok-cli -d demo -g Logic -c pattern=graycode [...]

-t, --triggers <triggerlist>
A comma-separated list of triggers to use, of the form <chan-
nel>=<trigger>. You can use the name or number of the channel,
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.
e: 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 -L (--list-supported)
output.

Example:

$ sigrok-cli -i <file.sr> -P 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>
-P uart:baudrate=115200:parity_type=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 channel
name/number assignments.

Example:

$ sigrok-cli -i <file.sr>
-P spi:wordsize=9:miso=1:mosi=5:clk=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 channel 1 as MISO signal for SPI, channel 5
as MOSI, channel 3 as CLK, and channel 0 as CS# signal.

Notice that the sigrok-cli application does not support "name
matching". Instead it's assumed that the traces in the input
stream match the order of the decoder's input signals, or that
users explicitly specify the input channel to decoder signal
mapping.

When multiple decoders are specified in the same -P option, they
will be stacked on top of each other in the specified order.

Example:

$ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
$ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi

When multiple -P options are specified, each of them creates one
decoder stack, which executes in parallel to other decoder
stacks.

Example:

$ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2

-A, --protocol-decoder-annotations <annotations>
By default, all annotation output of all protocol decoders is
shown. With this option a specific decoder's annotations can be
selected for display, by specifying the decoder ID:

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

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

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

Select multiple annotation classes by separating them with a
colon:

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write

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

$ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
-A i2c=data-read:data-write,edid

-M, --protocol-decoder-meta <pdname>
When given, show protocol decoder meta output instead of annota-
tions. The argument is the name of the decoder whose meta out-
put to show.

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

Not every decoder generates meta output.

-B, --protocol-decoder-binary <binaryspec>
When given, decoder "raw" data of various kinds is written to
stdout instead of annotations (this could be raw binary UART/SPI
bytes, or WAV files, PCAP files, PNG files, or anything else;
this is entirely dependent on the decoder and what kinds of
binary output make sense for that decoder).

No other information is printed to stdout, so this is suitable
for piping into other programs or saving to a file.

Protocol decoders that support binary output publish a list of
binary classes, for example the UART decoder might have "TX" and
"RX". To select TX for output, the argument to this option would
be:

$ sigrok-cli -i <file.sr> -B uart=tx

If only the protocol decoder is specified, without binary class,
all classes are written to stdout:

$ sigrok-cli -i <file.sr> -B uart

(this is only useful in rare cases, generally you would specify
a certain binary class you're interested in)

Not every decoder generates binary output.

--protocol-decoder-samplenum
When given, decoder annotations will include sample numbers,
too. This allows consumers to receive machine readable timing
information.

-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

This also works for protocol decoders, input modules and output
modules:

$ sigrok-cli --protocol-decoders i2c --show
$ sigrok-cli --input-format csv --show
$ sigrok-cli --output-format bits --show

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

Example:

$ sigrok-cli --scan
The following devices were found:
demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
A1 A2 A3
fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 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 channel: P1

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

You can optionally follow the number by s to specify the time to
sample in seconds.

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.

--frames <numframes>
Acquire <numframes> frames, then quit.

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

--get <variable>
Get the value of <variable> from the specified device and print
it.

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

October 22, 2018 SIGROK-CLI(1)
</pre>

== Screenshots ==

=== sigrok-cli in action: logic data, decoder output, analog data ===

[[File:Sigrok-cli-screenshot-1.png]]

Input output formats

2023-07-06T15:46:22Z

AtomicFS: /* Supported input/output formats */

[[libsigrok]] supports a number of different input modules (a.k.a. file formats) and output modules, and has a generic API which allows easily adding more input/output modules.

== Supported input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 12em;" | Name
!Input
!Output
!Description
|-
| [[File format:analog|Analog]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Text output of analog data and types.
|-
| [[File format:ascii|ASCII]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| ASCII art.
|-
| [[File format:binary|Binary]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Raw binary data output without any metadata attached.
|-
| [[File format:bits|Bits]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| 0/1 digits.
|-
| style="white-space: nowrap;" | [[File format:chronovu_la8|ChronoVu LA8]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| [[ChronoVu LA8]] software file format (usually with .kdt file extension).
|-
| [[File format:csv|CSV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| Comma-separated values (also usable for generating data and config files for gnuplot).
|-
| [[File format:hex|hex]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Hexadecimal digits.
|-
| [[File format:logicport|Intronix Logicport LA1034]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| [[Intronix Logicport LA1034]] *.lpf files.
|-
| [[File format:ols|ols]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| The file format used by the [http://www.lxtreme.nl/ols/ "Alternative" Java client] for the [[Openbench Logic Sniffer]].
|-
| [[File format:saleae|saleae]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Files exported by the Saleae Logic application.
|-
| [[File format:srzip|srzip]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The current (v2) sigrok session file format (*.sr).
|-
| [[File format:stf|STF]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| "Sigma Test File". Native format of the Asix Sigma/Omega vendor software.
|-
| [[File format:vcd|VCD]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/Value_change_dump Value Change Dump] format (can also be visualized in [http://gtkwave.sourceforge.net/ gtkwave], for instance).
|-
| [[File format:wav|WAV]]
| bgcolor="lime" | supported
| bgcolor="lime" | supported
| The [http://en.wikipedia.org/wiki/WAV waveform audio] (WAV) file format.
|-
| [[File format:raw_analog|Raw analog]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| Analog signals without header (configurable sample size, format, and endianness).

|-
| [[File format:trace32_ad|Lauterbach Trace32]]
| bgcolor="lime" | supported
| bgcolor="yellow" | —
| The Lauterbach Trace32 logic analyzer data file format.

|-
| [[File format:wavedrom|WaveDrom]]
| bgcolor="yellow" | —
| bgcolor="lime" | supported
| Digital timing diagrams in JSON syntax

|}

<b>WARNING:</b> The output formats apply only to unprocessed raw data. Data processed by decoders can't be saved into output file by argument, only be redirection of <code>STDOUT</code>.

== Supported transform modules ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
! style="width: 8em;" | Name
!Description
|-
| nop
| Do nothing.
|-
| scale
| Scale analog values by a specified factor.
|-
| invert
| Invert values.
|}

== Possible candidates for future input/output formats ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
!Name
!Description
|-
| Scanalogic
| Used by the [[IKALOGIC Scanalogic-2]] and [[IKALOGIC ScanaPLUS]] logic analyzers.
|-
| [[File format:rigol_rof|Rigol ROF]]
| Used by the [[Rigol DP800 series]] power supplies.
|-
| [[File format:rigol_raf|Rigol RAF]]
| Used by the Rigol DG1000Z, DG4000, and DG5000 series signal generators. See [http://www.batronix.com/pdf/Rigol/UserGuide/DG1000Z_UserGuide_EN.pdf DG1000Z User Guide] page 2-75, also [http://www.eevblog.com/forum/testgear/rigol-dg4000-series-raf-file-format/msg559443/ this post] at eevblog.
|-
| [[File format:rigol_wfm|Rigol WFM]]
| Used by the Rigol DS series oscilloscopes. See https://github.com/mabl/pyRigolWFM/blob/master/wfm.py
|-
| [[File_format:Rigol_WFM4|Rigol WFM4]]
| Used by the Rigol DS4000 series oscilloscopes.
|-
| Vector MDF (v3.3) / ASAM MDF (v4.x)
| Automotive industry standard format. Docs can be found [http://vector.com/vi_mdf_de.html here] and [http://vector.com/downloads/mdf_specification.pdf here]. Validator is [http://vector.com/downloads/MDFValidator2.1.8.zip here]. Some code is [https://code.google.com/p/mdfreader/ here] and [http://sourceforge.net/p/mdfdatafile/code/HEAD/tree/ here].
|-
| [http://en.wikipedia.org/wiki/Comtrade COMTRADE]
| File format used by devices in power engineering (e.g. protective relays, fault recorders). Can contain digital and analog data with constant or variable sample rate.
|-
| [[File format:pwl|PWL]]
| Trivial file format that can be used to define the signal of voltage/current sources in a SPICE simulation.
|-
| [[File format:tektronix_wfm|Tektronix WFM]]
| Used by the Tektronix TDS series oscilloscopes. A parser for Matlab can be found [http://www.mathworks.com/matlabcentral/fileexchange/5873-tektronix-binary-file-readers/content/wfmread.m here].
|-
| EVCD/IDX/FST/GHW
| File formats generated by hardware simulation tools. See the [http://gtkwave.sourceforge.net/gtkwave.pdf GtkWave manual] for some of them, and conversion utilities.
|-
| [https://www.ni.com/hu-hu/support/documentation/supplemental/06/the-ni-tdms-file-format.html NI TDMS]
| File formats used by various National Instruments software like LabVIEW or DAQExpress.
|-
| IMC data format
| File formats used by imc GmbH softwares. File format description can be found in the [https://www.imcdataworks.com/secure-dl/?file=fileadmin/Download-Center/Manuals/imc_FAMOS/imcSharedComponents.pdf imc Software Shared Components documentation]. (Registration required.)
|}

Protocol decoder HOWTO

2023-07-06T13:20:52Z

AtomicFS: /* Unit tests */

This page serves as a quick-start guide for people who want to write their own [[libsigrokdecode]] protocol decoders ([[Protocol decoders|PDs]]).

It is '''not''' intended to replace the [[Protocol decoder API]] page, but rather to give a short overview/tutorial and some tips.

== Introduction ==

Protocol decoders are written entirely in Python (>= 3.0).

== Files ==

Every protocol decoder is a Python module and has its own subdirectory in libsigrokdecode's '''[http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders decoders]''' directory.

This is a minimalistic example of how a protocol decoder looks like, in this case the '''[[Protocol_decoder:I2c|i2c]]''' decoder (license header, comments, and some other parts omitted).

'''Note''': Do not start new protocol decoders by copying code from here. Instead, it's recommended to select an already existing decoder in the source code which is similar to the one you plan to write, and copy that as a starting point.

=== __init__.py ===

<small>
<source lang="python">
'''
I²C (Inter-Integrated Circuit) is a bidirectional, multi-master
bus using two signals (SCL = serial clock line, SDA = serial data line).

<Insert notes and hints for the user here>
'''

from .pd import Decoder
</source>
</small>

This is a standard Python file, required in every Python module. It contains a module-level docstring, which is accessible by frontends via the [http://sigrok.org/api/libsigrokdecode/unstable/index.html libsigrokdecode API]. It should contain a (very) short description of what the protocol (in this case [[Protocol_decoder:I2c|I²C]]) is about, and some notes and hints for the user of this protocol decoder (which can be shown in GUIs when the user selects/browses different PDs).

This docstring should '''not''' contain the full, extensive protocol description. Instead, the per-PD wiki page should be used for protocol description, photos of devices or photos of example acquisition setups, and so on. Each decoder has one unique wiki page at the URL '''<nowiki>http://sigrok.org/wiki/Protocol_decoder:<pd></nowiki>''', where '''<pd>''' is the Python module name of the decoder ('''i2c''' in this case). Some examples for such per-PD wiki pages: [[Protocol_decoder:Uart|UART]], [[Protocol_decoder:Pan1321|PAN1321]], [[Protocol_decoder:Mx25lxx05d|MX25Lxx05D]], [[Protocol_decoder:Dcf77|DCF77]].

The "'''from .pd import Decoder'''" line will make sure the code from '''pd.py''' gets properly imported when this module is used.

=== pd.py ===

<small>
<source lang="python">
import sigrokdecode as srd

class Decoder(srd.Decoder):
api_version = 3
id = 'i2c'
name = 'I²C'
longname = 'Inter-Integrated Circuit'
desc = 'Two-wire, multi-master, serial bus.'
license = 'gplv2+'
inputs = ['logic']
outputs = ['i2c']
channels = (
{'id': 'scl', 'name': 'SCL', 'desc': 'Serial clock line'},
{'id': 'sda', 'name': 'SDA', 'desc': 'Serial data line'},
)
optional_channels = ()
options = (
{'id': 'address_format', 'desc': 'Displayed slave address format',
'default': 'shifted', 'values': ('shifted', 'unshifted')},
)
annotations = (
('start', 'Start condition'),
('repeat-start', 'Repeat start condition'),
('stop', 'Stop condition'),
('ack', 'ACK'),
('nack', 'NACK'),
('bit', 'Data/address bit'),
('address-read', 'Address read'),
('address-write', 'Address write'),
('data-read', 'Data read'),
('data-write', 'Data write'),
('warnings', 'Human-readable warnings'),
)
annotation_rows = (
('bits', 'Bits', (5,)),
('addr-data', 'Address/Data', (0, 1, 2, 3, 4, 6, 7, 8, 9)),
('warnings', 'Warnings', (10,)),
)

def __init__(self, **kwargs):
self.state = 'FIND START'
# And various other variable initializations...

def metadata(self, key, value):
if key == srd.SRD_CONF_SAMPLERATE:
self.samplerate = value

def reset(self):
#reset inner states

def start(self):
self.out_ann = self.register(srd.OUTPUT_ANN)

def decode(self):
decode_the_sample(self.wait())

</source>
</small>

The recommended name for the actual decoder file is '''pd.py'''. This file contains some meta information about the decoder, and the actual code itself, mostly in the '''decode()''' method.

If needed, large unwieldy lists or similar things can also be factored out into another *.py file (examples: [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders/midi midi], [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders/z80 z80]).

== Copyright and license ==

Every protocol decoder '''must''' come with source code in the form of '''*.py''' files. No pre-compiled code should be present, Python or otherwise. The PD must not use any helpers that are not provided as source code under the same license as the PD itself.

The '''<tt>Decoder</tt>''' class must have a license declaration (see above), stating the license under which all the contents in the decoder's directory are provided. This is usually <tt>'gplv2+'</tt> or <tt>'gplv3+'</tt>, whichever you prefer. In either case, the decoder license must be compatible with the [[libsigrokdecode]] license (which is "GPL, version 3 or later").

== <tt>channels</tt> & <tt>optional_channels</tt> ==

The following excerpt from the [[Protocol_decoder:spi|SPI]] PD shows how to use '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''. To decode SPI, the clock signal is always needed, the chip-select signal is optional and only used when provided. To give the user the flexibility to provide only one of the MOSI/MISO signals, they are both also defined as optional:

<small>
<source lang="python">
class Decoder(srd.Decoder):
...
id = 'spi'
...
channels = (
{'id': 'clk', 'name': 'CLK', 'desc': 'Clock'},
)
optional_channels = (
{'id': 'miso', 'name': 'MISO', 'desc': 'Master in, slave out'},
{'id': 'mosi', 'name': 'MOSI', 'desc': 'Master out, slave in'},
{'id': 'cs', 'name': 'CS#', 'desc': 'Chip-select'},
)
</source>
</small>

'''<tt>data</tt>''', the argument of the decoder's [[Protocol decoder API#decode-function|'''<tt>decode()</tt>''']] function that contains the data to decode, is a list of tuples. These tuples contain the (absolute) number of the sample and the data at that sample. To process all samples, the SPI decoder loops over '''<tt>data</tt>''' like this:

<small>
<source lang="python">
def decode(self, ss, es, data):
...
for (self.samplenum, pins) in data:
</source>
</small>

'''<tt>channels</tt>''' and '''<tt>optional_channels</tt>''' contain in total four channels, therefore the second member of the tuple is an object of Python's [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''] class containing 4 bytes, one for each channel. The decoder unpacks the bytes into the variables '''<tt>clk</tt>''', '''<tt>miso</tt>''', '''<tt>mosi</tt>''', and '''<tt>cs</tt>''' as shown below.

Then, it checks for the optional channels, if their value is either 0 or 1. If it is not, that optional channel is not provided to the decoder. In the case that neither of them is supplied, an exception is raised:

<small>
<source lang="python">
(clk, miso, mosi, cs) = pins
self.have_miso = (miso in (0, 1))
self.have_mosi = (mosi in (0, 1))
self.have_cs = (cs in (0, 1))

# Either MISO or MOSI (but not both) can be omitted.
if not (self.have_miso or self.have_mosi):
raise ChannelError('Either MISO or MOSI (or both) pins required.')
</source>
</small>

== <tt>annotations</tt> & <tt>annotation_rows</tt> ==

To make the relation between the '''<tt>annotations</tt>''' and the '''<tt>annotation_rows</tt>''' members of a decoder object more clear, take a look at how the [[Protocol_decoder:Ir_nec|ir_nec]] PD uses them:

<small>
<source lang="python">
class Decoder(srd.Decoder):
...
id = 'ir_nec'
...
annotations = ( # Implicitly assigned annotation type ID
('bit', 'Bit'), # 0
('agc-pulse', 'AGC pulse'), # 1
('longpause', 'Long pause'), # 2
('shortpause', 'Short pause'), # 3
('stop-bit', 'Stop bit'), # 4
('leader-code', 'Leader code'), # 5
('addr', 'Address'), # 6
('addr-inv', 'Address#'), # 7
('cmd', 'Command'), # 8
('cmd-inv', 'Command#'), # 9
('repeat-code', 'Repeat code'), # 10
('remote', 'Remote'), # 11
('warnings', 'Warnings'), # 12
)
annotation_rows = (
('bits', 'Bits', (0, 1, 2, 3, 4)),
('fields', 'Fields', (5, 6, 7, 8, 9, 10)),
('remote', 'Remote', (11,)),
('warnings', 'Warnings', (12,)),
)
</source>
</small>

It groups the first five annotation types together into the '''<tt>bits</tt>''' row and the next six into the '''<tt>fields</tt>''' row. The rows '''<tt>remote</tt>''' and '''<tt>warnings</tt>''' both only contain one annotation type.

Without '''<tt>annotation_rows</tt>''', [[PulseView]] would have to put each annotation type in its own row (which is unhandy if the decoder has many annotations) or it would have to put them all on the same row (which would result in unreadable output due to overlaps). But because of the '''<tt>annotation_rows</tt>''', the output of the [[Protocol_decoder:Ir_nec|ir_nec]] decoder is grouped together as shown in the following picture (note how different annotation types, distinguishable by their different colors, share the same row):

[[File:Pv example ir nec cropped.png]]

However, as you can imagine, handling numeric IDs is quite bothersome - especially if they change and all affected IDs have to be changed throughout the PD. To avoid this, you can use a pseudo-enum:

<small>
<source lang="python">
ann_bit, ann_agc_pulse, ann_long_pause, ann_short_pause, ann_stop_bit, ann_leader_code, ann_addr, ann_addr_inv, ann_cmd, ann_cmd_inv, ann_repeat_code, ann_remote, ann_warning = range(13)

class Decoder(srd.Decoder):
...
id = 'ir_nec'
...
annotations = ( # Implicitly assigned annotation type ID
('bit', 'Bit'), # 0 = ann_bit
('agc-pulse', 'AGC pulse'), # 1 = ann_agc_pulse
('longpause', 'Long pause'), # 2 = ann_long_pause
('shortpause', 'Short pause'), # 3 = ann_short_pause
('stop-bit', 'Stop bit'), # 4 = ann_stop_bit
('leader-code', 'Leader code'), # 5 = ann_leader_code
('addr', 'Address'), # 6 = ann_addr
('addr-inv', 'Address#'), # 7 = ann_addr_inv
('cmd', 'Command'), # 8 = ann_cmd
('cmd-inv', 'Command#'), # 9 = ann_cmd_inv
('repeat-code', 'Repeat code'), # 10 = ann_repeat_code
('remote', 'Remote'), # 11 = ann_remote
('warnings', 'Warnings'), # 12 = ann_warning
)
annotation_rows = (
('bits', 'Bits', (ann_bit, ann_agc_pulse, ann_long_pause, ann_short_pause, ann_stop_bit)),
('fields', 'Fields', (ann_leader_code, ann_addr, ann_addr_inv, ann_cmd, ann_cmd_inv, ann_repeat_code)),
('remote', 'Remote', (ann_remote,)),
('warnings', 'Warnings', (ann_warning,)),
)
</source>
</small>

This way, all you need to ensure is that the order of the enum entries is the same as in the annotations array and you're set. There is one downside, though, as always: pseudo-enums are pitifully slow in python, so if you use them and you use them in a lot of places, your protocol decoder may be significantly slower (up to 4x has been observed), so choose wisely. You can use the PD test facility to compare, using e.g. 'time ./pdtest -r $YOUR_PD'

== Random notes, tips and tricks ==

* You should usually only use '''raise''' in a protocol decoder to raise exceptions in cases which are a clear bug in how the protocol decoder is invoked (e.g. if no samplerate was provided for a PD which needs the samplerate, or if some of the required channels were not provided by the user, and so on).
* Use the <code>has_channel()</code> method to check whether an optional channel has been provided or not.
* A simple and fast way to calculate a parity (i.e., count the number of 1 bits) over a number (0x55 in this example) is:<source lang="python">
ones = bin(0x55).count('1')
</source>
* A simple function to convert a BCD number (max. 8 bits) to an integer is:<source lang="python">
def bcd2int(b):
return (b & 0x0f) + ((b >> 4) * 10)
</source> This is available as <code>from common.srdhelper import bcd2int</code>
* An elegant way to convert a sequence of bus pins to a numeric value:<source lang="python">
from functools import reduce

def reduce_bus(bus):
if 0xFF in bus:
return None # unassigned bus channels
else:
return reduce(lambda a, b: (a << 1) | b, reversed(bus))
</source>
* A nice way to construct method names according to e.g. protocol commands is (assuming '''cmd''' is 8, this would call the function '''self.handle_cmd_0x08'''):<source lang="python">
fn = getattr(self, 'handle_cmd_0x%02x' % cmd);
fn(arg1, arg2, ...)
</source>
* A cheap way to deal with Python's lack of enumerations (useful for states, pin indices, annotation indices, etc.):<source lang="python">
class Cycle:
NONE, MEMRD, MEMWR, IORD, IOWR, FETCH, INTACK = range(7)
</source>Please be aware, though, that using this mechanism may slow down your decoder significantly. It may make sense to perform some basic profiling to see if this affects you, e.g. using <code>time ./pdtest -r $YOUR_PD</code>.
** A class <code>SrdIntEnum</code> is now available from <code>common.srdhelper</code> based on Python's native [https://docs.python.org/3/library/enum.html#enum.IntEnum <code>IntEnum</code>]
* <div id="SIGROKDECODE_DIR"></div>You don't need to reinstall the whole [[libsigrokdecode]] project every time you make a change on your decoder. Instead, you can use the environment variable '''<tt>SIGROKDECODE_DIR</tt>''' to point the software to your development directory:<br /><source lang="bash">$ SIGROKDECODE_DIR=/path/to/libsigrokdecode/decoders/ sigrok-cli … -P <decodername></source>Because this environment variable is evaluated by the [[libsigrokdecode]] code itself, it can be used for any program that uses the library, for example when calling [[PulseView]] or the '''<tt>pdtest</tt>''' unit test utility from the [http://sigrok.org/gitweb/?p=sigrok-test.git;a=summary sigrok-test] repository.<br />If you compiled a recent [[libsigrokdecode]] by yourself ([http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=commit;h=40c6ac1d3fbded276dcbff23e8bc099896ab2fb5 newer than this commit]), you can also put decoders into your home directory, without the need for an additional environment variable. On Linux systems, this name follows the [http://standards.freedesktop.org/basedir-spec/latest/ar01s03.html XDG base directory specification], which by default resolves to <tt>~/.local/share/libsigrokdecode/decoders</tt>. If that folder does not exist, you can simply create it and drop your decoders there, in their own subdirectory, like you would do in the libsigrokdecode source tree. On Windows systems additional decoders are read from <tt>%ProgramData%\libsigrokdecode\decoders</tt>.

* To debug the Python implementation of a decoder during development, maintenance or research either add <code>print()</code> statements at appropriate locations. Or get WinPDB and use the remote debugging feature as outlined below (add this hook somewhere in pd.py, then "File -> Attach" to the running process). Decoders cannot be used in "regular" debuggers since they expect a rather specific environment to execute in, for all of receiving their input as well as having their output saved or presented as well as processing samples (data types, runtime routines). Remote debugging works in both the sigrok-cli and pulseview context. Adding another <code>print()</code> statement before starting the embedded debugger can help identify the moment in time when to attach.<source lang="python">
def __init__():
import rpdb2
rpdb2.start_embedded_debugger("pd")
...
</source>

For Windows you might want to use the following code, adapting it to your Python and WinPDB-reborn version:<source lang="python">
def __init__():
import sys
sys.path.insert(0, 'c:/Program Files (x86)/Python38-32/Lib/site-packages/winpdb_reborn-2.0.0.1-py3.8.egg')
import rpdb2
rpdb2.start_embedded_debugger("pd", fAllowRemote=True)
...
</source>

== Unit tests ==

In order to keep protocol decoders in a running state even when we make changes to a decoder or libsigrokdecode itself, we use unit tests for as many decoders as we can. These are stored in the [http://sigrok.org/gitweb/?p=sigrok-test.git sigrok-test repository]. If you want to add, modify or run one of them, clone that repository and [https://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=README check the README] for documentation.
We greatly appreciate it when you submit unit tests for your decoder so we can keep it in good health!

The following is step-by step guide.

=== libsigrokdecode ===
Assuming that you have cloned the [https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=summary libsigrokdecode] repository and are ready to run some testing.

=== Clone and build sigrok-util ===
Clone and build [https://sigrok.org/gitweb/?p=sigrok-util.git;a=summary sigrok-util]:

<small>
$ git clone git://sigrok.org/sigrok-util
$ cd sigrok-util/cross-compile/linux
$ ./sigrok-cross-linux
</small>

This will take a while, but should create <code>~/sr/</code> directory.

==== Test error ====
If you see following error ...

<small>
Running tests...
Test project ~/devel/sigrok-util/cross-compile/linux/build/pulseview/build
Start 1: test
1/1 Test #1: test .............................***Failed 9.69 sec

0% tests passed, 1 tests failed out of 1

Total Test time (real) = 9.69 sec

The following tests FAILED:
1 - test (Failed)
Errors while running CTest
Output from these tests are in: ~/devel/sigrok-util/cross-compile/linux/build/pulseview/build/Testing/Temporary/LastTest.log
Use "--rerun-failed --output-on-failure" to re-run the failed cases verbosely.
make: *** [Makefile:91: test] Error 8
</small>

... and the log contains only these failed tests ...

<small>
Output:
----------------------------------------------------------
Running 11 test cases...
~/devel/sigrok-util/cross-compile/linux/build/pulseview/test/util.cpp(220): error: in "UtilTest/format_time_minutes_test": check fmt(ts(12000), 0) == "+3:20:00" has failed [+3:19:60 != +3:20:00]
~/devel/sigrok-util/cross-compile/linux/build/pulseview/test/util.cpp(221): error: in "UtilTest/format_time_minutes_test": check fmt(ts(15000), 0) == "+4:10:00" has failed [+4:09:60 != +4:10:00]

*** 2 failures are detected in the test module "Master Test Suite"

<end of output>
Test time = 4.43 sec
----------------------------------------------------------
</small>

... you can ignore the error.

=== Clone and build sigrok-dumps ===
Clone and build [https://sigrok.org/gitweb/?p=sigrok-dumps.git;a=summary sigrok-dumps]. This repository should be in the same location as <code>libsigrokdecode</code> repository.

<small>
$ git clone git://sigrok.org/sigrok-dumps
$ cd sigrok-dumps
$ make install
</small>

=== Clone and build sigrok-test ===
Clone and build [https://sigrok.org/gitweb/?p=sigrok-test.git;a=summary sigrok-test].

Do not forget to change the <code>--with-decodersdir=/path/to/decoders</code> to point to <code>decoders</code> directory in your cloned <code>libsigrokdecode</code> repository.
<small>
$ git clone git://sigrok.org/sigrok-test
$ cd sigrok-test
$ ./autogen.sh
$ PKG_CONFIG_PATH=$HOME/sr/lib/pkgconfig ./configure --with-decodersdir=/path/to/decoders
$ make
</small>

=== Run tests ===
<small>
$ LD_LIBRARY_PATH=$HOME/sr/lib ./decoder/pdtest -r -v -a
</small>

For more information see [https://sigrok.org/gitweb/?p=sigrok-test.git;a=blob_plain;f=README;hb=HEAD README.md in sigrok-test] repository.

== Submitting your decoder ==

When you've finished your decoder and everything is working nicely, please contribute the decoder to the sigrok project so that other people can benefit from it (and test it, improve upon it, and so on).

* Check the decoder's operation in the most recent version of the software. You expect the decoder to get accepted in the project's mainline codebase. So it should work in that environment. Either build from up-to-date sources, or download nightly builds.
* Tell us about the location of your public git repo on the '''#sigrok''' IRC channel on libera.chat. As an alternative send the decoder to the [https://lists.sourceforge.net/lists/listinfo/sigrok-devel sigrok-devel] mailing list (preferrably against current master and as a full commit instead of a mere diff). Remember that pushing to a public git repo is preferred over email attachments.
* Please also make example data files (*.sr) including a small README available. Developers need these in order to properly review and test your decoder. Users need these to learn what the captures are about in the first place. Preferrably these files should also come as patches against the latest git master of the [http://sigrok.org/gitweb/?p=sigrok-dumps.git;a=tree sigrok-dumps] repository. See [[Example dumps]] for details. Submitting captures before any decoder materializes or work on a decoder even starts is very useful.
* Finally, please also consider adding a few "unit tests" for your decoder in the [http://sigrok.org/gitweb/?p=sigrok-test.git;a=tree sigrok-test] repository. These test will automatically run the decoder against various input files specified in '''test.conf''' and check whether the expected output is produced (examples: [http://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=decoder/test/rfm12/test.conf rfm12], [http://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=decoder/test/nrf24l01/test.conf nrf24l01]). This allows us to notice and fix any regressions in the decoder and/or the [[libsigrokdecode]] backend that may arise over time.

Thanks a lot!

[[Category:APIs]]