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 -d, --driver <drivername>
35 A driver must always be selected (unless doing a global scan).
36 Use the -L (--list-supported) option to get a list of available
37 drivers.
38 Drivers can take options, in the form key=value separated by
40 colons.
41 Drivers communicating with hardware via a serial port always
43 need the port specified as the conn option. For example, to use
44 the Openbench Logic Sniffer:
45 $ sigrok-cli --driver=ols:conn=/dev/ttyACM0 [...]
47 Some USB devices don't use a unique VendorID/ProductID combina‐
49 tion, and thus need that specified as well. This also uses the
50 conn option, using either VendorID.ProductID or bus.address:
51 USB VendorID.ProductID example:
53 $ sigrok-cli --driver=uni-t-ut61e:conn=1a86.e008 [...]
55 USB bus.address example:
57 $ sigrok-cli --driver=uni-t-ut61e:conn=4.6 [...]
59 -c, --config <deviceoption>
61 A colon-separated list of device options, where each option
62 takes the form key=value. For example, to set the samplerate to
63 1MHz on a device supported by the fx2lafw driver, you might
64 specify
65 $ sigrok-cli -d fx2lafw --config samplerate=1m [...]
67 Samplerate is an option common to most logic analyzers. The
69 argument specifies the samplerate in Hz. You can also specify
70 the samplerate in kHz, MHz or GHz. The following are all equiv‐
71 alent:
72 $ sigrok-cli -d fx2lafw --config samplerate=1000000 [...]
74 $ sigrok-cli -d fx2lafw --config samplerate=1m [...]
76 $ sigrok-cli -d fx2lafw --config "samplerate=1 MHz" [...]
78 -i, --input-file <filename>
80 Load input from a file instead of a hardware device. You can
81 specify "-" to use stdin as input. If the --input-format option
82 is not supplied, sigrok-cli attempts to autodetect the file for‐
83 mat of the input file.
84 Example for loading a sigrok session file:
86 $ sigrok-cli -i example.sr [...]
88 Example for loading a WAV file (autodetection of input format):
90 $ sigrok-cli -i example.wav [...]
92 Example for loading a VCD file from stdin (autodetection of
94 input format):
95 $ cat example.vcd | sigrok-cli -i - [...]
97 -I, --input-format <format>
99 When loading an input file, assume it's in the specified format.
100 If this option is not supplied (in addition to --input-file),
101 sigrok-cli attempts to autodetect the file format of the input
102 file. Use the -L (--list-supported) option to see a list of
103 available input formats.
104 The format name may optionally be followed by a colon-separated
106 list of options, where each option takes the form key=value.
107 Example for loading a binary file with options:
109 $ sigrok-cli -i example.bin
111 -I binary:numchannels=4:samplerate=1mhz [...]
112 -o, --output-file <filename>
114 Save output to a file instead of writing it to stdout. The
115 default format used when saving is the sigrok session file for‐
116 mat. This can be changed with the --output-format option.
117 Example for saving data in the sigrok session format:
119 $ sigrok-cli [...] -o example.sr
121 -O, --output-format <format>
123 Set the output format to use. Use the -L (--list-supported)
124 option to see a list of available output formats.
125 The format name may optionally be followed by a colon-separated
127 list of options, where each option takes the form key=value.
128 For example, the bits or hex formats, for an ASCII bit or ASCII
130 hexadecimal display, can take a "width" option, specifying the
131 number of samples (in bits) to display per line. Thus -O
132 hex:width=128 will display 128 bits per line, in hexadecimal:
133 0:ffff ffff ffff ffff ffff ffff ffff ffff
135 1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
136 The lines always start with the channel number (or name, if
138 defined), followed by a colon. If no format is specified, it
139 defaults to bits:width=64, like this:
140 0:11111111 11111111 11111111 11111111 [...]
142 1:11111111 00000000 11111111 00000000 [...]
143 Example for saving data in the CSV format with options:
145 $ sigrok-cli [...] -o example.csv -O csv:dedup:header=false
147 Notice that boolean options are true when no value gets speci‐
149 fied.
150 -C, --channels <channellist>
152 A comma-separated list of channels to be used in the session.
153 Note that sigrok always names the channels according to how
155 they're shown on the enclosure of the hardware. If your logic
156 analyzer numbers the channels 0-15, that's how you must specify
157 them with this option. An oscilloscope's channels would gener‐
158 ally be referred to as "CH1", "CH2", and so on. Use the --show
159 option to see a list of channel names for your device.
160 The default is to use all the channels available on a device.
162 You can name a channel like this: 1=CLK. A range of channels
163 can also be given, in the form 1-5.
164 Example:
166 $ sigrok-cli --driver fx2lafw --samples 100
168 --channels 1=CLK,2-4,7
169 CLK:11111111 11111111 11111111 11111111 [...]
170 2:11111111 11111111 11111111 11111111 [...]
171 3:11111111 11111111 11111111 11111111 [...]
172 4:11111111 11111111 11111111 11111111 [...]
173 7:11111111 11111111 11111111 11111111 [...]
174 The comma-separated list is processed from left to right, i.e.
176 items farther to the right override previous items. For example
177 1=CS,CS=MISO will set the name of channel 1 to MISO.
178 -g, --channel-group <channel group>
180 Specify the channel group to operate on. Some devices organize
181 channels into groups, the settings of which can only be changed
182 as a group. The list of channel groups, if any, is displayed
183 with the --show command.
184 Examples:
186 $ sigrok-cli -g CH1 [...]
188 $ sigrok-cli -d demo -g Logic -c pattern=graycode [...]
190 -t, --triggers <triggerlist>
192 A comma-separated list of triggers to use, of the form <chan‐
193 nel>=<trigger>. You can use the name or number of the channel,
194 and the trigger itself is a series of characters:
195 0 or 1: A low or high value on the pin.
197 r or f: A rising or falling value on the pin. An r effectively
198 corresponds to 01.
199 e: Any kind of change on a pin (either a rising or a falling
200 edge).
201 Not every device supports all of these trigger types. Use the
203 --show command to see which triggers your device supports.
204 -w, --wait-trigger
206 Don't output any sample data (even if it's actually received
207 from the hardware) before the trigger condition is met. In other
208 words, do not output any pre-trigger data. This option is useful
209 if you don't care about the data that came before the trigger
210 (but the hardware delivers this data to sigrok nonetheless).
211 -P, --protocol-decoders <list>
213 This option allows the user to specify a comma-separated list of
214 protocol decoders to be used in this session. The decoders are
215 specified by their ID, as shown in the -L (--list-supported)
216 output.
217 Example:
219 $ sigrok-cli -i <file.sr> -P i2c
221 Each protocol decoder can optionally be followed by a colon-sep‐
223 arated list of options, where each option takes the form
224 key=value.
225 Example:
227 $ sigrok-cli -i <file.sr>
229 -P uart:baudrate=115200:parity_type=odd
230 The list of supported options depends entirely on the protocol
232 decoder. Every protocol decoder has different options it sup‐
233 ports.
234 Any "options" specified for a protocol decoder which are not
236 actually supported options, will be interpreted as being channel
237 name/number assignments.
238 Example:
240 $ sigrok-cli -i <file.sr>
242 -P spi:wordsize=9:miso=1:mosi=5:clk=3:cs=0
243 In this example, wordsize is an option supported by the spi pro‐
245 tocol decoder. Additionally, the user tells sigrok to decode the
246 SPI protocol using channel 1 as MISO signal for SPI, channel 5
247 as MOSI, channel 3 as CLK, and channel 0 as CS# signal.
248 Notice that the sigrok-cli application does not support "name
250 matching". Instead it's assumed that the traces in the input
251 stream match the order of the decoder's input signals, or that
252 users explicitly specify the input channel to decoder signal
253 mapping.
254 When multiple decoders are specified in the same -P option, they
256 will be stacked on top of each other in the specified order.
257 Example:
259 $ sigrok-cli -i <file.sr> -P i2c,eeprom24xx
261 $ sigrok-cli -i <file.sr> -P uart:baudrate=31250,midi
262 When multiple -P options are specified, each of them creates one
264 decoder stack, which executes in parallel to other decoder
265 stacks.
266 Example:
268 $ sigrok-cli -i <file.sr> -P uart:tx=D0:rx=D1 -P timing:data=D2
270 -A, --protocol-decoder-annotations <annotations>
273 By default, only the stack's topmost protocol decoder's annota‐
274 tion output is shown. With this option another decoder's annota‐
275 tion can be selected for display, by specifying its ID:
276 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid -A i2c
278 If a protocol decoder has multiple annotations, you can also
280 specify which one of them to show by specifying its short
281 description like this:
282 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
284 -A i2c=data-read
285 Select multiple annotations by separating them with a colon:
287 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
289 -A i2c=data-read:data-write
290 You can also select multiple protocol decoders, with an optional
292 selected annotation each, by separating them with commas:
293 $ sigrok-cli -i <file.sr> -P i2c,i2cfilter,edid
295 -A i2c=data-read:data-write,edid
296 -M, --protocol-decoder-meta <pdname>
298 When given, show protocol decoder meta output instead of annota‐
299 tions. The argument is the name of the decoder whose meta out‐
300 put to show.
301 $ sigrok-cli -i <file.sr> -M i2c
303 Not every decoder generates meta output.
305 -B, --protocol-decoder-binary <binaryspec>
307 When given, decoder "raw" data of various kinds is written to
308 stdout instead of annotations (this could be raw binary UART/SPI
309 bytes, or WAV files, PCAP files, PNG files, or anything else;
310 this is entirely dependent on the decoder and what kinds of
311 binary output make sense for that decoder).
312 No other information is printed to stdout, so this is suitable
314 for piping into other programs or saving to a file.
315 Protocol decoders that support binary output publish a list of
317 binary classes, for example the UART decoder might have "TX" and
318 "RX". To select TX for output, the argument to this option would
319 be:
320 $ sigrok-cli -i <file.sr> -B uart=tx
322 If only the protocol decoder is specified, without binary class,
324 all classes are written to stdout:
325 $ sigrok-cli -i <file.sr> -B uart
327 (this is only useful in rare cases, generally you would specify
329 a certain binary class you're interested in)
330 Not every decoder generates binary output.
332 --protocol-decoder-samplenum
334 When given, decoder annotations will include sample numbers,
335 too. This allows consumers to receive machine readable timing
336 information.
337 -l, --loglevel <level>
339 Set the libsigrok and libsigrokdecode loglevel. At the moment
340 sigrok-cli doesn't support setting the two loglevels indepen‐
341 dently. The higher the number, the more debug output will be
342 printed. Valid loglevels are:
343 0 None
345 1 Error
346 2 Warnings
347 3 Informational
348 4 Debug
349 5 Spew
350 --show
352 Show information about the selected option. For example, to see
353 options for a connected fx2lafw device:
354 $ sigrok-cli --driver fx2lafw --show
356 In order to properly get device options for your hardware, some
358 drivers might need a serial port specified:
359 $ sigrok-cli --driver ols:conn=/dev/ttyACM0 --show
361 This also works for protocol decoders, input modules and output
363 modules:
364 $ sigrok-cli --protocol-decoders i2c --show
366 $ sigrok-cli --input-format csv --show
367 $ sigrok-cli --output-format bits --show
368 --scan Scan for devices that can be detected automatically.
370 Example:
372 $ sigrok-cli --scan
374 The following devices were found:
375 demo - Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0
376 A1 A2 A3
377 fx2lafw:conn=3.26 - CWAV USBee SX with 8 channels: 0 1 2 3 4 5
378 6 7
379 However, not all devices are auto-detectable (e.g. serial port
381 based ones). For those you'll have to provide a conn option,
382 see above.
383 $ sigrok-cli --driver digitek-dt4000zc:conn=/dev/ttyUSB0 --scan
385 The following devices were found:
386 Digitek DT4000ZC with 1 channel: P1
387 --time <ms>
389 Sample for <ms> milliseconds, then quit.
390 You can optionally follow the number by s to specify the time to
392 sample in seconds.
393 For example, --time 2s will sample for two seconds.
395 --samples <numsamples>
397 Acquire <numsamples> samples, then quit.
398 You can optionally follow the number by k, m, or g to specify
400 the number of samples in kilosamples, megasamples, or gigasam‐
401 ples, respectively.
402 For example, --samples 3m will acquire 3000000 samples.
404 --frames <numframes>
406 Acquire <numframes> frames, then quit.
407 --continuous
409 Sample continuously until stopped. Not all devices support this.
410 --get <variable>
412 Get the value of <variable> from the specified device and print
413 it.
414 --set Set one or more variables specified with the --config option,
416 without doing any acquisition.
417
419 In order to get exactly 100 samples from the connected fx2lafw-sup‐
420 ported logic analyzer hardware, run the following command:
421 sigrok-cli --driver fx2lafw --samples 100
423 If you want to sample data for 3 seconds (3000 ms), use:
425 sigrok-cli --driver fx2lafw --time 3000
427 Alternatively, you can also use:
429 sigrok-cli --driver fx2lafw --time 3s
431 To capture data from the first 4 channels using the Openbench Logic
433 Sniffer lasting 100ms at 10 MHz starting at the trigger condition
434 0:high, 1:rising, 2:low, 3:high, use:
435 sigrok-cli --driver ols:conn=/dev/ttyACM0 --config samplerate=10m \
437 --output-format bits --channels 0-3 --wait-trigger \
438 --triggers 0=1,1=r,2=0,3=1 --time 100
439 To turn on internal logging on a Lascar EL-USB series device:
441 sigrok-cli --driver lascar-el-usb:conn=10c4.0002 \
443 --config datalog=on --set
444
446 sigrok-cli exits with 0 on success, 1 on most failures.
447
449 pulseview(1)
450
452 Please report any bugs via Bugzilla (http://sigrok.org/bugzilla) or on
453 the sigrok-devel mailing list (sigrok-devel@lists.souceforge.net).
454
456 sigrok-cli is covered by the GNU General Public License (GPL). Some
457 portions are licensed under the "GPL v2 or later", some under "GPL v3
458 or later".
459
461 Please see the individual source code files.
462 This manual page was written by Uwe Hermann <uwe@hermann-uwe.de>. It
464 is licensed under the terms of the GNU GPL (version 2 or later).
465 October 22, 2018 SIGROK-CLI(1)