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):

  1. gpiozero.pins.rpigpio.RPiGPIOPin
  2. gpiozero.pins.rpio.RPIOPin
  3. gpiozero.pins.native.NativePin

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 to None 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 than None.

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 not None), 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

class gpiozero.pins.rpigpio.RPiGPIOPin[source]

Uses the RPi.GPIO library to interface to the Pi’s GPIO pins. This is the default pin implementation if the RPi.GPIO library is installed. Supports all features including PWM (via software).

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!