gpio/gpio.1

   1 .TH "GPIO" "21st October 2012" "Command-Line access to Raspberry Pi and PiFace GPIO"
   2
   3 .SH NAME
   4 gpio \- Command-line access to Raspberry Pi and PiFace GPIO
   5
   6 .SH SYNOPSIS
   7 .B gpio
   8 .B \-v
   9 .PP
  10 .B gpio
  11 .B [ \-g ]
  12 .B read/write/wb/pwm/mode ...
  13 .PP
  14 .B gpio
  15 .B [ \-p ]
  16 .B read/write/wb
  17 .B ...
  18 .PP
  19 .B gpio
  20 .B readall
  21 .PP
  22 .B gpio
  23 .B unexportall/exports
  24 .PP
  25 .B gpio
  26 .B export/edge/unexport
  27 .B ...
  28 .PP
  29 .B gpio
  30 .B drive
  31 group value
  32 .PP
  33 .B gpio
  34 .B pwm-bal/pwm-ms
  35 .PP
  36 .B gpio
  37 .B pwmr
  38 range
  39 .PP
  40 .B gpio
  41 .B load \ i2c/spi
  42 .PP
  43 .B gpio
  44 .B gbr
  45 channel
  46 .PP
  47 .B gpio
  48 .B gbw
  49 channel value
  50
  51 .SH DESCRIPTION
  52
  53 .B GPIO
  54 is a swiss army knife of a command line tool to allow the user easy
  55 access to the GPIO pins on the Raspberry Pi and the SPI A/D and D/A
  56 converters on the Gertboard. It's designed for simple testing and
  57 diagnostic purposes, but can be used in shell scripts for general if
  58 somewhat slow control of the GPIO pins.
  59
  60 Additionally, it can be used to set the exports in the \fI/sys/class/gpio\fR
  61 system directory to allow subsequent programs to use the \fR/sys/class/gpio\fR
  62 interface without needing to be run as root.
  63
  64 .SH OPTIONS
  65
  66 .TP
  67 .B \-v
  68 Output the current version including the board revision of the Raspberry Pi.
  69
  70 .TP
  71 .B \-g
  72 Use the BCM_GPIO pins numbers rather than wiringPi pin numbers.
  73
  74 .TP
  75 .B \-p
  76 Use the PiFace interface board and its corresponding pin numbers.
  77
  78 .TP
  79 .B read <pin>
  80 Read the digital value of the given pin and print 0 or 1 to represent the
  81 respective logic levels.
  82
  83 .TP
  84 .B write <pin> <value>
  85 Write the given value (0 or 1) to the pin. You need to set the pin
  86 to output mode first.
  87
  88 .TP
  89 .B wb <value>
  90 Write the given byte to the 8 main GPIO pins. You can prefix it with 0x
  91 to specify a hexadecimal number. You need to set pins to output mode
  92 first.
  93
  94 .TP
  95 .B readall
  96 Output a table of all GPIO pins values. The values represent the actual values read
  97 if the pin is in input mode, or the last value written if the pin is in output
  98 mode.
  99
 100 .TP
 101 .B pwm <pin> <value>
 102 Write a PWM value (0-1023) to the given pin.
 103
 104 .TP
 105 .B mode <pin> <mode>
 106 Set a pin into \fIinput\fR, \fIoutput\fR or \fIpwm\fR mode. Can also
 107 use the literals \fIup\fR, \fIdown\fR or \fItri\fR to set the internal
 108 pull-up, pull-down or tristate (off) controls.
 109
 110 .TP
 111 .B unexportall
 112 Un-Export all the GPIO pins in the /sys/class/gpio directory.
 113
 114 .TP
 115 .B exports
 116 Print a list (if any) of all the exported GPIO pins and their current values.
 117
 118 .TP
 119 .B export
 120 Export a GPIO pin in the \fI/sys/class/gpio\fR directory. Use like the
 121 mode command above however only \fIin\fR and \fIout\fR are supported at
 122 this time. Note that the pin number is the \fBBCM_GPIO\fR number and
 123 not the wiringPi number.
 124
 125 Once a GPIO pin has been exported, the \fBgpio\fR program changes the
 126 ownership of the \fI/sys/class/gpio/gpioX/value\fR and if present in
 127 later kernels, the \fI/sys/class/gpio/gpioX/edge\fR pseudo files to
 128 that of the user running the \fBgpio\fR program. This means that you
 129 can have a small script of gpio exports to setup the gpio pins as your
 130 program requires without the need to run anything as root, or with the
 131 sudo command.
 132
 133 .TP
 134 .B edge
 135 This exports a GPIO pin in the \fI/sys/class/gpio\fR directory, set
 136 the direction to input and set the edge interrupt method to \fInone\fR,
 137 \fIrising\fR, \fIfalling\fR or \fIboth\fR.  Use like the export command
 138 above and note that \fBBCM_GPIO\fR pin number is used not not wiringPi pin
 139 numbering.
 140
 141 Like the export commands above, ownership is set to that of the
 142 calling user, allowing subsequent access from user programs without
 143 requiring root/sudo.
 144
 145 .TP
 146 .B unexport
 147 Un-Export a GPIO pin in the /sys/class/gpio directory.
 148
 149 .TP
 150 .B drive
 151 group value
 152
 153 Change the pad driver value for the given pad group to the supplied drive
 154 value. Group is 0, 1 or 2 and value is 0-7. Do not use unless you are
 155 absolutely sure you know what you're doing.
 156
 157 .TP
 158 .B pwm-bal/pwm-ms
 159 Change the PWM mode to balanced (the default) or mark:space ratio (traditional)
 160
 161 .TP
 162 .B pwmr
 163 Change the PWM range register. The default is 1024.
 164
 165 .TP
 166 .B load i2c/spi
 167 This loads the i2c or the spi drivers into the system and changes the permissions on
 168 the associated /dev/ entries so that the current user has access to them.
 169
 170 .TP
 171 .B gbr
 172 channel
 173
 174 This reads the analog to digital converter on the Gertboard on the given
 175 channel. The board jumpers need to be in-place to do this operation.
 176
 177 .TP
 178 .B gbw
 179 channel value
 180
 181 This writes the supplied value to the output channel on the Gertboards
 182 SPI digital to analogue converter.
 183 The board jumpers need to be in-place to do this operation.
 184
 185
 186 .SH "WiringPi vs. GPIO Pin numbering"
 187
 188 .PP
 189 .TS
 190 r r r l.
 191 WiringPi        GPIO-r1 GPIO-r2 Function
 192 _
 193 0       17      17
 194 1       18      18      (PWM)
 195 2       21      27
 196 3       22      22
 197 4       23      23
 198 5       24      24
 199 6       25      25
 200 7       4       4
 201 8       0       2       I2C: SDA0
 202 9       1       3       I2C: SCL0
 203 10      8       8       SPI: CE0
 204 11      7       7       SPI: CE1
 205 12      10      10      SPI: MOSI
 206 13      9       9       SPI: MISO
 207 14      11      11      SPI: SCLK
 208 15      14      14      TxD
 209 16      15      16      RxD
 210 17      -       28
 211 18      -       29
 212 19      -       30
 213 20      -       31
 214 .TE
 215
 216 .SH FILES
 217
 218 .TP 2.2i
 219 .I gpio
 220 executable
 221
 222 .SH EXAMPLES
 223 .TP 2.2i
 224 gpio mode 4 output # Set pin 4 to output
 225 .PP
 226 gpio -g mode 23 output # Set GPIO pin 23 to output (same as WiringPi pin 4)
 227 .PP
 228 gpio mode 1 pwm # Set pin 1 to PWM mode
 229 .PP
 230 gpio pwm 1 512 # Set pin 1 to PWM value 512 - half brightness
 231 .PP
 232 gpio export 17 out # Set GPIO Pin 17 to output
 233 .PP
 234 gpio export 0 in # Set GPIO Pin 0 (SDA0) to input.
 235 .PP
 236 gpio -g read 0 # Read GPIO Pin 0 (SDA0)
 237
 238 .SH "NOTES"
 239
 240 When using the \fIexport\fR, \fIedge\fR or \fIunexport\fR commands, the
 241 pin numbers are \fBalways\fR native BCM_GPIO numbers and never wiringPi
 242 pin numbers.
 243
 244 .SH "SEE ALSO"
 245
 246 .LP
 247 WiringPi's home page
 248 .IP
 249 https://projects.drogon.net/raspberry-pi/wiringpi/
 250
 251 .SH AUTHOR
 252
 253 Gordon Henderson
 254
 255 .SH "REPORTING BUGS"
 256
 257 Please report bugs to <projects@drogon.net>
 258
 259 .SH COPYRIGHT
 260
 261 Copyright (c) 2012 Gordon Henderson
 262 This is free software; see the source for copying conditions. There is NO
 263 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 264
 265 .SH TRADEMARKS AND ACKNOWLEDGEMENTS
 266
 267 Raspberry Pi is a trademark of the Raspberry Pi Foundation.