Boards and Accessories

These additional interfaces are provided to group collections of components together for ease of use, and as examples. They are composites made up of components from the various Input Devices and Output Devices provided by GPIO Zero. See those pages for more information on using components individually.

Note

All GPIO pin numbers use Broadcom (BCM) numbering. See the Recipes page for more information.

LEDBoard

class gpiozero.LEDBoard(*pins, pwm=False, active_high=True, initial_value=False, **named_pins)[source]

Extends LEDCollection and represents a generic LED board or collection of LEDs.

The following example turns on all the LEDs on a board containing 5 LEDs attached to GPIO pins 2 through 6:

from gpiozero import LEDBoard

leds = LEDBoard(2, 3, 4, 5, 6)
leds.on()
Parameters:
  • *pins (int) – Specify the GPIO pins that the LEDs of the board are attached to. You can designate as many pins as necessary. You can also specify LEDBoard instances to create trees of LEDs.
  • pwm (bool) – If True, construct PWMLED instances for each pin. If False (the default), construct regular LED instances. This parameter can only be specified as a keyword parameter.
  • active_high (bool) – If True (the default), the on() method will set all the associates pins to HIGH. If False, the on() method will set all pins to LOW (the off() method always does the opposite).
  • initial_value (bool) – If False (the default), all LEDs will be off initially. If None, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). If True, the device will be switched on initially.
  • **named_pins – Sepcify GPIO pins that LEDs of the board are attached to, associated each LED with a property name. You can designate as many pins as necessary and any name provided it’s not already in use by something else. You can also specify LEDBoard instances to create trees of LEDs.

Make all the LEDs turn on and off repeatedly.

Parameters:
  • on_time (float) – Number of seconds on. Defaults to 1 second.
  • off_time (float) – Number of seconds off. Defaults to 1 second.
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
close()[source]

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...
off(*args)[source]

Turn all the output devices off.

on(*args)[source]

Turn all the output devices on.

pulse(fade_in_time=1, fade_out_time=1, n=None, background=True)[source]

Make the device fade in and out repeatedly.

Parameters:
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 1.
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True (the default), start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
toggle(*args)[source]

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

LEDBarGraph

class gpiozero.LEDBarGraph(*pins, initial_value=0)[source]

Extends LEDCollection to control a line of LEDs representing a bar graph. Positive values (0 to 1) light the LEDs from first to last. Negative values (-1 to 0) light the LEDs from last to first.

The following example demonstrates turning on the first two and last two LEDs in a board containing five LEDs attached to GPIOs 2 through 6:

from gpiozero import LEDBarGraph
from time import sleep

graph = LEDBarGraph(2, 3, 4, 5, 6)
graph.value = 2/5  # Light the first two LEDs only
sleep(1)
graph.value = -2/5 # Light the last two LEDs only
sleep(1)
graph.off()

As with other output devices, source and values are supported:

from gpiozero import LEDBarGraph, MCP3008
from signal import pause

graph = LEDBarGraph(2, 3, 4, 5, 6, pwm=True)
pot = MCP3008(channel=0)
graph.source = pot.values
pause()
Parameters:
  • *pins (int) – Specify the GPIO pins that the LEDs of the bar graph are attached to. You can designate as many pins as necessary.
  • initial_value (float) – The initial value of the graph given as a float between -1 and +1. Defaults to 0.0. This parameter can only be specified as a keyword parameter.
  • pwm (bool) – If True, construct PWMLED instances for each pin. If False (the default), construct regular LED instances. This parameter can only be specified as a keyword parameter.
off()

Turn all the output devices off.

on()

Turn all the output devices on.

toggle()

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

The value of the LED bar graph. When no LEDs are lit, the value is 0. When all LEDs are lit, the value is 1. Values between 0 and 1 light LEDs linearly from first to last. Values between 0 and -1 light LEDs linearly from last to first.

To light a particular number of LEDs, simply divide that number by the number of LEDs. For example, if your graph contains 3 LEDs, the following will light the first:

from gpiozero import LEDBarGraph

graph = LEDBarGraph(12, 16, 19)
graph.value = 1/3

Note

Setting value to -1 will light all LEDs. However, querying it subsequently will return 1 as both representations are the same in hardware. The readable range of value is effectively -1 < value <= 1.

values

An infinite iterator of values read from value.

TrafficLights

class gpiozero.TrafficLights(red=None, amber=None, green=None, pwm=False)[source]

Extends LEDBoard for devices containing red, amber, and green LEDs.

The following example initializes a device connected to GPIO pins 2, 3, and 4, then lights the amber LED attached to GPIO 3:

from gpiozero import TrafficLights

