These output device component interfaces have been provided for simple use of everyday components. Components must be wired up correctly before use in code.
Note
All GPIO pin numbers use Broadcom (BCM) numbering. See the Recipes page for more information.
Extends DigitalOutputDevice and represents a light emitting diode (LED).
Connect the cathode (short leg, flat side) of the LED to a ground pin; connect the anode (longer leg) to a limiting resistor; connect the other side of the limiting resistor to a GPIO pin (the limiting resistor can be placed either side of the LED).
The following example will light the LED:
from gpiozero import LED
led = LED(17)
led.on()
Parameters: |
|
---|
Turns the device on.
Turns the device off.
Reverse the state of the device. If it’s on, turn it off; if it’s off, turn it on.
Make the device turn on and off repeatedly.
Parameters: |
|
---|
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. This property is usually derived from value. Unlike value, this is always a boolean.
Extends PWMOutputDevice and represents a light emitting diode (LED) with variable brightness.
A typical configuration of such a device is to connect a GPIO pin to the anode (long leg) of the LED, and the cathode (short leg) to ground, with an optional resistor to prevent the LED from burning out.
Parameters: |
|
---|
Turns the device on.
Turns the device off.
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.
Make the device turn on and off repeatedly.
Parameters: |
|
---|
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.
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.
Extends Device and represents a full color LED component (composed of red, green, and blue LEDs).
Connect the common cathode (longest leg) to a ground pin; connect each of the other legs (representing the red, green, and blue anodes) to any GPIO pins. You can either use three limiting resistors (one per anode) or a single limiting resistor on the cathode.
The following code will make the LED purple:
from gpiozero import RGBLED
led = RGBLED(2, 3, 4)
led.color = (1, 0, 1)
Parameters: |
|
---|
Turn the LED on. This equivalent to setting the LED color to white (1, 1, 1).
Turn the LED off. This is equivalent to setting the LED color to black (0, 0, 0).
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.
Make the device turn on and off repeatedly.
Parameters: |
|
---|
Returns True if the LED is currently active (not black) and False otherwise.
Represents the color of the LED as an RGB 3-tuple of (red, green, blue) where each value is between 0 and 1.
For example, purple would be (1, 0, 1) and yellow would be (1, 1, 0), while orange would be (1, 0.5, 0).
Extends DigitalOutputDevice and represents a digital buzzer component.
Connect the cathode (negative pin) of the buzzer to a ground pin; connect the other side to any GPIO pin.
The following example will sound the buzzer:
from gpiozero import Buzzer
bz = Buzzer(3)
bz.on()
Parameters: |
|
---|
Turns the device on.
Turns the device off.
Reverse the state of the device. If it’s on, turn it off; if it’s off, turn it on.
Make the device turn on and off repeatedly.
Parameters: |
|
---|
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. This property is usually derived from value. Unlike value, this is always a boolean.
Extends CompositeDevice and represents a generic motor connected to a bi-directional motor driver circuit (i.e. an H-bridge).
Attach an H-bridge motor controller to your Pi; connect a power source (e.g. a battery pack or the 5V pin) to the controller; connect the outputs of the controller board to the two terminals of the motor; connect the inputs of the controller board to two GPIO pins.
The following code will make the motor turn “forwards”:
from gpiozero import Motor
motor = Motor(17, 18)
motor.forward()
Parameters: |
---|
Drive the motor forwards.
Parameters: | speed (float) – The speed at which the motor should turn. Can be any value between 0 (stopped) and the default 1 (maximum speed). |
---|
Drive the motor backwards.
Parameters: | speed (float) – The speed at which the motor should turn. Can be any value between 0 (stopped) and the default 1 (maximum speed). |
---|
Stop the motor.
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:
The following sections document these base classes for advanced users that wish to construct classes for their own devices.
Represents a generic output device with typical on/off behaviour.
This class extends OutputDevice with 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 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 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.
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 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 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.
Make the device fade in and out repeatedly.
Parameters: |
|
---|
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 GPIO output device.
This class extends GPIODevice to add facilities common to GPIO output devices: an on() method to switch the device on, a corresponding off() method, and a toggle() method.
Parameters: |
|
---|
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.
When True, the value property is True when the device’s pin is high. When False the value property is True when the device’s pin is low (i.e. the value is inverted).
This property can be set after construction; be warned that changing it will invert value (i.e. changing this property doesn’t change the device’s pin state - it just changes how that state is interpreted).
Returns True if the device is currently active and False otherwise. Setting this property changes the state of the device.
Extends Device. Represents a generic GPIO device and provides the services common to all single-pin GPIO devices (like ensuring two GPIO devices do no share a pin).
Parameters: | pin (int) – The GPIO pin (in BCM numbering) that the device is connected to. If this is None, GPIOPinMissing will be raised. If the pin is already in use by another device, GPIOPinInUse will be raised. |
---|
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 the with statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
... bz.on()
...
>>> with LED(16) as led:
... led.on()
...
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.