Buzzer(pin, *, active_high=True, initial_value=False, pin_factory=None)
Note : This interface is only capable of simple on/off commands, and is not capable of playing a variety of tones (see TonalBuzzer).
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 or str) – The GPIO pin which the buzzer is connected to. See Pin Numbering 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 or None) – 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.
pin_factory (Factory or None) – Advanced users.
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 or None) – 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).
off() Turns the device off.
on() Turns the device on.
toggle() Reverse the state of the device. If it’s on, turn it off; if it’s off, turn it on.
is_active 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.
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.
value Returns 1 if the device is currently active and 0 otherwise. Setting this property changes the state of the device.
#Buzzer should go on and off 10 times
from gpiozero import Buzzer
bz = Buzzer(3,active_high=True, initial_value=False)
bz.beep(on_time=1, off_time=1, n=10)
#Buzzr should go on and off
from gpiozero import Buzzer
bz = Buzzer(3,active_high=True, initial_value=False)
bz.on()
bz.toggle()
bz.off()
bz.toggle()
#Buzzr miscellenous
from gpiozero import Buzzer
bz = Buzzer(3,active_high=True, initial_value=False)
print("Is buzzer on ?",bz.is_active)
print("Where is it connected ?, bz.pin)
print("Current value", bz.value)
#Buzzr should go on and off
from gpiozero import Buzzer
bz = Buzzer(3,active_high=True, initial_value=False)
bz.value=1
bz.value=0
TonalBuzzer(pin, *, initial_value=None, mid_tone=Tone('A4'), octaves=1, pin_factory=None)
Extends CompositeDevice and represents a tonal buzzer.
Parameters:
pin (int or str) – The GPIO pin which the buzzer is connected to. See Pin Numbering for valid pin numbers.
initial_value (float) – If None (the default), the buzzer will be off initially. Values between -1 and 1 can be specified as an initial value for the buzzer.
mid_tone (int or str) – The tone which is represented the device’s middle value (0). The default is “A4” (MIDI note 69).
octaves (int) – The number of octaves to allow away from the base note. The default is 1, meaning a value of -1 goes one octave below the base note, and one above, i.e. from A3 to A5 with the default base note of A4.
pin_factory (Factory or None) – For advanced users
play(tone) Play the given tone. This can either be an instance of Tone or can be anything that could be used to construct an instance of Tone.
For example:
>>> from gpiozero import TonalBuzzer
>>> from gpiozero.tones import Tone
>>> b = TonalBuzzer(17)
>>> b.play(Tone("A4"))
>>> b.play(Tone(220.0)) # Hz
>>> b.play(Tone(60)) # middle C in MIDI notation
>>> b.play("A4")
>>> b.play(220.0)
>>> b.play(60)
stop() Turn the buzzer off. This is equivalent to setting value to None.
is_active Returns True if the buzzer is currently playing, otherwise False.
max_tone The highest tone that the buzzer can play, i.e. the tone played when value is 1.
mid_tone The middle tone available, i.e. the tone played when value is 0.
min_tone The lowest tone that the buzzer can play, i.e. the tone played when value is -1.
octaves The number of octaves available (above and below mid_tone).
tone Returns the Tone that the buzzer is currently playing, or None if the buzzer is silent. This property can also be set to play the specified tone.
value Represents the state of the buzzer as a value between -1 (representing the minimum tone) and 1 (representing the maximum tone). This can also be the special value None indicating that the buzzer is currently silent.
#Set buzzer values
from gpiozero import TonalBuzzer
from gpiozero.tones import Tone
buzz = TonalBuzzer(17,initial_value=None, mid_tone=Tone('A4'), octaves=1)
buzz.value=1
buzz.value=-1
buzz.value=0
#Set buzzer values
from gpiozero import TonalBuzzer
from gpiozero.tones import Tone
buzz = TonalBuzzer(17,initial_value=None, mid_tone=Tone('A4'), octaves=1)
print("Buzzer tone is",buzz.tone())
#Set buzzer values
from gpiozero import TonalBuzzer
from gpiozero.tones import Tone
buzz = TonalBuzzer(17,initial_value=None, mid_tone=Tone('A4'), octaves=1)
buzz.max_tone
buzz.min_tone
buzz.mid_tone
buzz.octave
buzz.is_active
buzz.stop()
Motor(forward, backward, *, pwm=True, pin_factory=None)
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 or str) – The GPIO pin that the forward input of the motor driver chip is connected to.
backward (int or str) – The GPIO pin that the backward input of the motor driver chip is connected to.
enable (int or str or None) – The GPIO pin that enables the motor. Required for some motor controller boards.
pwm (bool) – If True (the default), construct PWMOutputDevice instances for the motor controller pins, allowing both direction and variable speed control. If False, construct DigitalOutputDevice instances, allowing only direction control.
pin_factory (Factory or None) – Advanced users
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) if pwm was True when the class was constructed (and only 0 or 1 if not).
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) if pwm was True when the class was constructed (and only 0 or 1 if not).
reverse() Reverse the current direction of the motor. If the motor is currently idle this does nothing. Otherwise, the motor’s direction will be reversed at the current speed.
stop() Stop the motor.
is_active Returns True if the motor is currently running and False otherwise.
value Represents the speed of the motor as a floating point value between -1 (full speed backward) and 1 (full speed forward), with 0 representing stopped.
from gpiozero import Motor
motor = Motor(17, 18)
motor.backward()
from gpiozero import Motor
motor = Motor(17, 18)
motor.reverse()
from gpiozero import Motor
motor = Motor(17, 18)
motor.is_active
from gpiozero import Motor
motor = Motor(17, 18)
motor.value = 1
from gpiozero import Motor
motor = Motor(17, 18)
motor.value = -1
from gpiozero import Motor
motor = Motor(17, 18)
print("speed of motor",motor.value)
from gpiozero import Motor
motor = Motor(17, 18)
motor.forward()
motor.stop()
PhaseEnableMotor(phase, enable, *, pwm=True, pin_factory=None)
Extends CompositeDevice and represents a generic motor connected to a Phase/Enable motor driver circuit; the phase of the driver controls whether the motor turns forwards or backwards, while enable controls the speed with PWM.
The following code will make the motor turn “forwards”:
from gpiozero import PhaseEnableMotor
motor = PhaseEnableMotor(12, 5)
motor.forward()
Parameters:
phase (int or str) – The GPIO pin that the phase (direction) input of the motor driver chip is connected to.
enable (int or str) – The GPIO pin that the enable (speed) input of the motor driver chip is connected to.
pwm (bool) – If True (the default), allowing both direction and variable speed control. If False, allowing only direction control.
pin_factory (Factory or None) – Advanced users
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).
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).
reverse() Reverse the current direction of the motor. If the motor is currently idle this does nothing. Otherwise, the motor’s direction will be reversed at the current speed.
stop() Stop the motor.
is_active Returns True if the motor is currently running and False otherwise.
value Represents the speed of the motor as a floating point value between -1 (full speed backward) and 1 (full speed forward).
Servo(pin, *, initial_value=0, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None)
Extends CompositeDevice and represents a PWM-controlled servo motor connected to a GPIO pin.
Connect a power source (e.g. a battery pack or the 5V pin) to the power cable of the servo (this is typically colored red); connect the ground cable of the servo (typically colored black or brown) to the negative of your battery pack, or a GND pin; connect the final cable (typically colored white or orange) to the GPIO pin you wish to use for controlling the servo.
The following code will make the servo move between its minimum, maximum, and mid-point positions with a pause between each:
from gpiozero import Servo
from time import sleep
servo = Servo(17)
while True:
servo.min()
sleep(1)
servo.mid()
sleep(1)
servo.max()
sleep(1)
You can also use the value property to move the servo to a particular position, on a scale from -1 (min) to 1 (max) where 0 is the mid-point:
from gpiozero import Servo
servo = Servo(17)
servo.value = 0.5
Parameters:
pin (int or str) – The GPIO pin that the servo is connected to. See Pin Numbering for valid pin numbers. If this is None a GPIODeviceError will be raised.
initial_value (float) – If 0 (the default), the device’s mid-point will be set initially. Other values between -1 and +1 can be specified as an initial position. None means to start the servo un-controlled (see value).
min_pulse_width (float) – The pulse width corresponding to the servo’s minimum position. This defaults to 1ms.
max_pulse_width (float) – The pulse width corresponding to the servo’s maximum position. This defaults to 2ms.
frame_width (float) – The length of time between servo control pulses measured in seconds. This defaults to 20ms which is a common value for servos.
pin_factory (Factory or None) – Advanced users.
detach() Temporarily disable control of the servo. This is equivalent to setting value to None.
max() Set the servo to its maximum position.
mid() Set the servo to its mid-point position.
min() Set the servo to its minimum position.
frame_width The time between control pulses, measured in seconds.
is_active Composite devices are considered “active” if any of their constituent devices have a “truthy” value.
max_pulse_width The control pulse width corresponding to the servo’s maximum position, measured in seconds.
min_pulse_width The control pulse width corresponding to the servo’s minimum position, measured in seconds.
pulse_width Returns the current pulse width controlling the servo.
value Represents the position of the servo as a value between -1 (the minimum position) and +1 (the maximum position). This can also be the special value None indicating that the servo is currently “uncontrolled”, i.e. that no control signal is being sent. Typically this means the servo’s position remains unchanged, but that it can be moved by hand.
AngularServo(pin, *, initial_angle=0, min_angle=-90, max_angle=90, min_pulse_width=1/1000, max_pulse_width=2/1000, frame_width=20/1000, pin_factory=None)
Extends Servo and represents a rotational PWM-controlled servo motor which can be set to particular angles (assuming valid minimum and maximum angles are provided to the constructor).
Connect a power source (e.g. a battery pack or the 5V pin) to the power cable of the servo (this is typically colored red); connect the ground cable of the servo (typically colored black or brown) to the negative of your battery pack, or a GND pin; connect the final cable (typically colored white or orange) to the GPIO pin you wish to use for controlling the servo.
Next, calibrate the angles that the servo can rotate to. In an interactive Python session, construct a Servo instance. The servo should move to its mid-point by default. Set the servo to its minimum value, and measure the angle from the mid-point. Set the servo to its maximum value, and again measure the angle:
>>> from gpiozero import Servo
>>> s = Servo(17)
>>> s.min() # measure the angle
>>> s.max() # measure the angle
You should now be able to construct an AngularServo instance with the correct bounds:
>>> from gpiozero import AngularServo
>>> s = AngularServo(17, min_angle=-42, max_angle=44)
>>> s.angle = 0.0
>>> s.angle
0.0
>>> s.angle = 15
>>> s.angle
15.0
Note You can set min_angle greater than max_angle if you wish to reverse the sense of the angles (e.g. min_angle=45, max_angle=-45). This can be useful with servos that rotate in the opposite direction to your expectations of minimum and maximum.
Parameters:
pin (int or str) – The GPIO pin that the servo is connected to. See Pin Numbering for valid pin numbers. If this is None a GPIODeviceError will be raised.
initial_angle (float) – Sets the servo’s initial angle to the specified value. The default is 0. The value specified must be between min_angle and max_angle inclusive. None means to start the servo un-controlled (see value).
min_angle (float) – Sets the minimum angle that the servo can rotate to. This defaults to -90, but should be set to whatever you measure from your servo during calibration.
max_angle (float) – Sets the maximum angle that the servo can rotate to. This defaults to 90, but should be set to whatever you measure from your servo during calibration.
min_pulse_width (float) – The pulse width corresponding to the servo’s minimum position. This defaults to 1ms.
max_pulse_width (float) – The pulse width corresponding to the servo’s maximum position. This defaults to 2ms.
frame_width (float) – The length of time between servo control pulses measured in seconds. This defaults to 20ms which is a common value for servos.
pin_factory (Factory or None) – Advanced users
max() Set the servo to its maximum position.
mid() Set the servo to its mid-point position.
min() Set the servo to its minimum position.
angle The position of the servo as an angle measured in degrees. This will only be accurate if min_angle and max_angle have been set appropriately in the constructor.
This can also be the special value None indicating that the servo is currently “uncontrolled”, i.e. that no control signal is being sent. Typically this means the servo’s position remains unchanged, but that it can be moved by hand.
is_active Composite devices are considered “active” if any of their constituent devices have a “truthy” value.
max_angle The maximum angle that the servo will rotate to when max() is called.
min_angle The minimum angle that the servo will rotate to when min() is called.
value Represents the position of the servo as a value between -1 (the minimum position) and +1 (the maximum position). This can also be the special value None indicating that the servo is currently “uncontrolled”, i.e. that no control signal is being sent. Typically this means the servo’s position remains unchanged, but that it can be moved by hand.