Output Devices
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.
LED
-
class gpiozero.LED(pin, active_high=True, initial_value=False)
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: |
- pin (int) – The GPIO pin which the LED is attached to. See Notes for valid
pin numbers.
- active_high (bool) – If True (the default), the LED will operate normally with the
circuit described above. If False you should wire the cathode to
the GPIO pin, and the anode to a 3V3 pin (via a limiting resistor).
- initial_value (bool) – If False (the default), the LED will be off initially. If
None, the LED will be left in whatever state the pin is found in
when configured for output (warning: this can be on). If True, the
LED will be switched on initially.
|
-
on()
Turns the device on.
-
off()
Turns the device off.
-
toggle()
Reverse the state of the device. If it’s on, turn it off; if it’s off,
turn it on.
-
blink(on_time=1, off_time=1, 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.
- 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. If False, only return when the
blink is finished (warning: the default value of n will result in
this method never returning).
|
-
pin
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.
-
is_lit
Returns True if the device is currently active and False
otherwise.
PWMLED
-
class gpiozero.PWMLED(pin, active_high=True, initial_value=0, frequency=100)
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: |
- pin (int) – The GPIO pin which the LED is attached to. See Notes for
valid pin numbers.
- active_high (bool) – If True (the default), the on() method will set the GPIO to
HIGH. If False, the on() method will set the GPIO to LOW (the
off() method always does the opposite).
- initial_value (bool) – If 0 (the default), the LED will be off initially. Other values
between 0 and 1 can be specified as an initial brightness for the LED.
Note that None 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 LED. Defaults
to 100Hz.
|
-
on()
Turns the device on.
-
off()
Turns the device off.
-
toggle()
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.
-
blink(on_time=1, off_time=1, fade_in_time=0, fade_out_time=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.
- 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. If False, only return when the
blink is finished (warning: the default value of n will result in
this method never returning).
|
-
pin
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.
-
is_lit
Returns True if the device is currently active (value is
non-zero) and False otherwise.
-
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.
RGBLED
-
class gpiozero.RGBLED(red, green, blue, active_high=True, initial_value=(0, 0, 0))
Extends CompositeDevice 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: |
- red (int) – The GPIO pin that controls the red component of the RGB LED.
- green (int) – The GPIO pin that controls the green component of the RGB LED.
- blue (int) – The GPIO pin that controls the blue component of the RGB LED.
- active_high (bool) – Set to True (the default) for common cathode RGB LEDs. If you are
using a common anode RGB LED, set this to False.
- initial_value (bool) – The initial color for the LED. Defaults to black (0, 0, 0).
|
-
on()
Turn the LED on. This equivalent to setting the LED color to white
(1, 1, 1).
-
off()
Turn the LED off. This is equivalent to setting the LED color to black
(0, 0, 0).
-
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.
-
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.
- fade_out_time (float) – Number of seconds to spend fading out. Defaults to 0.
- 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. If False, only return when the
blink is finished (warning: the default value of n will result in
this method never returning).
|
-
is_lit
Returns True if the LED is currently active (not black) and
False otherwise.
-
color
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).
Buzzer
-
class gpiozero.Buzzer(pin, active_high=True, initial_value=False)
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: |
- pin (int) – The GPIO pin which the buzzer is attached to. See Notes for
valid pin numbers.
- active_high (bool) – If True (the default), the buzzer will operate normally with the
circuit described above. If False you should wire the cathode to
the GPIO pin, and the anode to a 3V3 pin.
- initial_value (bool) – If False (the default), the buzzer will be silent initially. If
None, the buzzer will be left in whatever state the pin is found in
when configured for output (warning: this can be on). If True, the
buzzer will be switched on initially.
|
-
on()
Turns the device on.
-
off()
Turns the device off.
-
toggle()
Reverse the state of the device. If it’s on, turn it off; if it’s off,
turn it on.
-
beep(on_time=1, off_time=1, 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.
- 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. If False, only return when the
blink is finished (warning: the default value of n will result in
this method never returning).
|
-
pin
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.
-
is_active
Returns True if the device is currently active and False
otherwise.
Motor
-
class gpiozero.Motor(forward, backward)
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: |
- forward (int) – The GPIO pin that the forward input of the motor driver chip is
connected to.
- backward (int) – The GPIO pin that the backward input of the motor driver chip is
connected to.
|
-
forward(speed=1)
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). |
-
backward(speed=1)
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()
Stop the motor.