traffic = TrafficLights(2, 3, 4)
traffic.amber.on()
Parameters:
  • red (int) – The GPIO pin that the red LED is attached to.
  • amber (int) – The GPIO pin that the amber LED is attached to.
  • green (int) – The GPIO pin that the green LED is attached to.
  • pwm (bool) – If True, construct PWMLED instances to represent each LED. If False (the default), construct regular LED instances.

Make all the LEDs turn on and off repeatedly.

Parameters:
  • on_time (float) – Number of seconds on. Defaults to 1 second.
  • off_time (float) – Number of seconds off. Defaults to 1 second.
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
close()

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...
off(*args)

Turn all the output devices off.

on(*args)

Turn all the output devices on.

pulse(fade_in_time=1, fade_out_time=1, n=None, background=True)

Make the device fade in and out repeatedly.

Parameters:
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 1.
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True (the default), start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
toggle(*args)

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

PiLITEr

class gpiozero.PiLiter(pwm=False)[source]

Extends LEDBoard for the Ciseco Pi-LITEr: a strip of 8 very bright LEDs.

The Pi-LITEr pins are fixed and therefore there’s no need to specify them when constructing this class. The following example turns on all the LEDs of the Pi-LITEr:

from gpiozero import PiLiter

lite = PiLiter()
lite.on()
Parameters:pwm (bool) – If True, construct PWMLED instances for each pin. If False (the default), construct regular LED instances. This parameter can only be specified as a keyword parameter.

Make all the LEDs turn on and off repeatedly.

Parameters:
  • on_time (float) – Number of seconds on. Defaults to 1 second.
  • off_time (float) – Number of seconds off. Defaults to 1 second.
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
close()

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...
off(*args)

Turn all the output devices off.

on(*args)

Turn all the output devices on.

pulse(fade_in_time=1, fade_out_time=1, n=None, background=True)

Make the device fade in and out repeatedly.

Parameters:
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 1.
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True (the default), start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
toggle(*args)

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

PiLITEr Bar Graph

class gpiozero.PiLiterBarGraph(initial_value=0)[source]

Extends LEDBarGraph to treat the Ciseco Pi-LITEr as an 8-segment bar graph.

The Pi-LITEr pins are fixed and therefore there’s no need to specify them when constructing this class. The following example sets the graph value to 0.5:

from gpiozero import PiLiterBarGraph

graph = PiLiterBarGraph()
graph.value = 0.5
Parameters:initial_value (bool) – The initial value of the graph given as a float between -1 and +1. Defaults to 0.0.
off()

Turn all the output devices off.

on()

Turn all the output devices on.

toggle()

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

The value of the LED bar graph. When no LEDs are lit, the value is 0. When all LEDs are lit, the value is 1. Values between 0 and 1 light LEDs linearly from first to last. Values between 0 and -1 light LEDs linearly from last to first.

To light a particular number of LEDs, simply divide that number by the number of LEDs. For example, if your graph contains 3 LEDs, the following will light the first:

from gpiozero import LEDBarGraph

graph = LEDBarGraph(12, 16, 19)
graph.value = 1/3

Note

Setting value to -1 will light all LEDs. However, querying it subsequently will return 1 as both representations are the same in hardware. The readable range of value is effectively -1 < value <= 1.

values

An infinite iterator of values read from value.

PI-TRAFFIC

class gpiozero.PiTraffic[source]

Extends TrafficLights for the Low Voltage Labs PI-TRAFFIC: vertical traffic lights board when attached to GPIO pins 9, 10, and 11.

There’s no need to specify the pins if the PI-TRAFFIC is connected to the default pins (9, 10, 11). The following example turns on the amber LED on the PI-TRAFFIC:

from gpiozero import PiTraffic

traffic = PiTraffic()
traffic.amber.on()

To use the PI-TRAFFIC board when attached to a non-standard set of pins, simply use the parent class, TrafficLights.

Make all the LEDs turn on and off repeatedly.

Parameters:
  • on_time (float) – Number of seconds on. Defaults to 1 second.
  • off_time (float) – Number of seconds off. Defaults to 1 second.
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0. Must be 0 if pwm was False when the class was constructed (ValueError will be raised if not).
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
close()

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...
off(*args)

Turn all the output devices off.

on(*args)

Turn all the output devices on.

pulse(fade_in_time=1, fade_out_time=1, n=None, background=True)

Make the device fade in and out repeatedly.

Parameters:
  • fade_in_time (float) – Number of seconds to spend fading in. Defaults to 1.
  • fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
  • n (int) – Number of times to blink; None (the default) means forever.
  • background (bool) – If True (the default), start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning).
