gpio/gpio.1

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