Generic Devices¶
The GPIO Zero class hierarchy is quite extensive. It contains a couple of base classes:
GPIODevice
for individual devices that attach to a single GPIO pinCompositeDevice
for devices composed of multiple other devices like HATs
There are also a couple of mixin classes:
ValuesMixin
which defines thevalues
properties; there is rarely a need to use this as the base classes mentioned above both include it (so all classes in GPIO Zero include thevalues
property)SourceMixin
which defines thesource
property; this is generally included in novel output device classes
The current class hierarchies are displayed below. For brevity, the mixin classes are omitted:
Finally, for composite devices, the following chart shows which devices are composed of which other devices:
Base Classes¶
-
class
gpiozero.
GPIODevice
(pin)[source]¶ Represents a generic GPIO device.
This is the class at the root of the gpiozero class hierarchy. It handles ensuring that two GPIO devices do not share the same pin, and provides basic services applicable to all devices (specifically the
pin
property,is_active
property, and theclose
method).Parameters: pin (int) – The GPIO pin (in BCM numbering) that the device is connected to. If this is None
aGPIODeviceError
will be raised.-
close
()[source]¶ Shut down the device and release all associated resources.
This method is primarily intended for interactive use at the command line. It disables the device and releases its pin 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()
GPIODevice
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.
-
pin
¶ The
Pin
that the device is connected to. This will beNone
if the device has been closed (see theclose()
method). When dealing with GPIO pins, querypin.number
to discover the GPIO pin (in BCM numbering) that the device is connected to.
-
value
¶ Returns
True
if the device is currently active andFalse
otherwise.
-
values
¶ An infinite iterator of values read from value.
-
-
class
gpiozero.
CompositeDevice
[source]¶ Represents a device composed of multiple GPIO devices like simple HATs, H-bridge motor controllers, robots composed of multiple motors, etc.
-
close
()¶ Shut down the device and release all associated resources.
-
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.
-
values
¶ An infinite iterator of values read from value.
-
Input Devices¶
-
class
gpiozero.
InputDevice
(pin, pull_up=False)[source]¶ Represents a generic GPIO input device.
This class extends
GPIODevice
to add facilities common to GPIO input devices. The constructor adds the optional pull_up parameter to specify how the pin should be pulled by the internal resistors. Theis_active
property is adjusted accordingly so thatTrue
still means active regardless of thepull_up
setting.Parameters: -
pull_up
¶ If
True
, the device uses a pull-up resistor to set the GPIO pin “high” by default. Defaults toFalse
.
-
-
class
gpiozero.
WaitableInputDevice
(pin=None, pull_up=False)[source]¶ Represents a generic input device with distinct waitable states.
This class extends
InputDevice
with methods for waiting on the device’s status (wait_for_active()
andwait_for_inactive()
), and properties that hold functions to be called when the device changes state (when_activated()
andwhen_deactivated()
). These are aliased appropriately in various subclasses.Note that this class provides no means of actually firing its events; it’s effectively an abstract base class.
-
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.
-
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.
-
-
class
gpiozero.
DigitalInputDevice
(pin, pull_up=False, bounce_time=None)[source]¶ Represents a generic input device with typical on/off behaviour.
This class extends
WaitableInputDevice
with machinery to fire the active and inactive events for devices that operate in a typical digital manner: straight forward on / off states with (reasonably) clean transitions between the two.Parameters: bouncetime (float) – Specifies the length of time (in seconds) that the component will ignore changes in state after an initial change. This defaults to None
which indicates that no bounce compensation will be performed.
-
class
gpiozero.
SmoothedInputDevice
(pin=None, pull_up=False, threshold=0.5, queue_len=5, sample_wait=0.0, partial=False)[source]¶ Represents a generic input device which takes its value from the mean of a queue of historical values.
This class extends
WaitableInputDevice
with a queue which is filled by a background thread which continually polls the state of the underlying device. The mean of the values in the queue is compared to a threshold which is used to determine the state of theis_active
property.This class is intended for use with devices which either exhibit analog behaviour (such as the charging time of a capacitor with an LDR), or those which exhibit “twitchy” behaviour (such as certain motion sensors).
Parameters: - threshold (float) – The value above which the device will be considered “on”.
- queue_len (int) – The length of the internal queue which is filled by the background thread.
- sample_wait (float) – The length of time to wait between retrieving the state of the underlying device. Defaults to 0.0 indicating that values are retrieved as fast as possible.
- partial (bool) – If
False
(the default), attempts to read the state of the device (from theis_active
property) will block until the queue has filled. IfTrue
, a value will be returned immediately, but be aware that this value is likely to fluctuate excessively.
-
close
()[source]¶ Shut down the device and release all associated resources.
This method is primarily intended for interactive use at the command line. It disables the device and releases its pin 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()
GPIODevice
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.
-
partial
¶ If
False
(the default), attempts to read thevalue
oris_active
properties will block until the queue has filled.
-
queue_len
¶ The length of the internal queue of values which is averaged to determine the overall state of the device. This defaults to 5.
-
class
gpiozero.
AnalogInputDevice
(device=0, bits=None)[source]¶ Represents an analog input device connected to SPI (serial interface).
Typical analog input devices are analog to digital converters (ADCs). Several classes are provided for specific ADC chips, including
MCP3004
,MCP3008
,MCP3204
, andMCP3208
.The following code demonstrates reading the first channel of an MCP3008 chip attached to the Pi’s SPI pins:
from gpiozero import MCP3008 pot = MCP3008(0) print(pot.value)
The
value
attribute is normalized such that its value is always between 0.0 and 1.0 (or in special cases, such as differential sampling, -1 to +1). Hence, you can use an analog input to control the brightness of aPWMLED
like so:from gpiozero import MCP3008, PWMLED pot = MCP3008(0) led = PWMLED(17) led.source = pot.values
-
bits
¶ The bit-resolution of the device/channel.
-
bus
¶ The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.
-
device
¶ The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.
-
raw_value
¶ The raw value as read from the device.
-
value
¶ The current value read from the device, scaled to a value between 0 and 1.
-
Output Devices¶
-
class
gpiozero.
OutputDevice
(pin, active_high=True, initial_value=False)[source]¶ Represents a generic GPIO output device.
This class extends
GPIODevice
to add facilities common to GPIO output devices: anon()
method to switch the device on, and a correspondingoff()
method.Parameters: - pin (int) – The GPIO pin (in BCM numbering) that the device is connected to. If
this is
None
aGPIODeviceError
will be raised. - active_high (bool) – If
True
(the default), theon()
method will set the GPIO to HIGH. IfFalse
, theon()
method will set the GPIO to LOW (theoff()
method always does the opposite). - initial_value (bool) – If
False
(the default), the device will be off initially. IfNone
, the 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 (int) – The GPIO pin (in BCM numbering) that the device is connected to. If
this is
-
class
gpiozero.
PWMOutputDevice
(pin, active_high=True, initial_value=0, frequency=100)[source]¶ Generic output device configured for pulse-width modulation (PWM).
Parameters: - pin (int) – The GPIO pin which the device is attached to. See Notes for valid pin numbers.
- active_high (bool) – If
True
(the default), theon()
method will set the GPIO to HIGH. IfFalse
, theon()
method will set the GPIO to LOW (theoff()
method always does the opposite). - initial_value (bool) – If
0
(the default), the device’s duty cycle will be 0 initially. Other values between 0 and 1 can be specified as an initial duty cycle. Note thatNone
cannot be specified (unlike the parent class) as there is no way to tell PWM not to alter the state of the pin. - frequency (int) – The frequency (in Hz) of pulses emitted to drive the device. Defaults to 100Hz.
-
blink
(on_time=1, off_time=1, fade_in_time=0, fade_out_time=0, n=None, background=True)[source]¶ 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.
- fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0.
- 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
()[source]¶ Shut down the device and release all associated resources.
This method is primarily intended for interactive use at the command line. It disables the device and releases its pin 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()
GPIODevice
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() ...
-
toggle
()[source]¶ Toggle the state of the device. If the device is currently off (
value
is 0.0), this changes it to “fully” on (value
is 1.0). If the device has a duty cycle (value
) of 0.1, this will toggle it to 0.9, and so on.
-
frequency
¶ The frequency of the pulses used with the PWM device, in Hz. The default is 100Hz.
-
value
¶ The duty cycle of the PWM device. 0.0 is off, 1.0 is fully on. Values in between may be specified for varying levels of power in the device.
-
class
gpiozero.
DigitalOutputDevice
(pin, active_high=True, initial_value=False)[source]¶ Represents a generic output device with typical on/off behaviour.
This class extends
OutputDevice
with atoggle()
method to switch the device between its on and off states, and ablink()
method which uses an optional background thread to handle toggling the device state without further interaction.-
blink
(on_time=1, off_time=1, n=None, background=True)[source]¶ 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.
- 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
()[source]¶ Shut down the device and release all associated resources.
This method is primarily intended for interactive use at the command line. It disables the device and releases its pin 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()
GPIODevice
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() ...
-