toggle(*args)

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

TrafficLightsBuzzer

class gpiozero.TrafficLightsBuzzer(lights, buzzer, button)[source]

Extends CompositeDevice and is a generic class for HATs with traffic lights, a button and a buzzer.

Parameters:
  • lights (TrafficLights) – An instance of TrafficLights representing the traffic lights of the HAT.
  • buzzer (Buzzer) – An instance of Buzzer representing the buzzer on the HAT.
  • button (Button) – An instance of Button representing the button on the HAT.
off()

Turn all the output devices off.

on()

Turn all the output devices on.

toggle()

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

Fish Dish

class gpiozero.FishDish(pwm=False)[source]

Extends TrafficLightsBuzzer for the Pi Supply FishDish: traffic light LEDs, a button and a buzzer.

The FishDish pins are fixed and therefore there’s no need to specify them when constructing this class. The following example waits for the button to be pressed on the FishDish, then turns on all the LEDs:

from gpiozero import FishDish

fish = FishDish()
fish.button.wait_for_press()
fish.lights.on()
Parameters:pwm (bool) – If True, construct PWMLED instances to represent each LED. If False (the default), construct regular LED instances.
off()

Turn all the output devices off.

on()

Turn all the output devices on.

toggle()

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

Traffic HAT

class gpiozero.TrafficHat(pwm=False)[source]

Extends TrafficLightsBuzzer for the Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer.

The Traffic HAT pins are fixed and therefore there’s no need to specify them when constructing this class. The following example waits for the button to be pressed on the Traffic HAT, then turns on all the LEDs:

from gpiozero import TrafficHat

hat = TrafficHat()
hat.button.wait_for_press()
hat.lights.on()
Parameters:pwm (bool) – If True, construct PWMLED instances to represent each LED. If False (the default), construct regular LED instances.
off()

Turn all the output devices off.

on()

Turn all the output devices on.

toggle()

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

values

An infinite iterator of values read from value.

Robot

class gpiozero.Robot(left=None, right=None)[source]

Extends CompositeDevice to represent a generic dual-motor robot.

This class is constructed with two tuples representing the forward and backward pins of the left and right controllers respectively. For example, if the left motor’s controller is connected to GPIOs 4 and 14, while the right motor’s controller is connected to GPIOs 17 and 18 then the following example will turn the robot left:

from gpiozero import Robot

robot = Robot(left=(4, 14), right=(17, 18))
robot.left()
Parameters:
  • left (tuple) – A tuple of two GPIO pins representing the forward and backward inputs of the left motor’s controller.
  • right (tuple) – A tuple of two GPIO pins representing the forward and backward inputs of the right motor’s controller.
backward(speed=1)[source]

Drive the robot backward by running both motors backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
forward(speed=1)[source]

Drive the robot forward by running both motors forward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
left(speed=1)[source]

Make the robot turn left by running the right motor forward and left motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
reverse()[source]

Reverse the robot’s current motor directions. If the robot is currently running full speed forward, it will run full speed backward. If the robot is turning left at half-speed, it will turn right at half-speed. If the robot is currently stopped it will remain stopped.

right(speed=1)[source]

Make the robot turn right by running the left motor forward and right motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
stop()[source]

Stop the robot.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

values

An infinite iterator of values read from value.

Ryanteck MCB Robot

class gpiozero.RyanteckRobot[source]

Extends Robot for the Ryanteck MCB robot.

The Ryanteck MCB pins are fixed and therefore there’s no need to specify them when constructing this class. The following example turns the robot left:

from gpiozero import RyanteckRobot

robot = RyanteckRobot()
robot.left()
backward(speed=1)

Drive the robot backward by running both motors backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
forward(speed=1)

Drive the robot forward by running both motors forward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
left(speed=1)

Make the robot turn left by running the right motor forward and left motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
reverse()

Reverse the robot’s current motor directions. If the robot is currently running full speed forward, it will run full speed backward. If the robot is turning left at half-speed, it will turn right at half-speed. If the robot is currently stopped it will remain stopped.

right(speed=1)

Make the robot turn right by running the left motor forward and right motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
stop()

Stop the robot.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

values

An infinite iterator of values read from value.

CamJam #3 Kit Robot

class gpiozero.CamJamKitRobot[source]

Extends Robot for the CamJam #3 EduKit robot controller.

The CamJam robot controller pins are fixed and therefore there’s no need to specify them when constructing this class. The following example turns the robot left:

from gpiozero import CamJamKitRobot

robot = CamJamKitRobot()
robot.left()
backward(speed=1)

Drive the robot backward by running both motors backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
forward(speed=1)

