Gordons Projects

--> Projects Top-Level GIT

update for the v3+
[wiringPi] / gpio / gpio.1
1 .TH GPIO 1 "March 2018" wiringPi "Command-Line access to Raspberry Pi's GPIO"
2
3 .SH NAME
4 gpio \- Command-line access to Raspberry Pi's GPIO
5
6 .SH SYNOPSIS
7 .B gpio
8 .B \-v
9 .PP
10 .B gpio
11 .B [ \-g | \-1 ]
12 .B mode/read/write/aread/awrite/wb/pwm/pwnTone/clock/toggle/blink ...
13 .PP
14 .B gpio
15 .B [ \-x extension:params ]
16 .B mode/read/write/aread/awrite/pwm/toggle/blink ...
17 .PP
18 .B gpio
19 .B [ \-p ]
20 .B read/write/toggle/blink
21 .B ...
22 .PP
23 .B gpio
24 .B [ \-p ]
25 .B pwnTone pin frequency
26 .B ...
27 .PP
28 .B gpio
29 .B readall
30 .PP
31 .B gpio
32 .B unexportall/exports
33 .PP
34 .B gpio
35 .B export/edge/unexport
36 .B ...
37 .PP
38 .B gpio
39 .B wfi
40 .B ...
41 .PP
42 .B gpio
43 .B drive
44 group value
45 .PP
46 .B gpio
47 .B usbp
48 high | low
49 .PP
50 .B gpio
51 .B pwm-bal/pwm-ms
52 .PP
53 .B gpio
54 .B pwmr
55 range
56 .PP
57 .B gpio
58 .B load \ i2c/spi ...
59 .PP
60 .B gpio
61 .B gbr
62 channel
63 .PP
64 .B gpio
65 .B gbw
66 channel value
67
68 .SH DESCRIPTION
69
70 .B GPIO
71 is a swiss army knife of a command line tool to allow the user easy
72 access to the GPIO pins on the Raspberry Pi and the SPI A/D and D/A
73 converters on the Gertboard. It's designed for simple testing and
74 diagnostic purposes, but can be used in shell scripts for general if
75 somewhat slow control of the GPIO pins.
76
77 It can also control the IO's on the PiFace IO board and load the SPI and I2C
78 kernel modules if required.
79
80 Additionally, it can be used to set the exports in the \fI/sys/class/gpio\fR
81 system directory to allow subsequent programs to use the \fR/sys/class/gpio\fR
82 interface without needing to be run as root.
83
84 .SH OPTIONS
85
86 .TP
87 .B \-v
88 Output the current version including the board revision of the Raspberry Pi.
89
90 .TP
91 .B \-g
92 Use the BCM_GPIO pins numbers rather than wiringPi pin numbers.
93 \fINote:\fR The BCM_GPIO pin numbers are always used with the 
94 export and edge commands.
95
96 .TP
97 .B \-1
98 Use the physical pin numbers rather than wiringPi pin numbers.
99 \fINote:\fR that this applies to the P1 connector only. It is not possible to
100 use pins on the Revision 2 P5 connector this way, and as with \-g the
101 BCM_GPIO pin numbers are always used with the export and edge commands.
102
103 .TP
104 .B \-x extension
105 This causes the named extension to be initialised. Extensions
106 comprise of a name (e.g. mcp23017) followed by a colon, then the
107 pin-base, then more optional parameters depending on the extension type.
108 See the web page on http://wiringpi.com/the-gpio-utility/
109
110 .TP
111 .B \-p
112 Use the PiFace interface board and its corresponding pin numbers. The PiFace
113 will always appear at pin number 200 in the gpio command. You can assign any
114 pin numbers you like in your own programs though.
115
116 .TP
117 .B read <pin>
118 Read the digital value of the given pin and print 0 or 1 to represent the
119 respective logic levels.
120
121 .TP
122 .B write <pin> <value>
123 Write the given value (0 or 1) to the pin. You need to set the pin
124 to output mode first.
125
126 .TP
127 .B toggle <pin> 
128 Changes the state of a GPIO pin; 0 to 1, or 1 to 0.
129
130 Note unlike the blink command, the pin must be in output mode first.
131
132 .TP
133 .B blink <pin> 
134 Blinks the given pin on/off. Press Control-C to exit.
135
136 Note: This command explicitly sets the pin to output mode.
137
138 .TP
139 .B aread <pin>
140 Read the analog value of the given pin. This needs to be used in
141 conjunction with a -x flag to add in an extension that handles analog
142 inputs.
143
144 e.g. gpio -x mcp3002:200:0 aread 200
145
146 will read the first analog input on an mcp3002 SPI ADC chip.
147
148 .TP
149 .B awrite <pin> <value>
150 Write the analog value to the given pin. This needs to be used in
151 conjunction with a -x flag to add in an extension that handles analog
152 inputs. 
153
154 e.g. gpio -x mcp4802:200:0 awrite 200 128
155
156 will write the value 128 to the first DAC port on an mcp4802 chip on
157 the Pi's SPI bus 0.
158
159
160 .TP
161 .B wb <value>
162 Write the given byte to the 8 main GPIO pins. You can prefix it with 0x
163 to specify a hexadecimal number. You need to set pins to output mode
164 first.
165
166 .TP
167 .B readall
168 Output a table of all GPIO pins values. The values represent the actual values read
169 if the pin is in input mode, or the last value written if the pin is in output
170 mode.
171
172 The readall command is usable with an extension module (via the -x parameter),
173 but it's unable to determine pin modes or states, so will perform both a
174 digital and analog read on each pin in-turn.
175
176 .TP
177 .B pwm <pin> <value>
178 Write a PWM value (0-1023) to the given pin. The pin needs to be put
179 into PWM mode first.
180
181 .TP
182 .B clock <pin> <frequency>
183 Set the output frequency on the given pin. The pin needs to be put into
184 clock mode first.
185
186 .TP
187 .B mode <pin> <mode>
188 Set a pin into \fIinput\fR, \fIoutput\fR or \fIpwm\fR mode. Can also
189 use the literals \fIup\fR, \fIdown\fR or \fItri\fR to set the internal
190 pull-up, pull-down or tristate (off) controls.
191
192 The ALT modes can also be set using \fIalt0\fR, \fIalt1\fR,  ... \fIalt5\fR.
193
194 .TP
195 .B unexportall
196 Un-Export all the GPIO pins in the /sys/class/gpio directory.
197
198 .TP
199 .B exports
200 Print a list (if any) of all the exported GPIO pins and their current values.
201
202 .TP
203 .B export
204 Export a GPIO pin in the \fI/sys/class/gpio\fR directory. Use like the
205 mode command above however only \fIin\fR, \fIout\fR, \fIhigh\fR and
206 \fRlow\fR are supported at this time. Note that the pin number is the
207 \fBBCM_GPIO\fR number and not the wiringPi number. The \fIhigh\fR and
208 \fIlow\fR commands pre-set the output value at the same time as the
209 export to output mode.
210
211 Once a GPIO pin has been exported, the \fBgpio\fR program changes the
212 ownership of the \fI/sys/class/gpio/gpioX/value\fR and if present in
213 later kernels, the \fI/sys/class/gpio/gpioX/edge\fR pseudo files to
214 that of the user running the \fBgpio\fR program. This means that you
215 can have a small script of gpio exports to setup the gpio pins as your
216 program requires without the need to run anything as root, or with the
217 sudo command.
218
219 .TP
220 .B edge
221 This exports a GPIO pin in the \fI/sys/class/gpio\fR directory, set
222 the direction to input and set the edge interrupt method to \fInone\fR,
223 \fIrising\fR, \fIfalling\fR or \fIboth\fR.  Use like the export command
224 above and note that \fBBCM_GPIO\fR pin number is used not not wiringPi pin
225 numbering.
226
227 Like the export commands above, ownership is set to that of the 
228 calling user, allowing subsequent access from user programs without
229 requiring root/sudo.
230
231 .TP
232 .B unexport
233 Un-Export a GPIO pin in the /sys/class/gpio directory.
234
235 .TP
236 .B wfi <pin> <mode>
237 This set the given pin to the supplied interrupt mode: rising, falling
238 or both then waits for the interrupt to happen. It's a non-busy wait,
239 so does not consume and CPU while it's waiting.
240
241 .TP
242 .B drive
243 group value
244
245 Change the pad driver value for the given pad group to the supplied drive
246 value. Group is 0, 1 or 2 and value is 0-7. Do not use unless you are
247 absolutely sure you know what you're doing.
248
249 .TP
250 .B usbp
251 high | low
252
253 Change the USB current limiter to high (1.2 amps) or low (the default, 600mA)
254 This is only applicable to the Model B+ and the Model B, v2.
255
256 .TP
257 .B pwm-bal/pwm-ms 
258 Change the PWM mode to balanced (the default) or mark:space ratio (traditional)
259
260 .TP
261 .B pwmr
262 Change the PWM range register. The default is 1024.
263
264 .TP
265 .B gbr
266 channel
267
268 This reads the analog to digital converter on the Gertboard on the given
269 channel. The board jumpers need to be in-place to do this operation.
270
271 .TP
272 .B gbw
273 channel value
274
275 This writes the supplied value to the output channel on the Gertboards
276 SPI digital to analogue converter.
277 The board jumpers need to be in-place to do this operation.
278
279
280 .SH "WiringPi vs. BCM_GPIO Pin numbering vs. Physical pin numbering"
281
282 .PP
283 The quickest way to get a list of the pin differences is to run the command
284 .TP
285 gpio readall
286
287 .SH FILES
288
289 .TP 2.2i
290 .I gpio
291 executable
292
293 .SH EXAMPLES
294 .TP 2.2i
295 gpio mode 4 output # Set pin 4 to output
296 .PP
297 gpio -g mode 23 output # Set GPIO pin 23 to output (same as WiringPi pin 4)
298 .PP
299 gpio mode 1 pwm # Set pin 1 to PWM mode
300 .PP
301 gpio pwm 1 512 # Set pin 1 to PWM value 512 - half brightness
302 .PP
303 gpio export 17 out # Set GPIO Pin 17 to output
304 .PP
305 gpio export 0 in # Set GPIO Pin 0 (SDA0) to input.
306 .PP
307 gpio -g read 0 # Read GPIO Pin 0 (SDA0)
308
309 .SH "NOTES"
310
311 When using the \fIexport\fR, \fIedge\fR or \fIunexport\fR commands, the
312 pin numbers are \fBalways\fR native BCM_GPIO numbers and never wiringPi
313 pin numbers.
314
315 As of kernels 4.1.7, a user-level GPIO access mechanism is available,
316 however wiringPi will not use this by default - because at this time
317 there appears to be issues when trying to program the PWM or clock output
318 hardware. If you can live without PWM or GPIO clocks and you want to use
319 the GPIO from a non-root program, then you need to make sure that the 
320 module \fIbcm2835_gpiomem\fR is loaded at boot time. This should happen
321 automatically when you enable the device tree in raspi-config. You may
322 also need some additional information in /etc/udev/rules.d/ to change the
323 mode and ownership of the /dev/gpiomem file. Finally, you need to set
324 the environment variable \fIWIRINGPI_GPIOMEM\fR. This will go-away
325 in future releases once the /dev/gpiomem interface is fully operational.
326
327 .SH "SEE ALSO"
328
329 .LP
330 WiringPi's home page
331 .IP
332 http://wiringpi.com/
333
334 .SH AUTHOR
335
336 Gordon Henderson
337
338 .SH "REPORTING BUGS"
339
340 Please report bugs to <projects@drogon.net>
341
342 .SH COPYRIGHT
343
344 Copyright (c) 2012-2018 Gordon Henderson
345 This is free software; see the source for copying conditions. There is NO
346 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
347
348 .SH TRADEMARKS AND ACKNOWLEDGEMENTS
349
350 Raspberry Pi is a trademark of the Raspberry Pi Foundation. See
351 http://raspberrypi.org/ for full details.