The GPIO Zero class hierarchy is quite extensive. It contains a couple of base classes:
There are also a couple of mixin 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:
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 the close method).
Parameters: | pin (int) – The GPIO pin (in BCM numbering) that the device is connected to. If this is None a GPIODeviceError will be raised. |
---|
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 the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...
Returns True if the device is currently active and False otherwise.
The Pin that the device is connected to. This will be None if the device has been closed (see the close() method). When dealing with GPIO pins, query pin.number to discover the GPIO pin (in BCM numbering) that the device is connected to.
Returns True if the device is currently active and False otherwise.
An infinite iterator of values read from value.
Represents a device composed of multiple GPIO devices like simple HATs, H-bridge motor controllers, robots composed of multiple motors, etc.
Shut down the device and release all associated resources.
Returns True if the device is closed (see the close() method). Once a device is closed you can no longer use any other methods or properties to control or query the device.
An infinite iterator of values read from value.
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. The is_active property is adjusted accordingly so that True still means active regardless of the pull_up setting.
Parameters: |
---|
If True, the device uses a pull-up resistor to set the GPIO pin “high” by default. Defaults to False.
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() and wait_for_inactive()), and properties that hold functions to be called when the device changes state (when_activated() and when_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.
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. |
---|
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. |
---|
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.
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.
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. |
---|
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 the is_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: |
|
---|
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 the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...
Returns True if the device is currently active and False otherwise.
If False (the default), attempts to read the value or is_active properties will block until the queue has filled.
The length of the internal queue of values which is averaged to determine the overall state of the device. This defaults to 5.
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, and MCP3208.
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 a PWMLED like so:
from gpiozero import MCP3008, PWMLED
pot = MCP3008(0)
led = PWMLED(17)
led.source = pot.values
Shut down the device and release all associated resources.
The bit-resolution of the device/channel.
The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.
The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.
The raw value as read from the device.
The current value read from the device, scaled to a value between 0 and 1.
Represents a generic GPIO output device.
This class extends GPIODevice to add facilities common to GPIO output devices: an on() method to switch the device on, and a corresponding off() method.
Parameters: |
|
---|
Turns the device off.
Turns the device on.
Generic output device configured for pulse-width modulation (PWM).
Parameters: |
|
---|
Make the device turn on and off repeatedly.
Parameters: |
|
---|
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 the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...
Turns the device off.
Turns the device on.
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.
The frequency of the pulses used with the PWM device, in Hz. The default is 100Hz.
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.
Represents a generic output device with typical on/off behaviour.
This class extends OutputDevice with a toggle() method to switch the device between its on and off states, and a blink() method which uses an optional background thread to handle toggling the device state without further interaction.
Make the device turn on and off repeatedly.
Parameters: |
|
---|
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 the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...
Turns the device off.
Turns the device on.
Reverse the state of the device. If it’s on, turn it off; if it’s off, turn it on.