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.
LED Board¶
-
class
gpiozero.
LEDBoard
(*pins, pwm=False)[source]¶ Extends
CompositeDevice
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.
- pwm (bool) – If
True
, constructPWMLED
instances for each pin. IfFalse
(the default), construct regularLED
instances. This parameter can only be specified as a keyword parameter.
-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)[source]¶ 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
wasFalse
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
wasFalse
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. IfFalse
, only return when the blink is finished (warning: the default value of n will result in this method never returning).
-
toggle
()[source]¶ Toggle all the LEDs. For each LED, 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.
-
value
¶ A tuple containing a value for each LED on the board. This property can also be set to update the state of all LEDs on the board.
-
values
¶ An infinite iterator of values read from value.
LED Bar Graph¶
-
class
gpiozero.
LEDBarGraph
(*pins, initial_value=0)[source]¶ Extends
CompositeDevice
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 turns on all the LEDs on a board containing 5 LEDs attached to GPIO pins 2 through 6:
from gpiozero import LEDBarGraph graph = LEDBarGraph(2, 3, 4, 5, 6) graph.value = 2/5 # Light the first two LEDs only graph.value = -2/5 # Light the last two LEDs only graph.off()
As with other output devices,
source
andvalues
are supported:from gpiozero import LEDBarGraph, MCP3008 from signal import pause graph = LEDBarGraph(2, 3, 4, 5, 6) pot = MCP3008(channel=0) graph.source = pot.values pause()
Parameters: -
close
()¶ Shut down the device and release all associated resources.
-
off
()¶ Turn all the LEDs off.
-
on
()¶ Turn all the LEDs on.
-
toggle
()¶ Toggle all the LEDs. For each LED, 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.
-
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.
-
values
¶ An infinite iterator of values read from value.
-
Traffic Lights¶
-
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
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances.
-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)¶ 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
wasFalse
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
wasFalse
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. IfFalse
, 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.
-
off
()¶ Turn all the LEDs off.
-
on
()¶ Turn all the LEDs on.
-
toggle
()¶ Toggle all the LEDs. For each LED, 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.
-
value
¶ A 3-tuple containing values for the red, amber, and green LEDs. This property can also be set to alter the state of the LEDs.
-
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
, constructPWMLED
instances for each pin. IfFalse
(the default), construct regularLED
instances. This parameter can only be specified as a keyword parameter.-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)¶ 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
wasFalse
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
wasFalse
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. IfFalse
, 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.
-
off
()¶ Turn all the LEDs off.
-
on
()¶ Turn all the LEDs on.
-
toggle
()¶ Toggle all the LEDs. For each LED, 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.
-
value
¶ A tuple containing a value for each LED on the board. This property can also be set to update the state of all LEDs on the board.
-
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. -
close
()¶ Shut down the device and release all associated resources.
-
off
()¶ Turn all the LEDs off.
-
on
()¶ Turn all the LEDs on.
-
toggle
()¶ Toggle all the LEDs. For each LED, 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.
-
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.
-
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
.-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)¶ 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
wasFalse
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
wasFalse
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. IfFalse
, 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.
-
off
()¶ Turn all the LEDs off.
-
on
()¶ Turn all the LEDs on.
-
toggle
()¶ Toggle all the LEDs. For each LED, 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.
-
value
¶ A 3-tuple containing values for the red, amber, and green LEDs. This property can also be set to alter the state of the LEDs.
-
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.
-
blink
(on_time=1, off_time=1, n=None, background=True)[source]¶ Make all the board’s components turn on and off repeatedly.
Parameters: - on_time (float) – Number of seconds on
- off_time (float) – Number of seconds off
- n (int) – Number of times to blink;
None
means forever - background (bool) – If
True
, start a background thread to continue blinking and return immediately. IfFalse
, only return when the blink is finished (warning: the default value of n will result in this method never returning).
-
toggle
()[source]¶ Toggle all the board’s components. For each component, if it’s on, turn it off; if it’s off, turn it on.
-
all
¶ A tuple containing objects for all the items on the board (several
LED
objects, aBuzzer
, and aButton
).
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a named-tuple containing values representing the states of the LEDs, and the buzzer. This property can also be set to a 4-tuple to update the state of all the board’s components.
-
values
¶ An infinite iterator of values read from value.
- lights (TrafficLights) – An instance of
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
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances.-
blink
(on_time=1, off_time=1, n=None, background=True)¶ Make all the board’s components turn on and off repeatedly.
Parameters: - on_time (float) – Number of seconds on
- off_time (float) – Number of seconds off
- n (int) – Number of times to blink;
None
means forever - background (bool) – If
True
, start a background thread to continue blinking and return immediately. IfFalse
, 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.
-
off
()¶ Turn all the board’s components off.
-
on
()¶ Turn all the board’s components on.
-
toggle
()¶ Toggle all the board’s components. For each component, if it’s on, turn it off; if it’s off, turn it on.
-
all
¶ A tuple containing objects for all the items on the board (several
LED
objects, aBuzzer
, and aButton
).
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a named-tuple containing values representing the states of the LEDs, and the buzzer. This property can also be set to a 4-tuple to update the state of all the board’s components.
-
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
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances.-
blink
(on_time=1, off_time=1, n=None, background=True)¶ Make all the board’s components turn on and off repeatedly.
Parameters: - on_time (float) – Number of seconds on
- off_time (float) – Number of seconds off
- n (int) – Number of times to blink;
None
means forever - background (bool) – If
True
, start a background thread to continue blinking and return immediately. IfFalse
, 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.
-
off
()¶ Turn all the board’s components off.
-
on
()¶ Turn all the board’s components on.
-
toggle
()¶ Toggle all the board’s components. For each component, if it’s on, turn it off; if it’s off, turn it on.
-
all
¶ A tuple containing objects for all the items on the board (several
LED
objects, aBuzzer
, and aButton
).
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a named-tuple containing values representing the states of the LEDs, and the buzzer. This property can also be set to a 4-tuple to update the state of all the board’s components.
-
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: -
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.
-
left_motor
¶ Returns the Motor device representing the robot’s left motor.
-
right_motor
¶ Returns the Motor device representing the robot’s right motor.
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a tuple of two floating point values (-1 to 1) representing the speeds of the robot’s two motors (left and right). This property can also be set to alter the speed of both motors.
-
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.
-
close
()¶ Shut down the device and release all associated resources.
-
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.
-
left_motor
¶ Returns the Motor device representing the robot’s left motor.
-
right_motor
¶ Returns the Motor device representing the robot’s right motor.
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a tuple of two floating point values (-1 to 1) representing the speeds of the robot’s two motors (left and right). This property can also be set to alter the speed of both motors.
-
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.
-
close
()¶ Shut down the device and release all associated resources.
-
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.
-
left_motor
¶ Returns the Motor device representing the robot’s left motor.
-
right_motor
¶ Returns the Motor device representing the robot’s right motor.
-
source
¶ The iterable to use as a source of values for value.
-
value
¶ Returns a tuple of two floating point values (-1 to 1) representing the speeds of the robot’s two motors (left and right). This property can also be set to alter the speed of both motors.
-
values
¶ An infinite iterator of values read from value.
-