]>
Commit | Line | Data |
---|---|---|
7949dca0 | 1 | .TH SIGROK\-CLI 1 "March 18, 2012" |
43e5747a UH |
2 | .SH "NAME" |
3 | sigrok\-cli \- Command-line client for the sigrok logic analyzer software | |
4 | .SH "SYNOPSIS" | |
7949dca0 | 5 | .B sigrok\-cli \fR[\fB\-hVDiIoOdptwa\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-triggers\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR sequence] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR] |
43e5747a UH |
6 | .SH "DESCRIPTION" |
7 | .B sigrok\-cli | |
8 | is a cross-platform command line utility for the | |
9 | .B sigrok | |
10 | logic analyzer software. | |
11 | .PP | |
12 | The command-line frontend for sigrok cannot display graphical output, but is | |
13 | still sufficient to run through the whole process of hardware initialization, | |
14 | acquisition, protocol analysis and saving the session. | |
15 | .PP | |
16 | It is useful for running on remote or embedded systems, netbooks, PDAs, | |
17 | and for various other use-cases. It can display samples on standard output or | |
18 | save them in various file formats. | |
19 | .SH "OPTIONS" | |
20 | .TP | |
43e5747a UH |
21 | .B "\-h, \-\-help" |
22 | Show a help text and exit. | |
23 | .TP | |
7949dca0 UH |
24 | .B "\-V, \-\-version" |
25 | Show | |
26 | .B sigrok-cli | |
27 | version, and information about supported hardware drivers, input file | |
28 | formats, output file formats, and protocol decoders. | |
29 | .TP | |
43e5747a | 30 | .B "\-D, \-\-list\-devices" |
7949dca0 UH |
31 | List all logic analyzer devices found on the system. This actively scans for |
32 | devices (USB, serial port, and others). | |
43e5747a UH |
33 | .TP |
34 | .BR "\-i, \-\-input\-file " <filename> | |
7949dca0 | 35 | Load input from a file instead of a hardware device. If the |
43e5747a UH |
36 | .B \-\-input\-format |
37 | option is not supplied, sigrok-cli attempts to autodetect the file format of | |
38 | the input file. | |
39 | .TP | |
40 | .BR "\-I, \-\-input\-format " <format> | |
41 | When loading an input file, assume it's in the specified format. If this | |
42 | option is not supplied (in addition to | |
43 | .BR \-\-input\-file ), | |
44 | sigrok-cli attempts to autodetect the file format of the input file. | |
45 | .TP | |
46 | .BR "\-o, \-\-output\-file " <filename> | |
47 | Save output to a file instead of writing it to stdout. The default format | |
48 | used when saving is the sigrok session file format. This can be changed with | |
49 | the | |
76ae913d | 50 | .B \-\-output\-format |
7949dca0 UH |
51 | option. |
52 | .TP | |
53 | .BR "\-O, \-\-output\-format " <formatname> | |
54 | Set the output format to use. Use the | |
55 | .B \-V | |
56 | option to see a list of available output formats. The format name may | |
57 | optionally be followed by a colon-separated list of options, where each | |
58 | option takes the form | |
59 | .BR "key=value" . | |
60 | .sp | |
61 | Supported formats currently include | |
62 | .BR bits , | |
63 | .BR hex , | |
64 | .BR ascii , | |
65 | .BR binary , | |
66 | .BR vcd , | |
67 | .BR ols ", and" | |
68 | .BR gnuplot . | |
69 | .sp | |
70 | The | |
71 | .B bits | |
72 | or | |
73 | .B hex | |
74 | 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 | |
75 | .B hex:width=128 | |
76 | will display 128 bits per line, in hexadecimal: | |
77 | .sp | |
78 | 1:ffff ffff ffff ffff ffff ffff ffff ffff | |
79 | 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 | |
80 | .sp | |
81 | The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to | |
82 | .BR bits:width=64 , | |
83 | like this: | |
84 | .sp | |
85 | 1:11111111 11111111 11111111 11111111 [...] | |
86 | 2:11111111 00000000 11111111 00000000 [...] | |
43e5747a UH |
87 | .TP |
88 | .BR "\-d, \-\-device " <device> | |
89 | The device to use for acquisition. It can be specified by ID as reported by | |
90 | .BR "\-\-list\-devices" , | |
91 | or by the name of the driver as reported by | |
92 | .BR \-\-version . | |
93 | .sp | |
94 | A device can optionally be followed by a colon-separated list of device | |
95 | options, where each option takes the form | |
96 | .BR key=value . | |
97 | For example, to set the samplerate on the first device you might specify | |
98 | .sp | |
99 | .RB " $ " "sigrok\-cli \-d 0:samplerate=1m" | |
100 | .sp | |
7949dca0 | 101 | Samplerate is an option common to most devices. The argument specifies the |
43e5747a UH |
102 | samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. |
103 | The following are all equivalent: | |
104 | .sp | |
105 | .RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000" | |
106 | .sp | |
107 | .RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m" | |
108 | .sp | |
109 | .RB " $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz"" | |
110 | .TP | |
111 | .BR "\-p, \-\-probes " <probelist> | |
112 | A comma-separated list of probes to be used in the session. | |
113 | .sp | |
114 | The default is to use all the probes available on a device. You can name | |
115 | a probe like this: | |
116 | .BR "1=CLK" . | |
117 | A range of probes can also be given, in the form | |
118 | .BR "1\-5" . | |
119 | .sp | |
120 | Example: | |
121 | .sp | |
122 | $ | |
123 | .B "sigrok\-cli \-\-samples 100 \-\-probes 1=CLK,2\-4,7" | |
124 | .br | |
125 | CLK:11111111 11111111 11111111 11111111 [...] | |
126 | 2:11111111 11111111 11111111 11111111 [...] | |
127 | 3:11111111 11111111 11111111 11111111 [...] | |
128 | 4:11111111 11111111 11111111 11111111 [...] | |
129 | 7:11111111 11111111 11111111 11111111 [...] | |
130 | .sp | |
131 | The comma-separated list is processed from left to right, i.e. items farther | |
132 | to the right override previous items. For example | |
133 | .B "1=CS,1=MISO" | |
134 | will set the name of probe 1 to | |
135 | .BR "MISO" . | |
136 | .sp | |
137 | Also, while | |
138 | .B "5=MOSI,6=MISO" | |
139 | will only select probes 5 and 6, and set their names to MISO and MOSI, the | |
140 | command line | |
141 | .B "5=MOSI,6=MISO,1\-8" | |
142 | will select probes 1\-8 (including 5 and 6, of course), but the names specified | |
143 | for probes 5 and 6 will be reset to the defaults by the | |
144 | .B "1\-8" | |
145 | probe selection. | |
146 | .TP | |
147 | .BR "\-t, \-\-triggers " <triggerlist> | |
148 | A comma-separated list of triggers to use, of the form | |
149 | .BR "<probe>=<trigger>" . | |
150 | You can use the name or number of the probe, and the trigger itself is a | |
151 | series of characters: | |
152 | .sp | |
153 | .BR "0 or 1" : | |
154 | A low or high value on the pin. | |
155 | .br | |
156 | .BR "r or f" : | |
157 | A rising or falling value on the pin. An | |
158 | .B r | |
159 | effectively corresponds to | |
160 | .BR 01 . | |
161 | .br | |
162 | .BR "c" : | |
163 | Any kind of change on a pin. | |
164 | .sp | |
165 | Not every device supports all of these trigger types. Use the | |
166 | .B "\-d <device>" | |
167 | argument (with no other arguments) to see which triggers your device supports. | |
168 | .TP | |
169 | .BR "\-w, \-\-wait-trigger" | |
170 | Don't output any sample data (even if it's actually received from the logic | |
171 | analyzer) before the trigger condition is met. In other words, do not output | |
172 | any pre-trigger data. This option is useful if you don't care about the data | |
173 | that came before the trigger (but the logic analyzer hardware delivers this | |
174 | data to sigrok nonetheless). | |
175 | .TP | |
43e5747a UH |
176 | .BR "\-\-time " <ms> |
177 | Sample for | |
178 | .B <ms> | |
179 | milliseconds, then quit. You can optionally follow the number by | |
180 | .B s | |
181 | to state the number of seconds to sample instead. For example, | |
182 | .B "\-\-time 2s" | |
183 | will sample for two seconds. | |
184 | .TP | |
185 | .BR "\-\-samples " <numsamples> | |
186 | Acquire | |
187 | .B <numsamples> | |
188 | samples, then quit. | |
189 | .TP | |
190 | .BR "\-\-continuous" | |
191 | Sample continuously until stopped. Not all devices support this. | |
192 | .SH "EXAMPLES" | |
193 | In order to get exactly 100 samples from the (only) detected logic analyzer | |
194 | hardware, run the following command: | |
195 | .TP | |
196 | .B " sigrok\-cli \-\-samples 100" | |
197 | .TP | |
198 | If you want to sample data for 3 seconds, use: | |
199 | .TP | |
200 | .B " sigrok\-cli \-\-time 3000" | |
201 | .TP | |
202 | Alternatively, you can also use: | |
203 | .TP | |
204 | .B " sigrok\-cli \-\-time 3s" | |
205 | .TP | |
206 | To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use: | |
207 | .TP | |
7949dca0 | 208 | .B " sigrok\-cli \-O bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\" |
43e5747a UH |
209 | .B " \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 " |
210 | .SH "EXIT STATUS" | |
211 | .B sigrok\-cli | |
212 | exits with 0 on success, 1 on most failures. | |
213 | .SH "SEE ALSO" | |
4611cadf UH |
214 | \fBsigrok\-qt\fP(1), |
215 | \fBsigrok\-gtk\fP(1) | |
43e5747a UH |
216 | .SH "BUGS" |
217 | Please report any bugs on the sigrok\-devel mailing list | |
218 | .RB "(" sigrok\-devel@lists.souceforge.net ")." | |
219 | .SH "LICENSE" | |
220 | .B sigrok\-cli | |
221 | is covered by the GNU General Public License (GPL). Some portions are | |
222 | licensed under the "GPL v2 or later", some under "GPL v3 or later". | |
223 | .SH "AUTHORS" | |
224 | Please see the individual source code files. | |
225 | .PP | |
226 | This manual page was written by Uwe Hermann <uwe@hermann\-uwe.de>. | |
227 | It is licensed under the terms of the GNU GPL (version 2 or later). |