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.pigpiod.PiGPIOPin
  4. gpiozero.pins.native.NativePin

You can change the default pin implementation by over-writing the DefaultPin global in the devices module 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)

Alternatively, instead of passing an integer to the device constructor, you can pass a Pin object itself:

from gpiozero.pins.native import NativePin
from gpiozero import LED

led = LED(NativePin(16))

This is particularly useful with implementations that can take extra parameters such as PiGPIOPin which can address pins on remote machines:

from gpiozero.pins.pigpiod import PiGPIOPin
from gpiozero import LED

led = LED(PiGPIOPin(16, host='my_other_pi'))

In future, this separation of pins and devices should also permit 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!

Warning

The astute and mischievous reader may note that it is possible to mix pin implementations, e.g. using RPiGPIOPin for one pin, and NativePin for another. This is unsupported, and if it results in your script crashing, your components failing, or your Raspberry Pi turning into an actual raspberry pie, you have only yourself to blame.

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

Because this is the default pin implementation you can use it simply by specifying an integer number for the pin in most operations, e.g.:

from gpiozero import LED

led = LED(12)

However, you can also construct RPi.GPIO pins manually if you wish:

from gpiozero.pins.rpigpio import RPiGPIOPin
from gpiozero import LED

led = LED(RPiGPIOPin(12))

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.

You can construct RPIO pins manually like so:

from gpiozero.pins.rpio import RPIOPin
from gpiozero import LED

led = LED(RPIOPin(12))

PiGPIOPin

class gpiozero.pins.pigpiod.PiGPIOPin[source]

Uses the pigpio library to interface to the Pi’s GPIO pins. The pigpio library relies on a daemon (pigpiod) to be running as root to provide access to the GPIO pins, and communicates with this daemon over a network socket.

While this does mean only the daemon itself should control the pins, the architecture does have several advantages:

  • Pins can be remote controlled from another machine (the other machine doesn’t even have to be a Raspberry Pi; it simply needs the pigpio client library installed on it)
  • The daemon supports hardware PWM via the DMA controller
  • Your script itself doesn’t require root privileges; it just needs to be able to communicate with the daemon

You can construct pigpiod pins manually like so:

from gpiozero.pins.pigpiod import PiGPIOPin
from gpiozero import LED

led = LED(PiGPIOPin(12))

This is particularly useful for controlling pins on a remote machine. To accomplish this simply specify the host (and optionally port) when constructing the pin:

from gpiozero.pins.pigpiod import PiGPIOPin
from gpiozero import LED
from signal import pause

led = LED(PiGPIOPin(12, host='192.168.0.2'))

Note

In some circumstances, especially when playing with PWM, it does appear to be possible to get the daemon into “unusual” states. We would be most interested to hear any bug reports relating to this (it may be a bug in our pin implementation). A workaround for now is simply to restart the pigpiod daemon.

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!

You can construct native pin instances manually like so:

from gpiozero.pins.native import NativePin
from gpiozero import LED

led = LED(NativePin(12))

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()
  • _set_function()
  • _get_state()

The following functions may be overridden if applicable:

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.

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.

Utilities

The pins module also contains a database of information about the various revisions of Raspberry Pi. This is used internally to raise warnings when non-physical pins are used, or to raise exceptions when pull-downs are requested on pins with physical pull-up resistors attached. The following functions and classes can be used to query this database:

gpiozero.pi_info(revision=None)[source]

Returns a PiBoardInfo instance containing information about a revision of the Raspberry Pi.

Parameters:revision (str) – The revision of the Pi to return information about. If this is omitted or None (the default), then the library will attempt to determine the model of Pi it is running on and return information about that.
class gpiozero.PiBoardInfo[source]

This class is a namedtuple() derivative used to represent information about a particular model of Raspberry Pi. While it is a tuple, it is strongly recommended that you use the following named attributes to access the data contained within.

revision

A string indicating the revision of the Pi. This is unique to each revision and can be considered the “key” from which all other attributes are derived. However, in itself the string is fairly meaningless.

model

A string containing the model of the Pi (for example, “B”, “B+”, “A+”, “2B”, “CM” (for the Compute Module), or “Zero”).

pcb_revision

A string containing the PCB revision number which is silk-screened onto the Pi (on some models).

Note

This is primarily useful to distinguish between the model B revision 1.0 and 2.0 (not to be confused with the model 2B) which had slightly different pinouts on their 26-pin GPIO headers.

released

A string containing an approximate release date for this revision of the Pi (formatted as yyyyQq, e.g. 2012Q1 means the first quarter of 2012).

soc

A string indicating the SoC (system on a chip) that this revision of the Pi is based upon.

manufacturer

A string indicating the name of the manufacturer (usually “Sony” but a few others exist).

memory

An integer indicating the amount of memory (in Mb) connected to the SoC.

Note

This can differ substantially from the amount of RAM available to the operating system as the GPU’s memory is shared with the CPU. When the camera module is activated, at least 128Mb of RAM is typically reserved for the GPU.

storage

A string indicating the type of bootable storage used with this revision of Pi, e.g. “SD”, “MicroSD”, or “eMMC” (for the Compute Module).

usb

An integer indicating how many USB ports are physically present on this revision of the Pi.

Note

This does not include the micro-USB port used to power the Pi. On the Compute Module this is listed as 0 as the compute module itself doesn’t have any physical USB headers, despite providing one on the I/O development board and having the pins for one on the module itself.

ethernet

An integer indicating how many Ethernet ports are physically present on this revision of the Pi.

wifi

A bool indicating whether this revision of the Pi has wifi built-in.

bluetooth

A bool indicating whether this revision of the Pi has bluetooth built-in.

csi

An integer indicating the number of CSI (camera) ports available on this revision of the Pi.

dsi

An integer indicating the number of DSI (display) ports available on this revision of the Pi.

headers

A dictionary which maps header labels to dictionaries which map physical pin numbers to PinInfo tuples. For example, to obtain information about pin 12 on header P1 you would query headers['P1'][12].

class gpiozero.PinInfo[source]

This class is a namedtuple() derivative used to represent information about a pin present on a GPIO header. The following attributes are defined:

number

An integer containing the physical pin number on the header (starting from 1 in accordance with convention).

function

A string describing the function of the pin. Some common examples include “GND” (for pins connecting to ground), “3V3” (for pins which output 3.3 volts), “GPIO9” (for GPIO9 in the Broadcom numbering scheme), etc.

pull_up

A bool indicating whether the pin has a physical pull-up resistor permanently attached (this is usually False but GPIO2 and GPIO3 are usually True). This is used internally by gpiozero to raise errors when pull-down is requested on a pin with a physical pull-up resistor.