1SIGROK-CLI(1) General Commands Manual SIGROK-CLI(1)
2
6 sigrok-cli - Command-line client for the sigrok software
7
9 sigrok-cli [OPTIONS] [COMMAND]
10
12 sigrok-cli is a cross-platform command line utility for the sigrok
13 software.
14 It cannot display graphical output, but is still sufficient to run
16 through the whole process of hardware initialization, acquisition, pro‐
17 tocol decoding and saving the session.
18 It is useful for running on remote or embedded systems, netbooks, PDAs,
20 and for various other use-cases. It can display samples on standard
21 output or save them in various file formats.
22
24 -h, --help
25 Show a help text and exit.
26 -V, --version
28 Show sigrok-cli version and the versions of libraries used.
29 -L, --list-supported
31 Show information about supported hardware drivers, input file
32 formats, output file formats, and protocol decoders.
33 --list-supported-wiki
35 Show information about supported protocol decoders in MediaWiki
36 syntax. This is generally only used by developers to easily
37 update the list of supported protocol decoders in the sigrok
38 wiki.
39 -d, --driver <drivername>
41 Unless doing a global scan, users typically select one of the
42 available drivers. This can speedup program start, and can avoid
43 false matches for ambiguous configurations. Selecting a driver
44 also allows to pass more driver specific options. Use the -L
45 (--list-supported) option to get a list of available drivers.
46 Drivers can take options, in the form key=value separated by
48 colons.
49 Drivers communicating with hardware via a serial port always
51 need the port specified as the conn option. For example, to use
52 the Openbench Logic Sniffer:
53 $ sigrok-cli --driver=ols:conn=/dev/ttyACM0 [...]
55 Some USB devices don't use a unique VendorID/ProductID combina‐
57 tion, and thus need that specified as well. Notice that colons
58 are used to separate the driver name from the conn option, thus
59 colons cannot be used within the conn option's argument. To
60 select a specific USB device, use either VendorID.ProductID or
61 bus.address:
62 USB VendorID.ProductID example:
64 $ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]
66 USB bus.address example:
68 $ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]
70 -D, --dont-scan
72 Do not automatically scan for device drivers in the absence of a
73 -d (--driver) specification.
74 -c, --config <deviceoption>
76 A colon-separated list of device options, where each option
77 takes the form key=value. Multiple occurances of the --config
78 option are supported. The first item in the list of options can
79 take the form channel_group=<name> which would override the
80 --channel-group specification for this list of options. Other
81 option lists in other --config occurances are not affected by
82 this list's channel group name.
83 For example, to set the samplerate to 1MHz on a device supported
85 by the fx2lafw driver, you might specify
86 $ sigrok-cli -d fx2lafw --config samplerate=1m [...]
88 Samplerate is an option common to most logic analyzers. The
90 argument specifies the samplerate in Hz. You can also specify
91 the samplerate in kHz, MHz or GHz. The following are all equiv‐
92 alent:
93 $ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]
95 $ sigrok-cli -d fx2lafw --config samplerate=1m [...]
97 $ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]
99 These examples specify options within a channel group. The
101 first two are equivalent.
102 $ sigrok-cli -d demo --channel-group Logic --config pat‐
104 tern=random [...]
105 $ sigrok-cli -d demo --config channel_group=Logic:pattern=ran‐
107 dom [...]
108 $ sigrok-cli -d demo --config samplerate=1m --config chan‐
110 nel_group=Logic:pattern=random [...]
111 -i, --input-file <filename>
113 Load input from a file instead of a hardware device. You can
114 specify "-" to use stdin as input. If the --input-format option
115 is not supplied, sigrok-cli attempts to autodetect the file for‐
116 mat of the input file.
117 Example for loading a sigrok session file:
119 $ sigrok-cli -i example.sr [...]
121 Example for loading a WAV file (autodetection of input format):
123 $ sigrok-cli -i example.wav [...]
125 Example for loading a VCD file from stdin (autodetection of
127 input format):
128 $ cat example.vcd | sigrok-cli -i - [...]
130 -I, --input-format <format>
132 When loading an input file, assume it's in the specified format.
133 If this option is not supplied (in addition to --input-file),
134 sigrok-cli attempts to autodetect the file format of the input
135 file. Use the -L (--list-supported) option to see a list of
136 available input formats.
137 The format name may optionally be followed by a colon-separated
139 list of options, where each option takes the form key=value.
140 Example for loading a binary file with options:
142 $ sigrok-cli -i example.bin
144 -I binary:numchannels=4:samplerate=1mhz [...]
145 -o, --output-file <filename>
147 Save output to a file instead of writing it to stdout. The
148 default format used when saving is the sigrok session file for‐
149 mat. This can be changed with the --output-format option.
150 Example for saving data in the sigrok session format:
152 $ sigrok-cli [...] -o example.sr
154 -O, --output-format <format>
156 Set the output format to use. Use the -L (--list-supported)
157 option to see a list of available output formats.
158 The format name may optionally be followed by a colon-separated
160 list of options, where each option takes the form key=value.
161 For example, the bits or hex formats, for an ASCII bit or ASCII
163 hexadecimal display, can take a "width" option, specifying the
164 number of samples (in bits) to display per line. Thus -O
165 hex:width=128 will display 128 bits per line, in hexadecimal:
166 0:ffff ffff ffff ffff ffff ffff ffff ffff
168 1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
169 The lines always start with the channel number (or name, if
171 defined), followed by a colon. If no format is specified, it
172 defaults to bits:width=64, like this:
173 0:11111111 11111111 11111111 11111111 [...]
175 1:11111111 00000000 11111111 00000000 [...]
176 Example for saving data in the CSV format with options:
178 $ sigrok-cli [...] -o example.csv -O csv:dedup:header=false
180 Notice that boolean options are true when no value gets speci‐
182 fied.
183 -C, --channels <channellist>
185 A comma-separated list of channels to be used in the session.
186 Note that sigrok always names the channels according to how
188 they're shown on the enclosure of the hardware. If your logic
189 analyzer numbers the channels 0-15, that's how you must specify
190 them with this option. An oscilloscope's channels would gener‐
191 ally be referred to as "CH1", "CH2", and so on. Use the --show
192 option to see a list of channel names for your device.
193 The default is to use all the channels available on a device.
195 You can name a channel like this: 1=CLK. A range of channels
196 can also be given, in the form 1-5.
197 Example:
199 $ sigrok-cli --driver fx2lafw --samples 100
201 --channels 1=CLK,2-4,7
202 CLK:11111111 11111111 11111111 11111111 [...]
203 2:11111111 11111111 11111111 11111111 [...]
204 3:11111111 11111111 11111111 11111111 [...]
205 4:11111111 11111111 11111111 11111111 [...]
206 7:11111111 11111111 11111111 11111111 [...]
207 The comma-separated list is processed from left to right, i.e.
209 items farther to the right override previous items. For example
210 1=CS,CS=MISO will set the name of channel 1 to MISO.
211 -g, --channel-group <channel group>
213 Specify the channel group to operate on. Some devices organize
214 channels into groups, the settings of which can only be changed
215 as a group. The list of channel groups, if any, is displayed
216 with the --show command.
217 Examples:
219 $ sigrok-cli -g CH1 [...]
221 $ sigrok-cli -d demo -g Logic -c pattern=graycode [...]
223 Channel group specifications in --get or --config options take
225 precedence over channel group names in --channel-group so that a
226 single sigrok-cli invocation can support the query or manipula‐
227 tion of multiple device options which reside in different chan‐
228 nel groups.
229 -t, --triggers <triggerlist>
231 A comma-separated list of triggers to use, of the form <chan‐
232 nel>=<trigger>. You can use the name or number of the channel,
233 and the trigger itself is a series of characters:
234 0 or 1: A low or high value on the pin.
236 r or f: A rising or falling value on the pin. An r effectively
237 corresponds to 01.
238 e: Any kind of change on a pin (either a rising or a falling
239 edge).
240 Not every device supports all of these trigger types. Use the
242 --show command to see which triggers your device supports.
243 -w, --wait-trigger
245 Don't output any sample data (even if it's actually received
246 from the hardware) before the trigger condition is met. In other
247 words, do not output any pre-trigger data. This option is useful
248 if you don't care about the data that came before the trigger
249 (but the hardware delivers this data to sigrok nonetheless).
250 -P, --protocol-decoders <list>
252 This option allows the user to specify a comma-separated list of
253 protocol decoders to be used in this session. The decoders are
254 specified by their ID, as shown in the -L (--list-supported)
255 output.
256 Example:
258 $ sigrok-cli -i <file.sr> -P i2c
260 Each protocol decoder can optionally be followed by a colon-sep‐
262 arated list of options, where each option takes the form
263 key=value.
264 Example:
266 $ sigrok-cli -i <file.sr>
268 -P uart:baudrate=115200:parity_type=odd
269 The list of supported options depends entirely on the protocol
271 decoder. Every protocol decoder has different options it sup‐
272 ports.
273 Any "options" specified for a protocol decoder which are not
275 actually supported options, will be interpreted as being channel
276 name/number assignments.
277 Example:
279 $ sigrok-cli -i <file.sr>
281 -P spi:wordsize=9:miso=1:mosi=5:clk=3:cs=0
282 In this example, wordsize is an option supported by the spi pro‐
284 tocol decoder. Additionally, the user tells sigrok to decode the
285 SPI protocol using channel 1 as MISO signal for SPI, channel 5
286 as MOSI, channel 3 as CLK, and channel 0 as CS# signal.
287 Notice that the sigrok-cli application does not support "name
289 matching". Instead it's assumed that the traces in the input
290 stream match the order of the decoder's input signals, or that
291 users explicitly specify the input channel to decoder signal
292 mapping.
293 When multiple decoders are specified in the same -P option, they
295 will be stacked on top of each other in the specified order.
296 Example:
298 $ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
300 $ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi
301 When multiple -P options are specified, each of them creates one
303 decoder stack, which executes in parallel to other decoder
304 stacks.
305 Example:
307 $ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2
309 -A, --protocol-decoder-annotations <annotations>
312 By default, all annotation output of all protocol decoders is
313 shown. With this option a specific decoder's annotations can be
314 selected for display, by specifying the decoder ID:
315 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid -A i2c
317 If a protocol decoder has multiple annotation classes, you can
319 also specify which one of them to show by specifying its short
320 description like this:
321 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
323 -A i2c=data-read
324 Select multiple annotation classes by separating them with a
326 colon:
327 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
329 -A i2c=data-read:data-write
330 Annotation row names will resolve to their respective list of
332 classes. Row and class names can be used in combination. When
333 names are ambiguous then class names take precedence.
334 $ sigrok-cli -i <file.sr> -P i2c
336 -A i2c=addr-data:warnings
337 You can also select multiple protocol decoders, with optionally
339 selected annotation classes each, by separating them with com‐
340 mas:
341 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
343 -A i2c=data-read:data-write,edid
344 -M, --protocol-decoder-meta <pdname>
346 When given, show protocol decoder meta output instead of annota‐
347 tions. The argument is the name of the decoder whose meta out‐
348 put to show.
349 $ sigrok-cli -i <file.sr> -M i2c
351 Not every decoder generates meta output.
353 -B, --protocol-decoder-binary <binaryspec>
355 When given, decoder "raw" data of various kinds is written to
356 stdout instead of annotations (this could be raw binary UART/SPI
357 bytes, or WAV files, PCAP files, PNG files, or anything else;
358 this is entirely dependent on the decoder and what kinds of
359 binary output make sense for that decoder).
360 No other information is printed to stdout, so this is suitable
362 for piping into other programs or saving to a file.
363 Protocol decoders that support binary output publish a list of
365 binary classes, for example the UART decoder might have "TX" and
366 "RX". To select TX for output, the argument to this option would
367 be:
368 $ sigrok-cli -i <file.sr> -B uart=tx
370 If only the protocol decoder is specified, without binary class,
372 all classes are written to stdout:
373 $ sigrok-cli -i <file.sr> -B uart
375 (this is only useful in rare cases, generally you would specify
377 a certain binary class you're interested in)
378 Not every decoder generates binary output.
380 --protocol-decoder-samplenum
382 When given, decoder annotations will include sample numbers,
383 too. This allows consumers to receive machine readable timing
384 information.
385 -l, --loglevel <level>
387 Set the libsigrok and libsigrokdecode loglevel. At the moment
388 sigrok-cli doesn't support setting the two loglevels indepen‐
389 dently. The higher the number, the more debug output will be
390 printed. Valid loglevels are:
391 0 None
393 1 Error
394 2 Warnings
395 3 Informational
396 4 Debug
397 5 Spew
398 --show
400 Show information about the selected option. For example, to see
401 options for a connected fx2lafw device:
402 $ sigrok-cli --driver fx2lafw --show
404 In order to properly get device options for your hardware, some
406 drivers might need a serial port specified:
407 $ sigrok-cli --driver ols:conn=/dev/ttyACM0 --show
409 This also works for protocol decoders, input modules and output
411 modules:
412 $ sigrok-cli --protocol-decoders i2c --show
414 $ sigrok-cli --input-format csv --show
415 $ sigrok-cli --output-format bits --show
416 This also works for input files, including optional input format
418 specifications:
419 $ sigrok-cli --input-file <file.sr> --show
421 $ sigrok-cli --input-file <file.vcd> --input-format vcd --show
422 --scan Scan for devices that can be detected automatically.
424 Example:
426 $ sigrok-cli --scan
428 The following devices were found:
429 demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
430 A1 A2 A3
431 fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 0 1 2 3 4 5
432 6 7
433 However, not all devices are auto-detectable (e.g. serial port
435 based ones). For those you'll have to provide a conn option,
436 see above.
437 $ sigrok-cli --driver digitek-dt4000zc:conn=/dev/ttyUSB0 --scan
439 The following devices were found:
440 Digitek DT4000ZC with 1 channel: P1
441 --time <ms>
443 Sample for <ms> milliseconds, then quit.
444 You can optionally follow the number by s to specify the time to
446 sample in seconds.
447 For example, --time 2s will sample for two seconds.
449 --samples <numsamples>
451 Acquire <numsamples> samples, then quit.
452 You can optionally follow the number by k, m, or g to specify
454 the number of samples in kilosamples, megasamples, or gigasam‐
455 ples, respectively.
456 For example, --samples 3m will acquire 3000000 samples.
458 --frames <numframes>
460 Acquire <numframes> frames, then quit.
461 --continuous
463 Sample continuously until stopped. Not all devices support this.
464 --get <variable>
466 Get the value of <variable> from the specified device and print
467 it. Multiple variable names can be specified and get separated
468 by colon. The list of variable names optionally can be pre‐
469 ceeded by channel_group=<name> which would override the --chan‐
470 nel-group specification. Multiple --get occurances are sup‐
471 ported in a single sigrok-cli invocation.
472 $ sigrok-cli -d demo --get samplerate:averaging --get chan‐
474 nel_group=Logic:pattern
475 --set Set one or more variables specified with the --config option,
477 without doing any acquisition.
478
480 In order to get exactly 100 samples from the connected fx2lafw-sup‐
481 ported logic analyzer hardware, run the following command:
482 sigrok-cli --driver fx2lafw --samples 100
484 If you want to sample data for 3 seconds (3000 ms), use:
486 sigrok-cli --driver fx2lafw --time 3000
488 Alternatively, you can also use:
490 sigrok-cli --driver fx2lafw --time 3s
492 To capture data from the first 4 channels using the Openbench Logic
494 Sniffer lasting 100ms at 10 MHz starting at the trigger condition
495 0:high, 1:rising, 2:low, 3:high, use:
496 sigrok-cli --driver ols:conn=/dev/ttyACM0 --config samplerate=10m \
498 --output-format bits --channels 0-3 --wait-trigger \
499 --triggers 0=1,1=r,2=0,3=1 --time 100
500 To turn on internal logging on a Lascar EL-USB series device:
502 sigrok-cli --driver lascar-el-usb:conn=10c4.0002 \
504 --config datalog=on --set
505
507 sigrok-cli exits with 0 on success, 1 on most failures.
508
510 pulseview(1)
511
513 Please report any bugs via Bugzilla (http://sigrok.org/bugzilla) or on
514 the sigrok-devel mailing list (sigrok-devel@lists.souceforge.net).
515
517 sigrok-cli is covered by the GNU General Public License (GPL). Some
518 portions are licensed under the "GPL v2 or later", some under "GPL v3
519 or later".
520
522 Please see the individual source code files.
523 This manual page was written by Uwe Hermann <uwe@hermann-uwe.de>. It
525 is licensed under the terms of the GNU GPL (version 2 or later).
526 March 28, 2019 SIGROK-CLI(1)