picozero API
LED
- picozero.LED(pin, pwm=True, active_high=True, initial_value=False)[source]
Returns an instance of
DigitalLED
orPWMLED
depending on the value of the pwm parameter.from picozero import LED my_pwm_led = LED(1) my_digital_led = LED(2, pwm=False)
- Parameters
pin (int) – The pin that the device is connected to.
pin – If pwm is
True
(the default), aPWMLED
will be returned. If pwm isFalse
, aDigitalLED
will be returned. APWMLED
can control the brightness of the LED but uses 1 PWM channel.active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the device will be off initially. IfTrue
, the device will be switched on initially.
DigitalLED
- class picozero.DigitalLED(pin, active_high=True, initial_value=False)[source]
Bases:
DigitalOutputDevice
Represents a simple LED, which can be switched on and off.
- Parameters
pin (int) – The pin that the device is connected to.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the LED will be off initially. IfTrue
, the LED will be switched on initially.
- blink(on_time=1, off_time=None, n=None, wait=False)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None is specified, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the device stops turning on and off. If False, the method will return and the device will turn on and off in the background. Defaults to False.
- close()
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property is_active
Returns
True
if the device is on.
- property is_lit
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
PWMLED
- class picozero.PWMLED(pin, freq=100, duty_factor=65535, active_high=True, initial_value=False)[source]
Bases:
PWMOutputDevice
Represents an LED driven by a PWM pin; the brightness of the LED can be changed.
- Parameters
pin (int) – The pin that the device is connected to.
freq (int) – The frequency of the PWM signal in hertz. Defaults to 100.
duty_factor (int) – The duty factor of the PWM signal. This is a value between 0 and 65535. Defaults to 65535.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the LED will be off initially. IfTrue
, the LED will be switched on initially.
- blink(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the LED stops blinking. If False, the method will return and the LED will blink in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- close()
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- pulse(fade_in_time=1, fade_out_time=None, n=None, wait=False, fps=25)
Makes the device pulse on and off repeatedly.
- Parameters
fade_in_time (float) – The length of time in seconds that the device will take to turn on. Defaults to 1.
fade_out_time (float) – The length of time in seconds that the device will take to turn off. Defaults to 1.
fps (int) – The frames per second that will be used to calculate the number of steps between off/on states. Defaults to 25.
n (int) – The number of times to pulse the LED. If None, the LED will pulse forever. Defaults to None.
wait (bool) – If True, the method will block until the LED stops pulsing. If False, the method will return and the LED will pulse in the background. Defaults to False.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property brightness
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
- property freq
Returns the current frequency of the device.
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
RGBLED
- class picozero.RGBLED(red=None, green=None, blue=None, active_high=True, initial_value=(0, 0, 0), pwm=True)[source]
Bases:
OutputDevice
,PinsMixin
Extends
OutputDevice
and represents a full colour 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 GP pins. You should use three limiting resistors (one per anode). The following code will make the LED yellow:from picozero import RGBLED rgb = RGBLED(1, 2, 3) rgb.color = (1, 1, 0)
0–255 colours are also supported:
rgb.color = (255, 255, 0)
- Parameters
red (int) – The GP pin that controls the red component of the RGB LED.
green (int) – The GP pin that controls the green component of the RGB LED.
blue (int) – The GP 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 toFalse
.initial_value (Color or tuple) – The initial color for the RGB LED. Defaults to black
(0, 0, 0)
.pwm (bool) – If
True
(the default), constructPWMLED
instances for each component of the RGBLED. IfFalse
, constructDigitalLED
instances.
- blink(on_times=1, fade_times=0, colors=((1, 0, 0), (0, 1, 0), (0, 0, 1)), n=None, wait=False, fps=25)[source]
Makes the device blink between colours repeatedly.
- Parameters
on_times (float) – Single value or tuple of numbers of seconds to stay on each colour. Defaults to 1 second.
fade_times (float) – Single value or tuple of times to fade between each colour. Must be 0 if pwm was
False
when the class was constructed.colors (tuple Tuple of colours to blink between, use
(0, 0, 0)
for off.) – The colours to blink between. Defaults to red, green, blue.n (int or None) – Number of times to blink;
None
(the default) means forever.wait (bool) – If
False
(the default), use a Timer to manage blinking, continue blinking, and return immediately. IfFalse
, only return when the blinking is finished (warning: the default value of n will result in this method never returning).
- cycle(fade_times=1, colors=((1, 0, 0), (0, 1, 0), (0, 0, 1)), n=None, wait=False, fps=25)[source]
Makes the device fade in and out repeatedly.
- Parameters
fade_times (float) – Single value or tuple of numbers of seconds to spend fading between colours. Defaults to 1.
fade_times – Number of seconds to spend fading out. Defaults to 1.
on_color – Tuple of colours to cycle between. Defaults to red, green, blue.
n (int or None) – Number of times to cycle;
None
(the default) means forever.
- invert()[source]
Inverts 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 colour, this method inverts the colour.
- off()
Turns the device off.
- on()[source]
Turns the LED on. This is equivalent to setting the LED color to white, e.g.
(1, 1, 1)
.
- pulse(fade_times=1, colors=((0, 0, 0), (1, 0, 0), (0, 0, 0), (0, 1, 0), (0, 0, 0), (0, 0, 1)), n=None, wait=False, fps=25)[source]
Makes the device fade between colours repeatedly.
- Parameters
fade_times (float) – Single value or tuple of numbers of seconds to spend fading. Defaults to 1.
fade_out_time (float) – Number of seconds to spend fading out. Defaults to 1.
on_color – Tuple of colours to pulse between in order. Defaults to red, off, green, off, blue, off.
n (int or None) – Number of times to pulse;
None
(the default) means forever.
- toggle()[source]
Toggles the state of the device. If the device has a specific colour, then that colour is saved and the device is turned off. If the device is off, it will be changed to the last colour it had when it was on or, if none, to fully on (
value
is(1, 1, 1)
).
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property blue
Represents the blue component of the LED as a value between 0 and 255 if pwm was
True
when the class was constructed (but only takes values of 0 or 255 otherwise).
- property color
Represents the colour of the LED as an RGB 3-tuple of
(red, green, blue)
where each value is between 0 and 255 if pwm wasTrue
when the class was constructed (but only takes values of 0 or 255 otherwise). For example, red would be(255, 0, 0)
and yellow would be(255, 255, 0)
, whereas orange would be(255, 127, 0)
.
- property colour
Represents the colour of the LED as an RGB 3-tuple of
(red, green, blue)
where each value is between 0 and 255 if pwm wasTrue
when the class was constructed (but only takes values of 0 or 255 otherwise). For example, red would be(255, 0, 0)
and yellow would be(255, 255, 0)
, whereas orange would be(255, 127, 0)
.
- property green
Represents the green component of the LED as a value between 0 and 255 if pwm was
True
when the class was constructed (but only takes values of 0 or 255 otherwise).
- property is_active
Returns
True
if the LED is currently active (not black) andFalse
otherwise.
- property is_lit
Returns
True
if the LED is currently active (not black) andFalse
otherwise.
- property pins
Returns a tuple of pins used by the device.
- property red
Represents the red component of the LED as a value between 0 and 255 if pwm was
True
when the class was constructed (but only takes values of 0 or 255 otherwise).
- property value
Represents the colour of the LED as an RGB 3-tuple of
(red, green, blue)
where each value is between 0 and 1 if pwm wasTrue
when the class was constructed (but only takes values of 0 or 1 otherwise). For example, red would be(1, 0, 0)
and yellow would be(1, 1, 0)
, whereas orange would be(1, 0.5, 0)
.
Buzzer
- class picozero.Buzzer(pin, active_high=True, initial_value=False)[source]
Bases:
DigitalOutputDevice
Represents an active or passive buzzer, which can be turned on or off.
- Parameters
pin (int) – The pin that the device is connected to.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the Buzzer will be off initially. IfTrue
, the Buzzer will be switched on initially.
- beep(on_time=1, off_time=None, n=None, wait=False)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None is specified, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the device stops turning on and off. If False, the method will return and the device will turn on and off in the background. Defaults to False.
- blink(on_time=1, off_time=None, n=None, wait=False)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None is specified, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the device stops turning on and off. If False, the method will return and the device will turn on and off in the background. Defaults to False.
- close()
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
PWMBuzzer
- class picozero.PWMBuzzer(pin, freq=440, duty_factor=1023, active_high=True, initial_value=False)[source]
Bases:
PWMOutputDevice
Represents a passive buzzer driven by a PWM pin; the volume of the buzzer can be changed.
- Parameters
pin (int) – The pin that the buzzer is connected to.
freq (int) – The frequency of the PWM signal in hertz. Defaults to 440.
duty_factor (int) – The duty factor of the PWM signal. This is a value between 0 and 65535. Defaults to 1023.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the buzzer will be off initially. IfTrue
, the buzzer will be switched on initially.
- beep(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the LED stops blinking. If False, the method will return and the LED will blink in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- blink(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the LED stops blinking. If False, the method will return and the LED will blink in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- close()
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- pulse(fade_in_time=1, fade_out_time=None, n=None, wait=False, fps=25)
Makes the device pulse on and off repeatedly.
- Parameters
fade_in_time (float) – The length of time in seconds that the device will take to turn on. Defaults to 1.
fade_out_time (float) – The length of time in seconds that the device will take to turn off. Defaults to 1.
fps (int) – The frames per second that will be used to calculate the number of steps between off/on states. Defaults to 25.
n (int) – The number of times to pulse the LED. If None, the LED will pulse forever. Defaults to None.
wait (bool) – If True, the method will block until the LED stops pulsing. If False, the method will return and the LED will pulse in the background. Defaults to False.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property freq
Returns the current frequency of the device.
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
- property volume
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
Speaker
- class picozero.Speaker(pin, initial_freq=440, initial_volume=0, duty_factor=1023, active_high=True)[source]
Bases:
OutputDevice
,PinMixin
Represents a speaker driven by a PWM pin.
- Parameters
pin (int) – The pin that the speaker is connected to.
initial_freq (int) – The initial frequency of the PWM signal in hertz. Defaults to 440.
initial_volume (int) – The initial volume of the PWM signal. This is a value between 0 and 1. Defaults to 0.
duty_factor (int) – The duty factor of the PWM signal. This is a value between 0 and 65535. Defaults to 1023.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- beep(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)[source]
Makes the buzzer turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the beep operation. If None, the device will continue beeping forever. The default is None.
wait (bool) – If True, the method will block until the buzzer stops beeping. If False, the method will return and the buzzer will beep in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- blink(on_time=1, off_time=None, n=None, wait=False)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None is specified, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the device stops turning on and off. If False, the method will return and the device will turn on and off in the background. Defaults to False.
- on(volume=1)[source]
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- play(tune=440, duration=1, volume=1, n=1, wait=True)[source]
Plays a tune for a given duration.
- Parameters
tune (int) –
The tune to play can be specified as:
a single “note”, represented as: + a frequency in Hz e.g. 440 + a midi note e.g. 60 + a note name as a string e.g. “E4”
a list of notes and duration e.g. [440, 1] or [“E4”, 2]
a list of two value tuples of (note, duration) e.g. [(440,1), (60, 2), (“e4”, 3)]
Defaults to 440.
volume (int) – The volume of the tune; 1 is maximum volume, 0 is mute. Defaults to 1.
duration (float) – The duration of each note in seconds. Defaults to 1.
n (int) – The number of times to play the tune. If None, the tune will play forever. Defaults to 1.
wait (bool) – If True, the method will block until the tune has finished. If False, the method will return and the tune will play in the background. Defaults to True.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property freq
Sets or returns the current frequency of the speaker.
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns the value of the speaker. The value is a tuple of (freq, volume).
- property volume
Sets or returns the volume of the speaker: 1 for maximum volume, 0 for off.
Servo
- class picozero.Servo(pin, initial_value=None, min_pulse_width=0.001, max_pulse_width=0.002, frame_width=0.02, duty_factor=65535)[source]
Bases:
PWMOutputDevice
Represents a PWM-controlled servo motor.
Setting the value to 0 will move the servo to its minimum position, 1 will move the servo to its maximum position. Setting the value to
None
will turn the servo “off” (i.e. no signal is sent).- Parameters
pin (int) – The pin the servo motor is connected to.
initial_value (bool) – If
0
, the servo will be set to its minimum position. If1
, the servo will set to its maximum position. IfNone
(the default), the position of the servo will not change.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.
duty_factor (int) – The duty factor of the PWM signal. This is a value between 0 and 65535. Defaults to 65535.
- blink(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the LED stops blinking. If False, the method will return and the LED will blink in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- close()
Closes the device and turns the device off. Once closed, the device can no longer be used.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- pulse(fade_in_time=1, fade_out_time=None, n=None, wait=False, fps=25)
Makes the device pulse on and off repeatedly.
- Parameters
fade_in_time (float) – The length of time in seconds that the device will take to turn on. Defaults to 1.
fade_out_time (float) – The length of time in seconds that the device will take to turn off. Defaults to 1.
fps (int) – The frames per second that will be used to calculate the number of steps between off/on states. Defaults to 25.
n (int) – The number of times to pulse the LED. If None, the LED will pulse forever. Defaults to None.
wait (bool) – If True, the method will block until the LED stops pulsing. If False, the method will return and the LED will pulse in the background. Defaults to False.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property freq
Returns the current frequency of the device.
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
Motor
- class picozero.Motor(forward, backward, pwm=True)[source]
Bases:
PinsMixin
Represents a motor connected to a motor controller that has a two-pin input. One pin drives the motor “forward”, the other drives the motor “backward”.
- Parameters
forward (int) – The GP pin that controls the “forward” motion of the motor.
backward (int) – The GP pin that controls the “backward” motion of the motor.
pwm (bool) – If
True
(the default), PWM pins are used to drive the motor. When using PWM pins, values between 0 and 1 can be used to set the speed.
- backward(speed=1, t=None, wait=False)[source]
Makes the motor turn “backward”.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the motor should turn for. If None is specified, the motor will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- close()[source]
Closes the device and releases any resources. Once closed, the device can no longer be used.
- forward(speed=1, t=None, wait=False)[source]
Makes the motor turn “forward”.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the motor should turn for. If None is specified, the motor will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- on(speed=1, t=None, wait=False)[source]
Turns the motor on and makes it turn.
- Parameters
speed (float) – The speed as a value between -1 and 1: 1 turns the motor at full speed in one direction, -1 turns the motor at full speed in the opposite direction. Defaults to 1.
t (float) – The time in seconds that the motor should run for. If None is specified, the motor will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- start(speed=1, t=None, wait=False)
Turns the motor on and makes it turn.
- Parameters
speed (float) – The speed as a value between -1 and 1: 1 turns the motor at full speed in one direction, -1 turns the motor at full speed in the opposite direction. Defaults to 1.
t (float) – The time in seconds that the motor should run for. If None is specified, the motor will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- stop()
Stops the motor turning.
- property pins
Returns a tuple of pins used by the device.
- property value
Sets or returns the motor speed as a value between -1 and 1: -1 is full speed “backward”, 1 is full speed “forward”, 0 is stopped.
Robot / Rover
- class picozero.Robot(left, right, pwm=True)[source]
Bases:
object
Represents a generic dual-motor robot / rover / buggy.
Alias for
Rover
.This class is constructed with two tuples representing the forward and backward pins of the left and right controllers. For example, if the left motor’s controller is connected to pins 12 and 13, while the right motor’s controller is connected to pins 14 and 15, then the following example will drive the robot forward:
from picozero import Robot robot = Robot(left=(12, 13), right=(14, 15)) robot.forward()
- Parameters
left (tuple) – A tuple of two pins representing the forward and backward inputs of the left motor’s controller.
right (tuple) – A tuple of two pins representing the forward and backward inputs of the right motor’s controller.
pwm (bool) – If
True
(the default), pwm pins will be used, allowing variable speed control.
- backward(speed=1, t=None, wait=False)[source]
Makes the robot move “backward”.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the robot should move for. If None is specified, the robot will continue to move until stopped. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- close()[source]
Closes the device and releases any resources. Once closed, the device can no longer be used.
- forward(speed=1, t=None, wait=False)[source]
Makes the robot move “forward”.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the robot should move for. If None is specified, the robot will continue to move until stopped. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- left(speed=1, t=None, wait=False)[source]
Makes the robot turn “left” by turning the left motor backward and the right motor forward.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the robot should turn for. If None is specified, the robot will continue to turn until stopped. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- right(speed=1, t=None, wait=False)[source]
Makes the robot turn “right” by turning the left motor forward and the right motor backward.
- Parameters
speed (float) – The speed as a value between 0 and 1: 1 is full speed, 0 is stop. Defaults to 1.
t (float) – The time in seconds that the robot should turn for. If None is specified, the robot will continue to turn until stopped. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the motor will turn on in the background. Defaults to False. Only effective if t is not None.
- property value
Represents the motion of the robot as a tuple of (left_motor_speed, right_motor_speed) with
(-1, -1)
representing full speed backwards,(1, 1)
representing full speed forwards, and(0, 0)
representing stopped.
DigitalOutputDevice
- class picozero.DigitalOutputDevice(pin, active_high=True, initial_value=False)[source]
Bases:
OutputDevice
,PinMixin
Represents a device driven by a digital pin.
- Parameters
pin (int) – The pin that the device is connected to.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the LED will be off initially. IfTrue
, the LED will be switched on initially.
- blink(on_time=1, off_time=None, n=None, wait=False)
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds that the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds that the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None is specified, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the device stops turning on and off. If False, the method will return and the device will turn on and off in the background. Defaults to False.
- close()[source]
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
PWMOutputDevice
- class picozero.PWMOutputDevice(pin, freq=100, duty_factor=65535, active_high=True, initial_value=False)[source]
Bases:
OutputDevice
,PinMixin
Represents a device driven by a PWM pin.
- Parameters
pin (int) – The pin that the device is connected to.
freq (int) – The frequency of the PWM signal in hertz. Defaults to 100.
duty_factor (int) – The duty factor of the PWM signal. This is a value between 0 and 65535. Defaults to 65535.
active_high (bool) – If
True
(the default), theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).initial_value (bool) – If
False
(the default), the LED will be off initially. IfTrue
, the LED will be switched on initially.
- blink(on_time=1, off_time=None, n=None, wait=False, fade_in_time=0, fade_out_time=None, fps=25)[source]
Makes the device turn on and off repeatedly.
- Parameters
on_time (float) – The length of time in seconds the device will be on. Defaults to 1.
off_time (float) – The length of time in seconds the device will be off. If None, it will be the same as
on_time
. Defaults to None.n (int) – The number of times to repeat the blink operation. If None, the device will continue blinking forever. The default is None.
wait (bool) – If True, the method will block until the LED stops blinking. If False, the method will return and the LED will blink in the background. Defaults to False.
fade_in_time (float) – The length of time in seconds to spend fading in. Defaults to 0.
fade_out_time (float) – The length of time in seconds to spend fading out. If None, it will be the same as
fade_in_time
. Defaults to None.fps (int) – The frames per second that will be used to calculate the number of steps between off/on states when fading. Defaults to 25.
- close()[source]
Closes the device and turns the device off. Once closed, the device can no longer be used.
- off()
Turns the device off.
- on(value=1, t=None, wait=False)
Turns the device on.
- Parameters
value (float) – The value to set when turning on. Defaults to 1.
t (float) – The time in seconds that the device should be on. If None is specified, the device will stay on. The default is None.
wait (bool) – If True, the method will block until the time t has expired. If False, the method will return and the device will turn on in the background. Defaults to False. Only effective if t is not None.
- pulse(fade_in_time=1, fade_out_time=None, n=None, wait=False, fps=25)[source]
Makes the device pulse on and off repeatedly.
- Parameters
fade_in_time (float) – The length of time in seconds that the device will take to turn on. Defaults to 1.
fade_out_time (float) – The length of time in seconds that the device will take to turn off. Defaults to 1.
fps (int) – The frames per second that will be used to calculate the number of steps between off/on states. Defaults to 25.
n (int) – The number of times to pulse the LED. If None, the LED will pulse forever. Defaults to None.
wait (bool) – If True, the method will block until the LED stops pulsing. If False, the method will return and the LED will pulse in the background. Defaults to False.
- toggle()
If the device is off, turn it on. If it is on, turn it off.
- property active_high
Sets or returns the active_high property. If
True
, theon()
method will set the Pin to HIGH. IfFalse
, theon()
method will set the Pin to LOW (theoff()
method always does the opposite).
- property freq
Returns the current frequency of the device.
- property is_active
Returns
True
if the device is on.
- property pin
Returns the pin number used by the device.
- property value
Sets or returns a value representing the state of the device: 1 is on, 0 is off.
Switch
- class picozero.Switch(pin, pull_up=True, bounce_time=0.02)[source]
Bases:
DigitalInputDevice
Represents a toggle switch, which is either open or closed.
- Parameters
pin (int) – The pin that the device is connected to.
pull_up (bool) – If
True
(the default), the device will be pulled up to HIGH. IfFalse
, the device will be pulled down to LOW.bounce_time (float) – The bounce time for the device. If set, the device will ignore any button presses that happen within the bounce time after a button release. This is useful to prevent accidental button presses from registering as multiple presses. Defaults to 0.02 seconds.
- close()
Closes the device and releases any resources. Once closed, the device can no longer be used.
- property active_state
Sets or returns the active state of the device. If
None
(the default), the device will return the value that the pin is set to. IfTrue
, the device will returnTrue
if the pin is HIGH. IfFalse
, the device will returnFalse
if the pin is LOW.
- property is_active
Returns
True
if the device is active.
- property is_closed
Returns
True
if the device is active.
- property is_inactive
Returns
True
if the device is inactive.
- property is_open
Returns
True
if the device is inactive.
- property pin
Returns the pin number used by the device.
- property value
Returns the current value of the device. This is either
True
orFalse
depending on the value ofactive_state
.
- property when_activated
Returns a
callback
that will be called when the device is activated.
- property when_closed
Returns a
callback
that will be called when the device is activated.
- property when_deactivated
Returns a
callback
that will be called when the device is deactivated.
- property when_opened
Returns a
callback
that will be called when the device is deactivated.
Potentiometer / Pot
- class picozero.Potentiometer(pin, active_state=True, threshold=0.5)[source]
Bases:
AnalogInputDevice
Represents a potentiometer, which outputs a variable voltage between 0 and 3.3V.
Alias for
Pot
.- Parameters
pin (int) – The pin that the device is connected to.
active_state – The active state of the device. If
True
(the default), theAnalogInputDevice
will assume that the device is active when the pin is high and above the threshold. Ifactive_state
isFalse
, the device will be active when the pin is low and below the threshold.threshold (float) – The threshold that the device must be above or below to be considered active. The default is 0.5.
- property active_state
Sets or returns the active state of the device. If
None
(the default), the device will return the value that the pin is set to. IfTrue
, the device will returnTrue
if the pin is HIGH. IfFalse
, the device will returnFalse
if the pin is LOW.
- property is_active
Returns
True
if the device is active.
- property pin
Returns the pin number used by the device.
- property threshold
The threshold that the device must be above or below to be considered active. The default is 0.5.
- property value
Returns the current value of the device. This is either
True
orFalse
depending on the value ofactive_state
.
- property voltage
Returns the voltage of the analogue device.
TemperatureSensor / TempSensor / Thermistor
- class picozero.TemperatureSensor(pin, active_state=True, threshold=0.5, conversion=None)[source]
Bases:
AnalogInputDevice
Represents a TemperatureSensor, which outputs a variable voltage. The voltage can be converted to a temperature using a conversion function passed as a parameter.
Alias for
Thermistor
andTempSensor
.- Parameters
pin (int) – The pin that the device is connected to.
active_state – The active state of the device. If
True
(the default), theAnalogInputDevice
will assume that the device is active when the pin is high and above the threshold. Ifactive_state
isFalse
, the device will be active when the pin is low and below the threshold.threshold (float) – The threshold that the device must be above or below to be considered active. The default is 0.5.
conversion (float) –
A function that takes a voltage and returns a temperature.
e.g. The internal temperature sensor has a voltage range of 0.706V to 0.716V and would use the follow conversion function:
def temp_conversion(voltage): return 27 - (voltage - 0.706)/0.001721 temp_sensor = TemperatureSensor(pin, conversion=temp_conversion)
If
None
(the default), thetemp
property will returnNone
.
- property active_state
Sets or returns the active state of the device. If
None
(the default), the device will return the value that the pin is set to. IfTrue
, the device will returnTrue
if the pin is HIGH. IfFalse
, the device will returnFalse
if the pin is LOW.
- property conversion
Sets or returns the conversion function for the device.
- property is_active
Returns
True
if the device is active.
- property pin
Returns the pin number used by the device.
- property temp
Returns the temperature of the device. If the conversion function is not set, this will return
None
.
- property threshold
The threshold that the device must be above or below to be considered active. The default is 0.5.
- property value
Returns the current value of the device. This is either
True
orFalse
depending on the value ofactive_state
.
- property voltage
Returns the voltage of the analogue device.
DistanceSensor
- class picozero.DistanceSensor(echo, trigger, max_distance=1)[source]
Bases:
PinsMixin
Represents a HC-SR04 ultrasonic distance sensor.
- Parameters
echo (int) – The pin that the ECHO pin is connected to.
trigger (int) – The pin that the TRIG pin is connected to.
max_distance (float) – The
value
attribute reports a normalized value between 0 (too close to measure) and 1 (maximum distance). This parameter specifies the maximum distance expected in meters. This defaults to 1.
- property distance
Returns the current distance measured by the sensor in meters. Note that this property will have a value between 0 and max_distance.
- property max_distance
Returns the maximum distance that the sensor will measure in metres.
- property pins
Returns a tuple of pins used by the device.
- property value
Returns a value between 0, indicating the reflector is either touching the sensor or is sufficiently near that the sensor can’t tell the difference, and 1, indicating the reflector is at or beyond the specified max_distance. A return value of None indicates that the echo was not received before the timeout.
DigitalInputDevice
- class picozero.DigitalInputDevice(pin, pull_up=False, active_state=None, bounce_time=None)[source]
Bases:
InputDevice
,PinMixin
Represents a generic input device with digital functionality e.g. buttons that can be either active or inactive.
- Parameters
pin (int) – The pin that the device is connected to.
pull_up (bool) – If
True
, the device will be pulled up to HIGH. IfFalse
(the default), the device will be pulled down to LOW.active_state (bool) – If
True
(the default), the device will returnTrue
if the pin is HIGH. IfFalse
, the device will returnFalse
if the pin is LOW.bounce_time (float) – The bounce time for the device. If set, the device will ignore any button presses that happen within the bounce time after a button release. This is useful to prevent accidental button presses from registering as multiple presses. The default is
None
.
- close()[source]
Closes the device and releases any resources. Once closed, the device can no longer be used.
- property active_state
Sets or returns the active state of the device. If
None
(the default), the device will return the value that the pin is set to. IfTrue
, the device will returnTrue
if the pin is HIGH. IfFalse
, the device will returnFalse
if the pin is LOW.
- property is_active
Returns
True
if the device is active.
- property is_inactive
Returns
True
if the device is inactive.
- property pin
Returns the pin number used by the device.
- property value
Returns the current value of the device. This is either
True
orFalse
depending on the value ofactive_state
.
- property when_activated
Returns a
callback
that will be called when the device is activated.
- property when_deactivated
Returns a
callback
that will be called when the device is deactivated.