Drive the robot forward by running both motors forward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
left(speed=1)

Make the robot turn left by running the right motor forward and left motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
reverse()

Reverse the robot’s current motor directions. If the robot is currently running full speed forward, it will run full speed backward. If the robot is turning left at half-speed, it will turn right at half-speed. If the robot is currently stopped it will remain stopped.

right(speed=1)

Make the robot turn right by running the left motor forward and right motor backward.

Parameters:speed (float) – Speed at which to drive the motors, as a value between 0 (stopped) and 1 (full speed). The default is 1.
stop()

Stop the robot.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

values

An infinite iterator of values read from value.

Energenie

class gpiozero.Energenie(socket=None, initial_value=False)[source]

Extends Device to represent an Energenie socket controller.

This class is constructed with a socket number and an optional initial state (defaults to False, meaning off). Instances of this class can be used to switch peripherals on and off. For example:

from gpiozero import Energenie

lamp = Energenie(1)
lamp.on()
Parameters:
  • socket (int) – Which socket this instance should control. This is an integer number between 1 and 4.
  • initial_value (bool) – The initial state of the socket. As Energenie sockets provide no means of reading their state, you must provide an initial state for the socket, which will be set upon construction. This defaults to False which will switch the socket off.
close()[source]

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...
is_active

Returns True if the device is currently active and False otherwise. This property is usually derived from value. Unlike value, this is always a boolean.

source

The iterable to use as a source of values for value.

source_delay

The delay (measured in seconds) in the loop used to read values from source. Defaults to 0.01 seconds which is generally sufficient to keep CPU usage to a minimum while providing adequate responsiveness.

values

An infinite iterator of values read from value.

Base Classes

The classes in the sections above are derived from a series of base classes, some of which are effectively abstract. The classes form the (partial) hierarchy displayed in the graph below:

_images/composite_device_hierarchy.svg

For composite devices, the following chart shows which devices are composed of which other devices:

_images/composed_devices.svg

The following sections document these base classes for advanced users that wish to construct classes for their own devices.

LEDCollection

class gpiozero.LEDCollection(*args, **kwargs)[source]

Extends CompositeOutputDevice. Abstract base class for LEDBoard and LEDBarGraph.

leds

A flat iterator over all LEDs contained in this collection (and all sub-collections).

CompositeOutputDevice

class gpiozero.CompositeOutputDevice(*args, _order=None, **kwargs)[source]

Extends CompositeDevice with on(), off(), and toggle() methods for controlling subordinate output devices. Also extends value to be writeable.

Parameters:_order (list) – If specified, this is the order of named items specified by keyword arguments (to ensure that the value tuple is constructed with a specific order). All keyword arguments must be included in the collection. If omitted, an alphabetically sorted order will be selected for keyword arguments.
off()[source]

Turn all the output devices off.

on()[source]

Turn all the output devices on.

toggle()[source]

Toggle all the output devices. For each device, if it’s on, turn it off; if it’s off, turn it on.

value

A tuple containing a value for each subordinate device. This property can also be set to update the state of all subordinate output devices.

CompositeDevice

class gpiozero.CompositeDevice(*args, _order=None, **kwargs)[source]

Extends Device. Represents a device composed of multiple devices like simple HATs, H-bridge motor controllers, robots composed of multiple motors, etc.

The constructor accepts subordinate devices as positional or keyword arguments. Positional arguments form unnamed devices accessed via the all attribute, while keyword arguments are added to the device as named (read-only) attributes.

Parameters:_order (list) – If specified, this is the order of named items specified by keyword arguments (to ensure that the value tuple is constructed with a specific order). All keyword arguments must be included in the collection. If omitted, an alphabetically sorted order will be selected for keyword arguments.
close()[source]

Shut down the device and release all associated resources. This method can be called on an already closed device without raising an exception.

This method is primarily intended for interactive use at the command line. It disables the device and releases its pin(s) for use by another device.

You can attempt to do this simply by deleting an object, but unless you’ve cleaned up all references to the object this may not work (even if you’ve cleaned up all references, there’s still no guarantee the garbage collector will actually delete the object at that point). By contrast, the close method provides a means of ensuring that the object is shut down.

For example, if you have a breadboard with a buzzer connected to pin 16, but then wish to attach an LED instead:

>>> from gpiozero import *
>>> bz = Buzzer(16)
>>> bz.on()
>>> bz.off()
>>> bz.close()
>>> led = LED(16)
>>> led.blink()

Device descendents can also be used as context managers using the with statement. For example:

>>> from gpiozero import *
>>> with Buzzer(16) as bz:
...     bz.on()
...
>>> with LED(16) as led:
...     led.on()
...