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