15. API - 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 API - Input Devices and API - 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 Basic Recipes page for more information.
15.1. LEDBoard¶
-
class
gpiozero.
LEDBoard
(*pins, pwm=False, active_high=True, initial_value=False, pin_factory=None, **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
, constructPWMLED
instances for each pin. IfFalse
(the default), construct regularLED
instances. This parameter can only be specified as a keyword parameter. - active_high (bool) – If
True
(the default), theon()
method will set all the associated pins to HIGH. IfFalse
, theon()
method will set all pins to LOW (theoff()
method always does the opposite). This parameter can only be specified as a keyword parameter. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. This parameter can only be specified as a keyword parameter. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
- **named_pins – Specify GPIO pins that LEDs of the board are attached to, associating
each LED with a property name. You can designate as many pins as
necessary and use any names, provided they’re not already in use by
something else. You can also specify
LEDBoard
instances to create trees of LEDs.
-
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).
-
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 thewith
statement. For example:>>> from gpiozero import * >>> with Buzzer(16) as bz: ... bz.on() ... >>> with LED(16) as led: ... led.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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
- *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
15.2. LEDBarGraph¶
-
class
gpiozero.
LEDBarGraph
(*pins, pwm=False, active_high=True, initial_value=0, pin_factory=None)[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
andvalues
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.
- 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. - active_high (bool) – If
True
(the default), theon()
method will set all the associated pins to HIGH. IfFalse
, theon()
method will set all pins to LOW (theoff()
method always does the opposite). This parameter can only be specified as a keyword parameter. - initial_value (float) – The initial
value
of the graph given as a float between -1 and +1. Defaults to0.0
. This parameter can only be specified as a keyword parameter. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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 tuple of all LEDs contained in this collection (and all sub-collections).
-
lit_count
¶ The number of LEDs on the bar graph actually lit up. Note that just like
value
, this can be negative if the LEDs are lit from last to first.
-
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.
15.3. ButtonBoard¶
-
class
gpiozero.
ButtonBoard
(*pins, pull_up=True, bounce_time=None, hold_time=1, hold_repeat=False, pin_factory=None, **named_pins)[source]¶ Extends
CompositeDevice
and represents a generic button board or collection of buttons.Parameters: - *pins (int) – Specify the GPIO pins that the buttons of the board are attached to. You can designate as many pins as necessary.
- pull_up (bool) – If
True
(the default), the GPIO pins will be pulled high by default. In this case, connect the other side of the buttons to ground. IfFalse
, the GPIO pins will be pulled low by default. In this case, connect the other side of the buttons to 3V3. This parameter can only be specified as a keyword parameter. - bounce_time (float) – If
None
(the default), no software bounce compensation will be performed. Otherwise, this is the length of time (in seconds) that the buttons will ignore changes in state after an initial change. This parameter can only be specified as a keyword parameter. - hold_time (float) – The length of time (in seconds) to wait after any button is pushed,
until executing the
when_held
handler. Defaults to1
. This parameter can only be specified as a keyword parameter. - hold_repeat (bool) – If
True
, thewhen_held
handler will be repeatedly executed as long as any buttons remain held, every hold_time seconds. IfFalse
(the default) thewhen_held
handler will be only be executed once per hold. This parameter can only be specified as a keyword parameter. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
- **named_pins – Specify GPIO pins that buttons of the board are attached to, associating each button with a property name. You can designate as many pins as necessary and use any names, provided they’re not already in use by something else.
-
wait_for_active
(timeout=None)¶ Pause the script until the device is activated, or the timeout is reached.
Parameters: timeout (float) – Number of seconds to wait before proceeding. If this is None
(the default), then wait indefinitely until the device is active.
-
wait_for_inactive
(timeout=None)¶ Pause the script until the device is deactivated, or the timeout is reached.
Parameters: timeout (float) – Number of seconds to wait before proceeding. If this is None
(the default), then wait indefinitely until the device is inactive.
-
wait_for_press
(timeout=None)¶ Pause the script until the device is activated, or the timeout is reached.
Parameters: timeout (float) – Number of seconds to wait before proceeding. If this is None
(the default), then wait indefinitely until the device is active.
-
wait_for_release
(timeout=None)¶ Pause the script until the device is deactivated, or the timeout is reached.
Parameters: timeout (float) – Number of seconds to wait before proceeding. If this is None
(the default), then wait indefinitely until the device is inactive.
-
active_time
¶ The length of time (in seconds) that the device has been active for. When the device is inactive, this is
None
.
-
held_time
¶ The length of time (in seconds) that the device has been held for. This is counted from the first execution of the
when_held
event rather than when the device activated, in contrast toactive_time
. If the device is not currently held, this isNone
.
-
hold_repeat
¶ If
True
,when_held
will be executed repeatedly withhold_time
seconds between each invocation.
-
hold_time
¶ The length of time (in seconds) to wait after the device is activated, until executing the
when_held
handler. Ifhold_repeat
is True, this is also the length of time between invocations ofwhen_held
.
-
inactive_time
¶ The length of time (in seconds) that the device has been inactive for. When the device is active, this is
None
.
-
pressed_time
¶ The length of time (in seconds) that the device has been active for. When the device is inactive, this is
None
.
-
pull_up
¶ If
True
, the device uses a pull-up resistor to set the GPIO pin “high” by default.
-
values
¶ An infinite iterator of values read from value.
-
when_activated
¶ The function to run when the device changes state from inactive to active.
This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.
Set this property to
None
(the default) to disable the event.
-
when_deactivated
¶ The function to run when the device changes state from active to inactive.
This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that deactivated will be passed as that parameter.
Set this property to
None
(the default) to disable the event.
-
when_held
¶ The function to run when the device has remained active for
hold_time
seconds.This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.
Set this property to
None
(the default) to disable the event.
-
when_pressed
¶ The function to run when the device changes state from inactive to active.
This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.
Set this property to
None
(the default) to disable the event.
-
when_released
¶ The function to run when the device changes state from active to inactive.
This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that deactivated will be passed as that parameter.
Set this property to
None
(the default) to disable the event.
15.4. TrafficLights¶
-
class
gpiozero.
TrafficLights
(red=None, amber=None, green=None, pwm=False, initial_value=False, yellow=None, pin_factory=None)[source]¶ Extends
LEDBoard
for devices containing red, yellow, and green LEDs.The following example initializes a device connected to GPIO pins 2, 3, and 4, then lights the amber (yellow) 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. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. - yellow (int) – The GPIO pin that the yellow LED is attached to. This is merely an
alias for the
amber
parameter - you can’t specify bothamber
andyellow
. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
15.5. LedBorg¶
-
class
gpiozero.
LedBorg
(initial_value=(0, 0, 0), pwm=True, pin_factory=None)[source]¶ Extends
RGBLED
for the PiBorg LedBorg: an add-on board containing a very bright RGB LED.The LedBorg pins are fixed and therefore there’s no need to specify them when constructing this class. The following example turns the LedBorg purple:
from gpiozero import LedBorg led = LedBorg() led.color = (1, 0, 1)
Parameters: - initial_value (tuple) – The initial color for the LedBorg. Defaults to black
(0, 0, 0)
. - pwm (bool) – If
True
(the default), constructPWMLED
instances for each component of the LedBorg. IfFalse
, construct regularLED
instances, which prevents smooth color graduations. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, on_color=(1, 1, 1), off_color=(0, 0, 0), n=None, background=True)¶ Make the device 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). - on_color (tuple) – The color to use when the LED is “on”. Defaults to white.
- off_color (tuple) – The color to use when the LED is “off”. Defaults to black.
- 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. 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. 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 thewith
statement. For example:>>> from gpiozero import * >>> with Buzzer(16) as bz: ... bz.on() ... >>> with LED(16) as led: ... led.on() ...
-
off
()¶ Turn the LED off. This is equivalent to setting the LED color to black
(0, 0, 0)
.
-
on
()¶ Turn the LED on. This equivalent to setting the LED color to white
(1, 1, 1)
.
-
pulse
(fade_in_time=1, fade_out_time=1, on_color=(1, 1, 1), off_color=(0, 0, 0), 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.
- on_color (tuple) – The color to use when the LED is “on”. Defaults to white.
- off_color (tuple) – The color to use when the LED is “off”. Defaults to black.
- n (int) – Number of times to pulse;
None
(the default) means forever. - background (bool) – If
True
(the default), start a background thread to continue pulsing and return immediately. IfFalse
, only return when the pulse is finished (warning: the default value of n will result in this method never returning).
-
toggle
()¶ Toggle the state of the device. If the device is currently off (
value
is(0, 0, 0)
), this changes it to “fully” on (value
is(1, 1, 1)
). If the device has a specific color, this method inverts the color.
-
color
¶ Represents the color of the LED as an RGB 3-tuple of
(red, green, blue)
where each value is between 0 and 1 ifpwm
wasTrue
when the class was constructed (and only 0 or 1 if not).For example, purple would be
(1, 0, 1)
and yellow would be(1, 1, 0)
, while orange would be(1, 0.5, 0)
.
-
is_active
¶ Returns
True
if the LED is currently active (not black) andFalse
otherwise.
-
is_lit
¶ Returns
True
if the LED is currently active (not black) andFalse
otherwise.
-
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
¶ Represents the color of the LED as an RGB 3-tuple of
(red, green, blue)
where each value is between 0 and 1 ifpwm
wasTrue
when the class was constructed (and only 0 or 1 if not).For example, purple would be
(1, 0, 1)
and yellow would be(1, 1, 0)
, while orange would be(1, 0.5, 0)
.
-
values
¶ An infinite iterator of values read from value.
- initial_value (tuple) – The initial color for the LedBorg. Defaults to black
15.6. PiLITEr¶
-
class
gpiozero.
PiLiter
(pwm=False, initial_value=False, pin_factory=None)[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. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
- pwm (bool) – If
15.7. PiLITEr Bar Graph¶
-
class
gpiozero.
PiLiterBarGraph
(pwm=False, initial_value=0.0, pin_factory=None)[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: - pwm (bool) – If
True
, constructPWMLED
instances for each pin. IfFalse
(the default), construct regularLED
instances. - initial_value (float) – The initial
value
of the graph given as a float between -1 and +1. Defaults to0.0
. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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 tuple of all LEDs contained in this collection (and all sub-collections).
-
lit_count
¶ The number of LEDs on the bar graph actually lit up. Note that just like
value
, this can be negative if the LEDs are lit from last to first.
-
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.
- pwm (bool) – If
15.8. PI-TRAFFIC¶
-
class
gpiozero.
PiTraffic
(pwm=False, initial_value=False, pin_factory=None)[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
.Parameters: - pwm (bool) – If
True
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
- pwm (bool) – If
15.9. Pi-Stop¶
-
class
gpiozero.
PiStop
(location=None, pwm=False, initial_value=False, pin_factory=None)[source]¶ Extends
TrafficLights
for the PiHardware Pi-Stop: a vertical traffic lights board.The following example turns on the amber LED on a Pi-Stop connected to location
A+
:from gpiozero import PiStop traffic = PiStop('A+') traffic.amber.on()
Parameters: - location (str) – The location on the GPIO header to which the Pi-Stop is connected.
Must be one of:
A
,A+
,B
,B+
,C
,D
. - pwm (bool) – If
True
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
- location (str) – The location on the GPIO header to which the Pi-Stop is connected.
Must be one of:
15.10. TrafficLightsBuzzer¶
-
class
gpiozero.
TrafficLightsBuzzer
(lights, buzzer, button, pin_factory=None)[source]¶ Extends
CompositeOutputDevice
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. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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_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.
- lights (TrafficLights) – An instance of
15.11. Fish Dish¶
-
class
gpiozero.
FishDish
(pwm=False, pin_factory=None)[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. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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_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.
- pwm (bool) – If
15.12. Traffic HAT¶
-
class
gpiozero.
TrafficHat
(pwm=False, pin_factory=None)[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. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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_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.
- pwm (bool) – If
15.13. Robot¶
-
class
gpiozero.
Robot
(left=None, right=None, pin_factory=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 drive the robot forward:
from gpiozero import Robot robot = Robot(left=(4, 14), right=(17, 18)) robot.forward()
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.
- pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
backward
(speed=1, **kwargs)[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.
- curve_left (float) – The amount to curve left while moving backwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving backwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
forward
(speed=1, **kwargs)[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.
- curve_left (float) – The amount to curve left while moving forwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving forwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
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.
-
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
¶ Represents the motion of the robot as a tuple of (left_motor_speed, right_motor_speed) with
(-1, -1)
representing full speed backwards,(1, 1)
representing full speed forwards, and(0, 0)
representing stopped.
-
values
¶ An infinite iterator of values read from value.
15.14. PhaseEnableRobot¶
-
class
gpiozero.
PhaseEnableRobot
(left=None, right=None, pin_factory=None)[source]¶ Extends
CompositeDevice
to represent a dual-motor robot based around a Phase/Enable motor board.This class is constructed with two tuples representing the phase (direction) and enable (speed) pins of the left and right controllers respectively. For example, if the left motor’s controller is connected to GPIOs 12 and 5, while the right motor’s controller is connected to GPIOs 13 and 6 so the following example will drive the robot forward:
from gpiozero import PhaseEnableRobot robot = PhaseEnableRobot(left=(5, 12), right=(6, 13)) robot.forward()
Parameters: - left (tuple) – A tuple of two GPIO pins representing the phase and enable inputs of the left motor’s controller.
- right (tuple) – A tuple of two GPIO pins representing the phase and enable inputs of the right motor’s controller.
- pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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.
-
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
¶ 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.
15.15. Ryanteck MCB Robot¶
-
class
gpiozero.
RyanteckRobot
(pin_factory=None)[source]¶ Extends
Robot
for the Ryanteck motor controller board.The Ryanteck MCB pins are fixed and therefore there’s no need to specify them when constructing this class. The following example drives the robot forward:
from gpiozero import RyanteckRobot robot = RyanteckRobot() robot.forward()
Parameters: pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore). -
backward
(speed=1, **kwargs)¶ 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.
- curve_left (float) – The amount to curve left while moving backwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving backwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
forward
(speed=1, **kwargs)¶ 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.
- curve_left (float) – The amount to curve left while moving forwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving forwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
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_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
¶ Represents the motion of the robot as a tuple of (left_motor_speed, right_motor_speed) with
(-1, -1)
representing full speed backwards,(1, 1)
representing full speed forwards, and(0, 0)
representing stopped.
-
values
¶ An infinite iterator of values read from value.
-
15.16. CamJam #3 Kit Robot¶
-
class
gpiozero.
CamJamKitRobot
(pin_factory=None)[source]¶ Extends
Robot
for the CamJam #3 EduKit motor controller board.The CamJam robot controller pins are fixed and therefore there’s no need to specify them when constructing this class. The following example drives the robot forward:
from gpiozero import CamJamKitRobot robot = CamJamKitRobot() robot.forward()
Parameters: pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore). -
backward
(speed=1, **kwargs)¶ 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.
- curve_left (float) – The amount to curve left while moving backwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving backwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
forward
(speed=1, **kwargs)¶ 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.
- curve_left (float) – The amount to curve left while moving forwards, by driving the
left motor at a slower speed. Maximum
curve_left
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_right
. - curve_right (float) – The amount to curve right while moving forwards, by driving the
right motor at a slower speed. Maximum
curve_right
is 1, the default is 0 (no curve). This parameter can only be specified as a keyword parameter, and is mutually exclusive withcurve_left
.
-
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_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
¶ Represents the motion of the robot as a tuple of (left_motor_speed, right_motor_speed) with
(-1, -1)
representing full speed backwards,(1, 1)
representing full speed forwards, and(0, 0)
representing stopped.
-
values
¶ An infinite iterator of values read from value.
-
15.17. Pololu DRV8835 Robot¶
-
class
gpiozero.
PololuDRV8835Robot
(pin_factory=None)[source]¶ Extends
PhaseEnableRobot
for the Pololu DRV8835 Dual Motor Driver Kit.The Pololu DRV8835 pins are fixed and therefore there’s no need to specify them when constructing this class. The following example drives the robot forward:
from gpiozero import PololuDRV8835Robot robot = PololuDRV8835Robot() robot.forward()
Parameters: pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore). -
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_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
¶ 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.
-
15.18. Energenie¶
-
class
gpiozero.
Energenie
(socket=None, initial_value=False, pin_factory=None)[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. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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 thewith
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 andFalse
otherwise. This property is usually derived fromvalue
. Unlikevalue
, 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.
15.19. StatusZero¶
-
class
gpiozero.
StatusZero
(*labels, pwm=False, active_high=True, initial_value=False, pin_factory=None)[source]¶ Extends
LEDBoard
for The Pi Hut’s STATUS Zero: a Pi Zero sized add-on board with three sets of red/green LEDs to provide a status indicator.The following example designates the first strip the label “wifi” and the second “raining”, and turns them green and red respectfully:
from gpiozero import StatusZero status = StatusZero('wifi', 'raining') status.wifi.green.on() status.raining.red.on()
Parameters: - *labels (str) – Specify the names of the labels you wish to designate the strips to. You can list up to three labels. If no labels are given, three strips will be initialised with names ‘one’, ‘two’, and ‘three’. If some, but not all strips are given labels, any remaining strips will not be initialised.
- pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
15.20. StatusBoard¶
-
class
gpiozero.
StatusBoard
(*labels, pwm=False, active_high=True, initial_value=False, pin_factory=None)[source]¶ Extends
CompositeOutputDevice
for The Pi Hut’s STATUS board: a HAT sized add-on board with five sets of red/green LEDs and buttons to provide a status indicator with additional input.The following example designates the first strip the label “wifi” and the second “raining”, turns the wifi green and then activates the button to toggle its lights when pressed:
from gpiozero import StatusBoard status = StatusBoard('wifi', 'raining') status.wifi.lights.green.on() status.wifi.button.when_pressed = status.wifi.lights.toggle
Parameters: - *labels (str) – Specify the names of the labels you wish to designate the strips to. You can list up to five labels. If no labels are given, five strips will be initialised with names ‘one’ to ‘five’. If some, but not all strips are given labels, any remaining strips will not be initialised.
- pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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_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.
15.21. SnowPi¶
-
class
gpiozero.
SnowPi
(pwm=False, initial_value=False, pin_factory=None)[source]¶ Extends
LEDBoard
for the Ryanteck SnowPi board.The SnowPi pins are fixed and therefore there’s no need to specify them when constructing this class. The following example turns on the eyes, sets the nose pulsing, and the arms blinking:
from gpiozero import SnowPi snowman = SnowPi(pwm=True) snowman.eyes.on() snowman.nose.pulse() snowman.arms.blink()
Parameters: - pwm (bool) – If
True
, constructPWMLED
instances to represent each LED. IfFalse
(the default), construct regularLED
instances. - initial_value (bool) – If
False
(the default), all LEDs will be off initially. IfNone
, each device will be left in whatever state the pin is found in when configured for output (warning: this can be on). IfTrue
, the device will be switched on initially. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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. 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 thewith
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. IfFalse
, 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 tuple of all LEDs contained in this collection (and all sub-collections).
-
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.
- pwm (bool) – If
15.22. 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:
For composite devices, the following chart shows which devices are composed of which other devices:
The following sections document these base classes for advanced users that wish to construct classes for their own devices.
15.23. LEDCollection¶
-
class
gpiozero.
LEDCollection
(*pins, pwm=False, active_high=True, initial_value=False, pin_factory=None, **named_pins)[source]¶ Extends
CompositeOutputDevice
. Abstract base class forLEDBoard
andLEDBarGraph
.-
leds
¶ A flat tuple of all LEDs contained in this collection (and all sub-collections).
-
15.24. CompositeOutputDevice¶
-
class
gpiozero.
CompositeOutputDevice
(*args, _order=None, pin_factory=None, **kwargs)[source]¶ Extends
CompositeDevice
withon()
,off()
, andtoggle()
methods for controlling subordinate output devices. Also extendsvalue
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. - pin_factory (Factory) – See API - Pins for more information (this is an advanced feature which most users can ignore).
-
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.
- _order (list) – If specified, this is the order of named items specified by keyword
arguments (to ensure that the
15.25. CompositeDevice¶
-
class
gpiozero.
CompositeDevice
(*args, _order=None, pin_factory=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 thewith
statement. For example:>>> from gpiozero import * >>> with Buzzer(16) as bz: ... bz.on() ... >>> with LED(16) as led: ... led.on() ...
-