X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=gpio%2Fgpio.1;h=e5fe181e7d94a2e2a1167d74c80fb4434ce1f3a6;hb=d79506694d7ba1c3da865d095238289d6175057d;hp=73e43c81bdc1d193eff7c4fadc4b402ba7347069;hpb=1bb4989e11145c3a369058850cea77cb9ca5c3ec;p=wiringPi.git diff --git a/gpio/gpio.1 b/gpio/gpio.1 index 73e43c8..e5fe181 100644 --- a/gpio/gpio.1 +++ b/gpio/gpio.1 @@ -1,22 +1,29 @@ -.TH "GPIO" "14 June 2012" "Command-Line access to Raspberry Pi and PiFace GPIO" +.TH GPIO 1 "September 2015" wiringPi "Command-Line access to Raspberry Pi's GPIO" .SH NAME -gpio \- Command-line access to Raspberry Pi and PiFace GPIO +gpio \- Command-line access to Raspberry Pi's GPIO .SH SYNOPSIS .B gpio .B \-v .PP .B gpio -.B [ \-g ] -.B read/write/pwm/mode ... +.B [ \-g | \-1 ] +.B mode/read/write/aread/awrite/wb/pwm/clock ... +.PP +.B gpio +.B [ \-x extension:params ] +.B mode/read/write/aread/awrite/pwm/pwmTone ... .PP .B gpio .B [ \-p ] -.B read/write/mode +.B read/write/toggle/wb .B ... .PP .B gpio +.B readall +.PP +.B gpio .B unexportall/exports .PP .B gpio @@ -24,10 +31,18 @@ gpio \- Command-line access to Raspberry Pi and PiFace GPIO .B ... .PP .B gpio +.B wfi +.B ... +.PP +.B gpio .B drive group value .PP .B gpio +.B usbp +high | low +.PP +.B gpio .B pwm-bal/pwm-ms .PP .B gpio @@ -35,15 +50,27 @@ group value range .PP .B gpio -.B load \ i2c/spi +.B load \ i2c/spi ... +.PP +.B gpio +.B gbr +channel +.PP +.B gpio +.B gbw +channel value .SH DESCRIPTION .B GPIO -is a command line tool to allow the user easy access to the GPIO pins -on the Raspberry Pi. It's designed for simple testing and diagnostic -purposes, but can be used in shell scripts for general if somewhat slow -control of the GPIO pins. +is a swiss army knife of a command line tool to allow the user easy +access to the GPIO pins on the Raspberry Pi and the SPI A/D and D/A +converters on the Gertboard. It's designed for simple testing and +diagnostic purposes, but can be used in shell scripts for general if +somewhat slow control of the GPIO pins. + +It can also control the IO's on the PiFace IO board and load the SPI and I2C +kernel modules if required. Additionally, it can be used to set the exports in the \fI/sys/class/gpio\fR system directory to allow subsequent programs to use the \fR/sys/class/gpio\fR @@ -53,35 +80,100 @@ interface without needing to be run as root. .TP .B \-v -Output the current version +Output the current version including the board revision of the Raspberry Pi. .TP .B \-g Use the BCM_GPIO pins numbers rather than wiringPi pin numbers. +\fINote:\fR The BCM_GPIO pin numbers are always used with the +export and edge commands. + +.TP +.B \-1 +Use the physical pin numbers rather than wiringPi pin numbers. +\fINote:\fR that this applies to the P1 connector only. It is not possible to +use pins on the Revision 2 P5 connector this way, and as with \-g the +BCM_GPIO pin numbers are always used with the export and edge commands. + +.TP +.B \-x extension +This causes the named extension to be initialised. Extensions +comprise of a name (e.g. mcp23017) followed by a colon, then the +pin-base, then more optional parameters depending on the extension type. +See the web page on http://wiringpi.com/the-gpio-utility/ .TP .B \-p -Use the PiFace interface board and its corresponding pin numbers. +Use the PiFace interface board and its corresponding pin numbers. The PiFace +will always appear at pin number 200 in the gpio command. You can assign any +pin numbers you like in your own programs though. .TP -.B read +.B read Read the digital value of the given pin and print 0 or 1 to represent the respective logic levels. .TP -.B write -Write the given value (0 or 1) to the pin. +.B write +Write the given value (0 or 1) to the pin. You need to set the pin +to output mode first. + +.TP +.B aread +Read the analog value of the given pin. This needs to be uses in +conjunction with a -x flag to add in an extension that handles analog +inputs. respective logic levels. + +e.g. gpio -x mcp3002:200:0 aread 200 + +will read the first analog input on an mcp3002 SPI ADC chip. + +.TP +.B awrite +Write the analog value to the given pin. This needs to be used in +conjunction with a -x flag to add in an extension that handles analog +inputs. respective logic levels. + +e.g. gpio -x mcp4802:200:0 awrite 200 128 + +will write the value 128 to the first DAC port on an mcp4802 chip on +the Pi's SPI bus 0. + .TP -.B pwm -Write a PWM value (0-1023) to the given pin. +.B wb +Write the given byte to the 8 main GPIO pins. You can prefix it with 0x +to specify a hexadecimal number. You need to set pins to output mode +first. .TP -.B mode +.B readall +Output a table of all GPIO pins values. The values represent the actual values read +if the pin is in input mode, or the last value written if the pin is in output +mode. + +The readall command is usable with an extension module (via the -x parameter), +but it's unable to determine pin modes or states, so will perform both a +digital and analog read on each pin in-turn. + +.TP +.B pwm +Write a PWM value (0-1023) to the given pin. The pin needs to be put +into PWM mode first. + +.TP +.B clock +Set the output frequency on the given pin. The pin needs to be put into +clock mode first. + +.TP +.B mode Set a pin into \fIinput\fR, \fIoutput\fR or \fIpwm\fR mode. Can also use the literals \fIup\fR, \fIdown\fR or \fItri\fR to set the internal pull-up, pull-down or tristate (off) controls. +The ALT modes can also be set using \fIalt0\fR, \fIalt1\fR, ... \fIalt5\fR. + .TP .B unexportall Un-Export all the GPIO pins in the /sys/class/gpio directory. @@ -93,9 +185,11 @@ Print a list (if any) of all the exported GPIO pins and their current values. .TP .B export Export a GPIO pin in the \fI/sys/class/gpio\fR directory. Use like the -mode command above however only \fIin\fR and \fIout\fR are supported at -this time. Note that the pin number is the \fBBCM_GPIO\fR number and -not the wiringPi number. +mode command above however only \fIin\fR, \fIout\fR, \fIhigh\fR and +\fRlow\fR are supported at this time. Note that the pin number is the +\fBBCM_GPIO\fR number and not the wiringPi number. The \fIhigh\fR and +\fIlow\fR commands pre-set the output value at the same time as the +export to output mode. Once a GPIO pin has been exported, the \fBgpio\fR program changes the ownership of the \fI/sys/class/gpio/gpioX/value\fR and if present in @@ -113,7 +207,7 @@ the direction to input and set the edge interrupt method to \fInone\fR, above and note that \fBBCM_GPIO\fR pin number is used not not wiringPi pin numbering. -Like the export commands abovem ownership is set to that of the +Like the export commands above, ownership is set to that of the calling user, allowing subsequent access from user programs without requiring root/sudo. @@ -121,6 +215,12 @@ requiring root/sudo. .B unexport Un-Export a GPIO pin in the /sys/class/gpio directory. +.TP +.B wfi +This set the given pin to the supplied interrupt mode: rising, falling +or both then waits for the interrupt to happen. It's a non-busy wait, +so does not consume and CPU while it's waiting. + .TP .B drive group value @@ -129,6 +229,13 @@ Change the pad driver value for the given pad group to the supplied drive value. Group is 0, 1 or 2 and value is 0-7. Do not use unless you are absolutely sure you know what you're doing. +.TP +.B usbp +high | low + +Change the USB current limiter to high (1.2 amps) or low (the default, 600mA) +This is only applicable to the model B+ + .TP .B pwm-bal/pwm-ms Change the PWM mode to balanced (the default) or mark:space ratio (traditional) @@ -138,36 +245,53 @@ Change the PWM mode to balanced (the default) or mark:space ratio (traditional) Change the PWM range register. The default is 1024. .TP -.B load i2c/spi -This loads the i2c or the spi drivers into the system and changes the permissions on -the associated /dev/ entries so that the current user has access to them. - - -.SH "WiringPi vs. GPIO Pin numbering" - -.PP -.TS -r r l. -WiringPi GPIO Function -_ -0 17 -1 18 (PWM) -2 21 -3 22 -4 23 -5 24 -6 25 -7 4 -8 0 SDA0 -9 1 SCL0 -10 8 SPI CE0 -11 7 SPI CE1 -12 10 SPI MOSI -13 9 SPI MISO -14 11 SPI SCLK -15 14 TxD -16 15 RxD -.TE +.B load i2c [baudrate] +This loads the i2c or drivers into the kernel and changes the permissions +on the associated /dev/ entries so that the current user has access to +them. Optionally it will set the I2C baudrate to that supplied in Kb/sec +(or as close as the Pi can manage) The default speed is 100Kb/sec. + +Note: On recent kernels with the device tree enabled you should use the +raspi-config program to load/unload the I2C device at boot time. +(or disable the device tree to continue to use this method) + +.TP +.B load spi +This loads the spi drivers into the kernel and changes the permissions +on the associated /dev/ entries so that the current user has access to +them. It used to have the ability to change the buffer size from the +default of 4096 bytes to an arbitrary value, however for some time the +Pi Foundation have compiled the SPI device driver into the kernel and +this has fixed the buffer size. The way to change it now is to edit +the /boot/cmdline.txt file and add on spdev.bufsiz=8192 to set it to +e.g. 8192 bytes then reboot. + +Note: On recent kernels with the device tree enabled you should use the +raspi-config program to load/unload the SPI device at boot time. +(or disable the device tree to continue to use this method) + +.TP +.B gbr +channel + +This reads the analog to digital converter on the Gertboard on the given +channel. The board jumpers need to be in-place to do this operation. + +.TP +.B gbw +channel value + +This writes the supplied value to the output channel on the Gertboards +SPI digital to analogue converter. +The board jumpers need to be in-place to do this operation. + + +.SH "WiringPi vs. BCM_GPIO Pin numbering vs. Physical pin numbering" + +.PP +The quickest way to get a list of the pin differences is to run the command +.TP +gpio readall .SH FILES @@ -197,12 +321,24 @@ When using the \fIexport\fR, \fIedge\fR or \fIunexport\fR commands, the pin numbers are \fBalways\fR native BCM_GPIO numbers and never wiringPi pin numbers. +As of kernels 4.1.7, a user-level GPIO access mechanism is available, +however wiringPi will not use this by default - because at this time +there appears to be issues when trying to program the PWM or clock output +hardware. If you can live without PWM or GPIO clocks and you want to use +the GPIO from a non-root program, then you need to make sure that the +module \fIbcm2835_gpiomem\fR is loaded at boot time. This should happen +automatically when you enable the device tree in raspi-config. You may +also need some additional information in /etc/udev/rules.d/ to change the +mode and ownership of the /dev/gpiomem file. Finally, you need to set +the environment variable \fIWIRINGPI_GPIOMEM\fR. This will go-away +in future releases once the /dev/gpiomem interface is fully operational. + .SH "SEE ALSO" .LP WiringPi's home page .IP -https://projects.drogon.net/raspberry-pi/wiringpi/ +http://wiringpi.com/ .SH AUTHOR @@ -210,10 +346,15 @@ Gordon Henderson .SH "REPORTING BUGS" -Report bugs to +Please report bugs to .SH COPYRIGHT -Copyright (c) 2012 Gordon Henderson +Copyright (c) 2012-2015 Gordon Henderson This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +.SH TRADEMARKS AND ACKNOWLEDGEMENTS + +Raspberry Pi is a trademark of the Raspberry Pi Foundation. See +http://raspberrypi.org/ for full details.