Gordons Projects

--> Projects Top-Level GIT

Updating for various stuff and bugs. CM3+ and PiA3+
[wiringPi] / gpio / gpio.1
index 7da64b2..a71aaae 100644 (file)
@@ -1,31 +1,81 @@
-.TH "GPIO" "14 June 2012" "Command-Line access to Raspberry Pi and PiFace GPIO"
+.TH GPIO 1 "March 2018" 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
-.TP
 .B gpio
-.RB [ \-v ]
-.TP
+.B \-v
+.PP
 .B gpio
-.RB [ \-g ]
-.RB < read/write/pwm/mode ...>
-.TP
+.B [ \-g | \-1 ]
+.B mode/read/write/aread/awrite/wb/pwm/pwnTone/clock/toggle/blink ...
+.PP
 .B gpio
-.RB [ \-p ]
-.RB < read/write/mode ...>
-.TP
+.B [ \-x extension:params ]
+.B mode/read/write/aread/awrite/pwm/toggle/blink ...
+.PP
+.B gpio
+.B [ \-p ]
+.B read/write/toggle/blink
+.B ...
+.PP
+.B gpio
+.B [ \-p ]
+.B pwnTone pin frequency
+.B ...
+.PP
+.B gpio
+.B readall
+.PP
+.B gpio
+.B unexportall/exports
+.PP
+.B gpio
+.B export/edge/unexport
+.B ...
+.PP
+.B gpio
+.B wfi
+.B ...
+.PP
+.B gpio
+.B drive
+group value
+.PP
+.B gpio
+.B usbp
+high | low
+.PP
 .B gpio
-.RB < export/edge/unexport/unexportall/exports ...>
+.B pwm-bal/pwm-ms
+.PP
+.B gpio
+.B pwmr
+range
+.PP
+.B gpio
+.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
@@ -35,41 +85,128 @@ 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 <pin>
 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 <pin> <value>
+Write the given value (0 or 1) to the pin. You need to set the pin
+to output mode first.
+
+.TP
+.B toggle <pin> 
+Changes the state of a GPIO pin; 0 to 1, or 1 to 0.
+
+Note unlike the blink command, the pin must be in output mode first.
 
 .TP
-.B pwm
-Write a PWM value (0-1023) to the given pin.
+.B blink <pin> 
+Blinks the given pin on/off. Press Control-C to exit.
+
+Note: This command explicitly sets the pin to output mode.
 
 .TP
-.B mode
+.B aread <pin>
+Read the analog value of the given pin. This needs to be used in
+conjunction with a -x flag to add in an extension that handles analog
+inputs.
+
+e.g. gpio -x mcp3002:200:0 aread 200
+
+will read the first analog input on an mcp3002 SPI ADC chip.
+
+.TP
+.B awrite <pin> <value>
+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. 
+
+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 wb <value>
+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 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 <pin> <value>
+Write a PWM value (0-1023) to the given pin. The pin needs to be put
+into PWM mode first.
+
+.TP
+.B clock <pin> <frequency>
+Set the output frequency on the given pin. The pin needs to be put into
+clock mode first.
+
+.TP
+.B mode <pin> <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.
+
+.TP
+.B exports
+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
@@ -87,7 +224,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.
 
@@ -96,38 +233,56 @@ requiring root/sudo.
 Un-Export a GPIO pin in the /sys/class/gpio directory.
 
 .TP
-.B unexportall
-Un-Export all the GPIO pins in the /sys/class/gpio directory.
+.B wfi <pin> <mode>
+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 exports
-Print a list (if any) of all the exported GPIO pins and their current values.
+.B drive
+group value
+
+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+ and the Model B, v2.
+
+.TP
+.B pwm-bal/pwm-ms 
+Change the PWM mode to balanced (the default) or mark:space ratio (traditional)
+
+.TP
+.B pwmr
+Change the PWM range register. The default is 1024.
+
+.TP
+.B gbr
+channel
 
-.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
+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
 
@@ -157,12 +312,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
 
@@ -170,10 +337,15 @@ Gordon Henderson
 
 .SH "REPORTING BUGS"
 
-Report bugs to <gordon@drogon.net>
+Please report bugs to <projects@drogon.net>
 
 .SH COPYRIGHT
 
-Copyright (c) 2012 Gordon Henderson
+Copyright (c) 2012-2018 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.