Pins¶
As of release 1.1, the GPIO Zero library can be roughly divided into two things: pins and the devices that are connected to them. The majority of the documentation focuses on devices as pins are below the level that most users are concerned with. However, some users may wish to take advantage of the capabilities of alternative GPIO implementations or (in future) use GPIO extender chips. This is the purpose of the pins portion of the library.
When you construct a device, you pass in a GPIO pin number. However, what the
library actually expects is a Pin
implementation. If it finds a simple
integer number instead, it uses one of the following classes to provide the
Pin
implementation (classes are listed in favoured order):
You can change the default pin implementation by over-writing the
DefaultPin
global in devices like so:
from gpiozero.pins.native import NativePin
import gpiozero.devices
# Force the default pin implementation to be NativePin
gpiozero.devices.DefaultPin = NativePin
from gpiozero import LED
# This will now use NativePin instead of RPiGPIOPin
led = LED(16)
In future, this separation should allow the library to utilize pins that are part of IO extender chips. For example:
from gpiozero import IOExtender, LED
ext = IOExtender()
led = LED(ext.pins[0])
led.on()
Warning
While the devices API is now considered stable and won’t change in backwards incompatible ways, the pins API is not yet considered stable. It is potentially subject to change in future versions. We welcome any comments from testers!
Abstract Pin¶
-
class
gpiozero.
Pin
[source]¶ Abstract base class representing a GPIO pin or a pin from an IO extender.
Descendents should override property getters and setters to accurately represent the capabilities of pins. The following functions must be overridden:
_get_function()
_get_state()
The following functions may be overridden if applicable:
close()
_set_function()
_set_state()
_get_frequency()
_set_frequency()
_get_pull()
_set_pull()
_get_bounce()
_set_bounce()
_get_edges()
_set_edges()
_get_when_changed()
_set_when_changed()
output_with_state()
input_with_pull()
Warning
Descendents must ensure that pin instances representing the same physical hardware are identical, right down to object identity. The framework relies on this to correctly clean up resources at interpreter shutdown.
-
close
()[source]¶ Cleans up the resources allocated to the pin. After this method is called, this
Pin
instance may no longer be used to query or control the pin’s state.
-
input_with_pull
(pull)[source]¶ Sets the pin’s function to “input” and specifies an initial pull-up for the pin. By default this is equivalent to performing:
pin.function = 'input' pin.pull = pull
However, descendents may override this order to provide the smallest possible delay between configuring the pin for input and pulling the pin up/down (which can be important for avoiding “blips” in some configurations).
-
output_with_state
(state)[source]¶ Sets the pin’s function to “output” and specifies an initial state for the pin. By default this is equivalent to performing:
pin.function = 'output' pin.state = state
However, descendents may override this in order to provide the smallest possible delay between configuring the pin for output and specifying an initial value (which can be important for avoiding “blips” in active-low configurations).
-
bounce
¶ The amount of bounce detection (elimination) currently in use by edge detection, measured in seconds. If bounce detection is not currently in use, this is
None
.If the pin does not support edge detection, attempts to set this property will raise
PinEdgeDetectUnsupported
. If the pin supports edge detection, the class must implement bounce detection, even if only in software.
-
edges
¶ The edge that will trigger execution of the function or bound method assigned to
when_changed
. This can be one of the strings “both” (the default), “rising”, “falling”, or “none”.If the pin does not support edge detection, attempts to set this property will raise
PinEdgeDetectUnsupported
.
-
frequency
¶ The frequency (in Hz) for the pin’s PWM implementation, or
None
if PWM is not currently in use. This value always defaults toNone
and may be changed with certain pin types to activate or deactivate PWM.If the pin does not support PWM,
PinPWMUnsupported
will be raised when attempting to set this to a value other thanNone
.
-
function
¶ The function of the pin. This property is a string indicating the current function or purpose of the pin. Typically this is the string “input” or “output”. However, in some circumstances it can be other strings indicating non-GPIO related functionality.
With certain pin types (e.g. GPIO pins), this attribute can be changed to configure the function of a pin. If an invalid function is specified, for this attribute,
PinInvalidFunction
will be raised. If this pin is fixed function and an attempt is made to set this attribute,PinFixedFunction
will be raised.
-
pull
¶ The pull-up state of the pin represented as a string. This is typically one of the strings “up”, “down”, or “floating” but additional values may be supported by the underlying hardware.
If the pin does not support changing pull-up state (for example because of a fixed pull-up resistor), attempts to set this property will raise
PinFixedPull
. If the specified value is not supported by the underlying hardware,PinInvalidPull
is raised.
-
state
¶ The state of the pin. This is 0 for low, and 1 for high. As a low level view of the pin, no swapping is performed in the case of pull ups (see
pull
for more information).If PWM is currently active (when
frequency
is notNone
), this represents the PWM duty cycle as a value between 0.0 and 1.0.If a pin is currently configured for input, and an attempt is made to set this attribute,
PinSetInput
will be raised. If an invalid value is specified for this attribute,PinInvalidState
will be raised.
-
when_changed
¶ A function or bound method to be called when the pin’s state changes (more specifically when the edge specified by
edges
is detected on the pin). The function or bound method must take no parameters.If the pin does not support edge detection, attempts to set this property will raise
PinEdgeDetectUnsupported
.
RPiGPIOPin¶
RPIOPin¶
-
class
gpiozero.pins.rpio.
RPIOPin
[source]¶ Uses the RPIO library to interface to the Pi’s GPIO pins. This is the default pin implementation if the RPi.GPIO library is not installed, but RPIO is. Supports all features including PWM (hardware via DMA).
Note
Please note that at the time of writing, RPIO is only compatible with Pi 1’s; the Raspberry Pi 2 Model B is not supported. Also note that root access is required so scripts must typically be run with
sudo
.
NativePin¶
-
class
gpiozero.pins.native.
NativePin
[source]¶ Uses a built-in pure Python implementation to interface to the Pi’s GPIO pins. This is the default pin implementation if no third-party libraries are discovered.
Warning
This implementation does not currently support PWM. Attempting to use any class which requests PWM will raise an exception. This implementation is also experimental; we make no guarantees it will not eat your Pi for breakfast!