]>
Commit | Line | Data |
---|---|---|
1a0be0e3 | 1 | .TH SIGROK\-CLI 1 "May 29, 2012" |
43e5747a | 2 | .SH "NAME" |
53155b2f | 3 | sigrok\-cli \- Command-line client for the sigrok software |
43e5747a | 4 | .SH "SYNOPSIS" |
53155b2f | 5 | .B sigrok\-cli [OPTIONS] [COMMAND] |
43e5747a | 6 | .SH "DESCRIPTION" |
53155b2f | 7 | \fBsigrok\-cli\fP is a cross-platform command line utility for the \fBsigrok\fP software. |
43e5747a UH |
8 | .PP |
9 | The command-line frontend for sigrok cannot display graphical output, but is | |
10 | still sufficient to run through the whole process of hardware initialization, | |
85f2ddbb | 11 | acquisition, protocol decoding and saving the session. |
43e5747a UH |
12 | .PP |
13 | It is useful for running on remote or embedded systems, netbooks, PDAs, | |
14 | and for various other use-cases. It can display samples on standard output or | |
15 | save them in various file formats. | |
53155b2f | 16 | .SH OPTIONS |
43e5747a | 17 | .TP |
43e5747a UH |
18 | .B "\-h, \-\-help" |
19 | Show a help text and exit. | |
20 | .TP | |
7949dca0 UH |
21 | .B "\-V, \-\-version" |
22 | Show | |
23 | .B sigrok-cli | |
24 | version, and information about supported hardware drivers, input file | |
25 | formats, output file formats, and protocol decoders. | |
26 | .TP | |
53155b2f BV |
27 | \fB\-\-driver\fP <drivername> |
28 | A driver must always be selected. Use the \fB-V\fP option to get a list of available drivers. Drivers can take options, in the form \fBkey=value\fP separated by colons. | |
29 | .sp | |
30 | Drivers communicating with hardware via a serial port always need the port specified as the \fBconn\fP option. For example, to use the Openbench Logic Sniffer: | |
31 | .sp | |
32 | .RB " $ " "sigrok\-cli \-\-driver=ols:conn=/dev/ttyACM0" | |
33 | .sp | |
34 | Some USB devices don't use a unique VendorID/ProductID combination, and thus need that specified as well. This also uses the \fBconn\fP option, using either \fBVendorID.ProductID\fP or \fBbus.address\fP: | |
35 | .sp | |
36 | .RB " $ " "sigrok\-cli \-\-driver=nexus-osciprime:conn=04b4.8613" | |
43e5747a | 37 | .TP |
1b4b6a7c | 38 | .BR "\-d, \-\-device " <device> |
53155b2f | 39 | A colon-separated list of device options, where each option takes the form |
1b4b6a7c | 40 | .BR key=value . |
53155b2f BV |
41 | For example, to set the samplerate on a device supported by the fx2lafw |
42 | driver, you might specify | |
1b4b6a7c | 43 | .sp |
53155b2f | 44 | .RB " $ " "sigrok\-cli \-\-driver=fx2lafw \-\-device samplerate=1m" |
1b4b6a7c | 45 | .sp |
53155b2f BV |
46 | Samplerate is an option common to most logic analyzers. The argument specifies |
47 | the samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. | |
1b4b6a7c UH |
48 | The following are all equivalent: |
49 | .sp | |
53155b2f | 50 | .RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-device samplerate=1000000" |
1b4b6a7c | 51 | .sp |
53155b2f | 52 | .RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-device samplerate=1m" |
1b4b6a7c | 53 | .sp |
53155b2f | 54 | .RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-device \(dqsamplerate=1 MHz\(dq" |
1b4b6a7c | 55 | .TP |
43e5747a | 56 | .BR "\-i, \-\-input\-file " <filename> |
7949dca0 | 57 | Load input from a file instead of a hardware device. If the |
43e5747a UH |
58 | .B \-\-input\-format |
59 | option is not supplied, sigrok-cli attempts to autodetect the file format of | |
60 | the input file. | |
61 | .TP | |
62 | .BR "\-I, \-\-input\-format " <format> | |
63 | When loading an input file, assume it's in the specified format. If this | |
64 | option is not supplied (in addition to | |
65 | .BR \-\-input\-file ), | |
943d0c08 TŠ |
66 | sigrok-cli attempts to autodetect the file format of the input file. Use the |
67 | .B \-V | |
68 | option to see a list of available input formats. The format name may | |
69 | optionally be followed by a colon-separated list of options, where each | |
70 | option takes the form | |
71 | .BR "key=value" . | |
43e5747a UH |
72 | .TP |
73 | .BR "\-o, \-\-output\-file " <filename> | |
74 | Save output to a file instead of writing it to stdout. The default format | |
75 | used when saving is the sigrok session file format. This can be changed with | |
76 | the | |
76ae913d | 77 | .B \-\-output\-format |
7949dca0 UH |
78 | option. |
79 | .TP | |
80 | .BR "\-O, \-\-output\-format " <formatname> | |
81 | Set the output format to use. Use the | |
82 | .B \-V | |
83 | option to see a list of available output formats. The format name may | |
84 | optionally be followed by a colon-separated list of options, where each | |
85 | option takes the form | |
86 | .BR "key=value" . | |
87 | .sp | |
88 | Supported formats currently include | |
89 | .BR bits , | |
90 | .BR hex , | |
91 | .BR ascii , | |
92 | .BR binary , | |
93 | .BR vcd , | |
85f2ddbb UH |
94 | .BR ols , |
95 | .BR gnuplot , | |
96 | .BR chronovu-la8 ", and" | |
97 | .BR csv . | |
7949dca0 UH |
98 | .sp |
99 | The | |
100 | .B bits | |
101 | or | |
102 | .B hex | |
103 | 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 | |
104 | .B hex:width=128 | |
105 | will display 128 bits per line, in hexadecimal: | |
106 | .sp | |
107 | 1:ffff ffff ffff ffff ffff ffff ffff ffff | |
108 | 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 | |
109 | .sp | |
110 | The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to | |
111 | .BR bits:width=64 , | |
112 | like this: | |
113 | .sp | |
114 | 1:11111111 11111111 11111111 11111111 [...] | |
115 | 2:11111111 00000000 11111111 00000000 [...] | |
43e5747a | 116 | .TP |
43e5747a UH |
117 | .BR "\-p, \-\-probes " <probelist> |
118 | A comma-separated list of probes to be used in the session. | |
119 | .sp | |
53155b2f BV |
120 | Note that sigrok always names the probes according to how they're shown on the enclosure of the hardware. If your logic analyzer numbers the probes 0-15, that's how you must specify them with this option. An oscilloscope's probes would generally be referred to as "CH1", "CH2", and so on. Use the \fB\-\-show\fP option to see a list of probe names for your device. |
121 | .sp | |
43e5747a UH |
122 | The default is to use all the probes available on a device. You can name |
123 | a probe like this: | |
124 | .BR "1=CLK" . | |
125 | A range of probes can also be given, in the form | |
126 | .BR "1\-5" . | |
127 | .sp | |
128 | Example: | |
129 | .sp | |
130 | $ | |
53155b2f | 131 | .B "sigrok\-cli \-\-driver fx2lafw \-\-samples 100 \-\-probes 1=CLK,2\-4,7" |
43e5747a UH |
132 | .br |
133 | CLK:11111111 11111111 11111111 11111111 [...] | |
134 | 2:11111111 11111111 11111111 11111111 [...] | |
135 | 3:11111111 11111111 11111111 11111111 [...] | |
136 | 4:11111111 11111111 11111111 11111111 [...] | |
137 | 7:11111111 11111111 11111111 11111111 [...] | |
138 | .sp | |
139 | The comma-separated list is processed from left to right, i.e. items farther | |
140 | to the right override previous items. For example | |
141 | .B "1=CS,1=MISO" | |
142 | will set the name of probe 1 to | |
143 | .BR "MISO" . | |
144 | .sp | |
145 | Also, while | |
146 | .B "5=MOSI,6=MISO" | |
147 | will only select probes 5 and 6, and set their names to MISO and MOSI, the | |
148 | command line | |
149 | .B "5=MOSI,6=MISO,1\-8" | |
150 | will select probes 1\-8 (including 5 and 6, of course), but the names specified | |
151 | for probes 5 and 6 will be reset to the defaults by the | |
152 | .B "1\-8" | |
153 | probe selection. | |
154 | .TP | |
155 | .BR "\-t, \-\-triggers " <triggerlist> | |
156 | A comma-separated list of triggers to use, of the form | |
157 | .BR "<probe>=<trigger>" . | |
158 | You can use the name or number of the probe, and the trigger itself is a | |
159 | series of characters: | |
160 | .sp | |
161 | .BR "0 or 1" : | |
162 | A low or high value on the pin. | |
163 | .br | |
164 | .BR "r or f" : | |
165 | A rising or falling value on the pin. An | |
166 | .B r | |
167 | effectively corresponds to | |
168 | .BR 01 . | |
169 | .br | |
170 | .BR "c" : | |
85f2ddbb | 171 | Any kind of change on a pin (either a rising or a falling edge). |
43e5747a | 172 | .sp |
53155b2f | 173 | Not every device supports all of these trigger types. Use the \fB\-\-show\fP command to see which triggers your device supports. |
43e5747a UH |
174 | .TP |
175 | .BR "\-w, \-\-wait-trigger" | |
53155b2f | 176 | 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). |
43e5747a | 177 | .TP |
85f2ddbb UH |
178 | .BR "\-a, \-\-protocol\-decoders " <list> |
179 | This option allows the user to specify a comma-separated list of protocol | |
180 | decoders to be used in this session. The decoders are specified by their | |
181 | ID, as shown in the | |
182 | .B \-\-version | |
183 | output. | |
184 | .sp | |
185 | Example: | |
186 | .sp | |
187 | $ | |
188 | .B "sigrok\-cli \-i <file.sr> \-a i2c" | |
189 | .sp | |
190 | Each protocol decoder can optionally be followed by a colon-separated list | |
191 | of options, where each option takes the form | |
192 | .BR "key=value" . | |
193 | .sp | |
194 | Example: | |
195 | .sp | |
196 | $ | |
197 | .B "sigrok\-cli \-i <file.sr> \-a uart:baudrate=115200:parity=odd" | |
198 | .sp | |
199 | The list of supported options depends entirely on the protocol decoder. Every | |
200 | protocol decoder has different options it supports. | |
201 | .sp | |
202 | Any "options" specified for a protocol decoder which are not actually | |
203 | supported options, will be interpreted as being probe name/number assignments. | |
204 | .sp | |
205 | Example: | |
206 | .sp | |
207 | $ | |
208 | .B "sigrok\-cli \-i <file.sr>" | |
209 | .br | |
210 | .B " \-a spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0" | |
211 | .sp | |
212 | In this example, | |
213 | .B wordsize | |
214 | is an option supported by the | |
215 | .B spi | |
216 | protocol decoder. Additionally, the user tells sigrok to decode the SPI | |
217 | protocol using probe 1 as MISO signal for SPI, probe 5 as MOSI, probe 3 | |
218 | as SCK, and probe 0 as CS# signal. | |
219 | .TP | |
220 | .BR "\-s, \-\-protocol\-decoder\-stack " <stack> | |
221 | This option allows the user to specify a protocol decoder stack, i.e. | |
222 | the way in which one protocol decoder's output gets piped into another | |
7fb87027 | 223 | protocol decoder. If not specified, the stack will be set up in the same |
1a0be0e3 UH |
224 | order in which the protocol decoders were given with the |
225 | .B \-\-protocol-decoders | |
7fb87027 | 226 | option. |
85f2ddbb UH |
227 | .sp |
228 | The decoders are specified by their ID, as shown in the | |
229 | .B \-\-version | |
230 | output. In addition to the | |
231 | .B \-s | |
232 | option, all protocol decoders that are used in a stack, must also be specified | |
233 | (together with their options, if any) using the | |
234 | .B \-a | |
235 | parameter. | |
236 | .sp | |
237 | Example: | |
238 | .sp | |
239 | $ | |
2d4077a7 | 240 | .B "sigrok\-cli \-i <file.sr> \-a i2c:sda=4:scl=7,rtc8564" |
85f2ddbb UH |
241 | .br |
242 | .B " \-s i2c,rtc8564" | |
243 | .sp | |
244 | In this example, the | |
245 | .B \-s | |
246 | option specifies that the output of the | |
247 | .BR i2c " decoder" | |
248 | is piped into the | |
249 | .BR rtc8564 " decoder," | |
250 | i.e., the | |
251 | .BR rtc8564 " decoder" | |
252 | is stacked on top of the | |
253 | .BR i2c " decoder." | |
254 | .sp | |
255 | The respective protocol decoder options and probe name/number assignments | |
256 | must be given using the | |
257 | .B \-a | |
258 | option (you cannot specify them in the | |
259 | .B \-s | |
260 | option). | |
261 | .TP | |
b6bd032d | 262 | .BR "\-A, \-\-protocol\-decoder\-annotations " <annotations> |
7fb87027 BV |
263 | By default, only the stack's topmost protocol decoder's annotation output is |
264 | shown. With this option another decoder's annotation can be selected for | |
1a0be0e3 | 265 | display, by specifying its ID: |
7fb87027 BV |
266 | .sp |
267 | $ | |
b6bd032d | 268 | .B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid -A i2c" |
7fb87027 BV |
269 | .sp |
270 | If a protocol decoder has multiple annotation formats, you can also specify | |
271 | which of them to show by specifying its short description like this: | |
272 | .sp | |
273 | $ | |
274 | .B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid" | |
275 | .br | |
b6bd032d | 276 | .B " \-A i2c=rawhex" |
7fb87027 BV |
277 | .sp |
278 | You can also select multiple protocol decoders, with an optional selected | |
279 | annotation format each, by separating them with commas: | |
280 | .sp | |
281 | $ | |
282 | .B "sigrok\-cli \-i <file.sr> \-a i2c,i2cfilter,edid" | |
283 | .br | |
b6bd032d | 284 | .B " \-A i2c=rawhex,edid" |
7fb87027 | 285 | .TP |
53155b2f BV |
286 | .BR "\-l, \-\-loglevel " <level> |
287 | Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok-cli\fP doesn't support setting the two loglevels independently. The higher the | |
288 | number, the more debug output will be printed. Valid loglevels are: | |
289 | .sp | |
290 | \fB0\fP None | |
291 | .br | |
292 | \fB1\fP Error | |
293 | .br | |
294 | \fB2\fP Warnings | |
295 | .br | |
296 | \fB3\fP Informational | |
297 | .br | |
298 | \fB4\fP Debug | |
299 | .br | |
300 | \fB5\fP Spew | |
301 | .TP | |
302 | .B "\-\-show" | |
303 | .br | |
304 | Show information about the selected option. For example, to see options for a connected fx2lafw device: | |
305 | .sp | |
306 | $ | |
307 | .B "sigrok\-cli \-\-driver fx2lafw \-\-show | |
308 | .sp | |
309 | In order to properly get device options for your hardware, some drivers might need a serial port specified: | |
310 | .sp | |
311 | $ | |
312 | .B "sigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-show | |
313 | .sp | |
314 | To view the documentation for a protocol decoder: | |
315 | .sp | |
316 | $ | |
317 | .B "sigrok\-cli \-\-protocol-decoders i2c \-\-show | |
318 | .TP | |
319 | .B "\-D, \-\-list\-devices" | |
320 | List all devices found on the system. This actively scans for devices that can be detected automatically. | |
321 | .TP | |
43e5747a UH |
322 | .BR "\-\-time " <ms> |
323 | Sample for | |
324 | .B <ms> | |
325 | milliseconds, then quit. You can optionally follow the number by | |
326 | .B s | |
327 | to state the number of seconds to sample instead. For example, | |
328 | .B "\-\-time 2s" | |
329 | will sample for two seconds. | |
330 | .TP | |
331 | .BR "\-\-samples " <numsamples> | |
332 | Acquire | |
333 | .B <numsamples> | |
334 | samples, then quit. | |
335 | .TP | |
336 | .BR "\-\-continuous" | |
337 | Sample continuously until stopped. Not all devices support this. | |
53155b2f BV |
338 | .SH EXAMPLES |
339 | In order to get exactly 100 samples from the connected fx2lafw-supported logic analyzer hardware, run the following command: | |
43e5747a | 340 | .TP |
53155b2f | 341 | .B " sigrok\-cli \-\-driver fx2lafw \-\-samples 100" |
43e5747a UH |
342 | .TP |
343 | If you want to sample data for 3 seconds, use: | |
344 | .TP | |
53155b2f | 345 | .B " sigrok\-cli \-\-driver fx2lafw \-\-time 3000" |
43e5747a UH |
346 | .TP |
347 | Alternatively, you can also use: | |
348 | .TP | |
53155b2f | 349 | .B " sigrok\-cli \-\-driver fx2lafw \-\-time 3s" |
43e5747a | 350 | .TP |
53155b2f BV |
351 | To capture data from the first 4 probes using the Openbench Logic Sniffer lasting 100ms at 10 MHz starting at the trigger condition |
352 | 0:high, 1:rising, 2:low, 3:high, use: | |
43e5747a | 353 | .TP |
53155b2f BV |
354 | .nf |
355 | \fBsigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-device samplerate=10m \\ | |
356 | \fB\-\-output\-format bits \-\-probes 0\-3 \-\-time 100 \\ | |
357 | \fB\-\-wait\-trigger \-\-triggers 0=1,1=r,2=0,3=1 | |
358 | .fi | |
43e5747a UH |
359 | .SH "EXIT STATUS" |
360 | .B sigrok\-cli | |
361 | exits with 0 on success, 1 on most failures. | |
362 | .SH "SEE ALSO" | |
4611cadf UH |
363 | \fBsigrok\-qt\fP(1), |
364 | \fBsigrok\-gtk\fP(1) | |
43e5747a UH |
365 | .SH "BUGS" |
366 | Please report any bugs on the sigrok\-devel mailing list | |
367 | .RB "(" sigrok\-devel@lists.souceforge.net ")." | |
368 | .SH "LICENSE" | |
369 | .B sigrok\-cli | |
370 | is covered by the GNU General Public License (GPL). Some portions are | |
371 | licensed under the "GPL v2 or later", some under "GPL v3 or later". | |
372 | .SH "AUTHORS" | |
373 | Please see the individual source code files. | |
374 | .PP | |
375 | This manual page was written by Uwe Hermann <uwe@hermann\-uwe.de>. | |
376 | It is licensed under the terms of the GNU GPL (version 2 or later). |