Generic Classes¶
The GPIO Zero class hierarchy is quite extensive. It contains several base classes (most of which are documented in their corresponding chapters):
Device
is the root of the hierarchy, implementing base functionality likeclose()
and context manager handlers.GPIODevice
represents individual devices that attach to a single GPIO pinSPIDevice
represents devices that communicate over an SPI interface (implemented as four GPIO pins)InternalDevice
represents devices that are entirely internal to the Pi (usually operating system related services)CompositeDevice
represents devices composed of multiple other devices like HATs
There are also several mixin classes for adding important functionality at numerous points in the hierarchy, which is illustrated below:
Device¶
-
class
gpiozero.
Device
[source]¶ Represents a single device of any type; GPIO-based, SPI-based, I2C-based, etc. This is the base class of the device hierarchy. It defines the basic services applicable to all devices (specifically thhe
is_active
property, thevalue
property, and theclose()
method).-
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() ...
-
closed
¶ Returns
True
if the device is closed (see theclose()
method). Once a device is closed you can no longer use any other methods or properties to control or query the device.
-
is_active
¶ Returns
True
if the device is currently active andFalse
otherwise. This property is usually derived fromvalue
. Unlikevalue
, this is always a boolean.
-
value
¶ Returns a value representing the device’s state. Frequently, this is a boolean value, or a number between 0 and 1 but some devices use larger ranges (e.g. -1 to +1) and composite devices usually use tuples to return the states of all their subordinate components.
-
ValuesMixin¶
-
class
gpiozero.
ValuesMixin
(...)[source]¶ Adds a
values
property to the class which returns an infinite generator of readings from thevalue
property. There is rarely a need to use this mixin directly as all base classes in GPIO Zero include it.Note
Use this mixin first in the parent class list.
-
values
¶ An infinite iterator of values read from value.
-
SourceMixin¶
-
class
gpiozero.
SourceMixin
(...)[source]¶ Adds a
source
property to the class which, given an iterable, setsvalue
to each member of that iterable until it is exhausted. This mixin is generally included in novel output devices to allow their state to be driven from another device.Note
Use this mixin first in the parent class list.
-
source
¶ The iterable to use as a source of values for
value
.
-
EventsMixin¶
-
class
gpiozero.
EventsMixin
(...)[source]¶ Adds edge-detected
when_activated()
andwhen_deactivated()
events to a device based on changes to theis_active
property common to all devices. Also addswait_for_active()
andwait_for_inactive()
methods for level-waiting.Note
Note that this mixin provides no means of actually firing its events; call
_fire_events()
in sub-classes when device state changes to trigger the events. This should also be called once at the end of initialization to set initial states.-
wait_for_active
(timeout=None)[source]¶ 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)[source]¶ 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
.
-
inactive_time
¶ The length of time (in seconds) that the device has been inactive for. When the device is active, this is
None
.
-
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.
-
HoldMixin¶
-
class
gpiozero.
HoldMixin
(...)[source]¶ Extends
EventsMixin
to add thewhen_held
event and the machinery to fire that event repeatedly (whenhold_repeat
isTrue
) at internals defined byhold_time
.-
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
.
-
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.
-