Source Tools

GPIO Zero includes several utility routines which are intended to be used with the source and values attributes common to most devices in the library. These utility routines are in the tools module of GPIO Zero and are typically imported as follows:

from gpiozero.tools import scaled, negated, conjunction

Given that source and values deal with infinite iterators, another excellent source of utilities is the itertools module in the standard library.

Warning

While the devices API is now considered stable and won’t change in backwards incompatible ways, the tools API is not yet considered stable. It is potentially subject to change in future versions. We welcome any comments from testers!

Single source conversions

gpiozero.tools.absoluted(values)[source]

Returns values with all negative elements negated (so that they’re positive). For example:

from gpiozero import PWMLED, Motor, MCP3008
from gpiozero.tools import absoluted, scaled
from signal import pause

led = PWMLED(4)
motor = Motor(22, 27)
pot = MCP3008(channel=0)
motor.source = scaled(pot.values, -1, 1)
led.source = absoluted(motor.values)
pause()
gpiozero.tools.clamped(values, output_min=0, output_max=1)[source]

Returns values clamped from output_min to output_max, i.e. any items less than output_min will be returned as output_min and any items larger than output_max will be returned as output_max (these default to 0 and 1 respectively). For example:

from gpiozero import PWMLED, MCP3008
from gpiozero.tools import clamped
from signal import pause

led = PWMLED(4)
pot = MCP3008(channel=0)
led.source = clamped(pot.values, 0.5, 1.0)
pause()
gpiozero.tools.inverted(values)[source]

Returns the inversion of the supplied values (1 becomes 0, 0 becomes 1, 0.1 becomes 0.9, etc.). For example:

from gpiozero import MCP3008, PWMLED
from gpiozero.tools import inverted
from signal import pause

led = PWMLED(4)
pot = MCP3008(channel=0)
led.source = inverted(pot.values)
pause()
gpiozero.tools.negated(values)[source]

Returns the negation of the supplied values (True becomes False, and False becomes True). For example:

from gpiozero import Button, LED
from gpiozero.tools import negated
from signal import pause

led = LED(4)
btn = Button(17)
led.source = negated(btn.values)
pause()
gpiozero.tools.post_delayed(values, delay)[source]

Waits for delay seconds after returning each item from values.

gpiozero.tools.pre_delayed(values, delay)[source]

Waits for delay seconds before returning each item from values.

gpiozero.tools.quantized(values, steps, output_min=0, output_max=1)[source]

Returns values quantized to steps increments. All items in values are assumed to be between output_min and output_max (use scaled() to ensure this if necessary).

For example, to quantize values between 0 and 1 to 5 “steps” (0.0, 0.25, 0.5, 0.75, 1.0):

from gpiozero import PWMLED, MCP3008
from gpiozero.tools import quantized
from signal import pause

led = PWMLED(4)
pot = MCP3008(channel=0)
led.source = quantized(pot.values, 4)
pause()
gpiozero.tools.queued(values, qsize)[source]

Queues up readings from values (the number of readings queued is determined by qsize) and begins yielding values only when the queue is full. For example, to “cascade” values along a sequence of LEDs:

from gpiozero import LEDBoard, Button
from gpiozero.tools import queued
from signal import pause

leds = LEDBoard(5, 6, 13, 19, 26)
btn = Button(17)
for i in range(4):
    leds[i].source = queued(leds[i + 1].values, 5)
    leds[i].source_delay = 0.01
leds[4].source = btn.values
pause()
gpiozero.tools.scaled(values, output_min, output_max, input_min=0, input_max=1)[source]

Returns values scaled from output_min to output_max, assuming that all items in values lie between input_min and input_max (which default to 0 and 1 respectively). For example, to control the direction of a motor (which is represented as a value between -1 and 1) using a potentiometer (which typically provides values between 0 and 1):

from gpiozero import Motor, MCP3008
from gpiozero.tools import scaled
from signal import pause

motor = Motor(20, 21)
pot = MCP3008(channel=0)
motor.source = scaled(pot.values, -1, 1)
pause()

Warning

If values contains elements that lie outside input_min to input_max (inclusive) then the function will not produce values that lie within output_min to output_max (inclusive).

Combining sources

gpiozero.tools.all_values(*values)[source]

Returns the logical conjunction of all supplied values (the result is only True if and only if all input values are simultaneously True). One or more values can be specified. For example, to light an LED only when both buttons are pressed:

from gpiozero import LED, Button
from gpiozero.tools import all_values
from signal import pause

led = LED(4)
btn1 = Button(20)
btn2 = Button(21)
led.source = all_values(btn1.values, btn2.values)
pause()
gpiozero.tools.any_values(*values)[source]

Returns the logical disjunction of all supplied values (the result is True if any of the input values are currently True). One or more values can be specified. For example, to light an LED when any button is pressed:

from gpiozero import LED, Button
from gpiozero.tools import any_values
from signal import pause

led = LED(4)
btn1 = Button(20)
btn2 = Button(21)
led.source = any_values(btn1.values, btn2.values)
pause()
gpiozero.tools.averaged(*values)[source]

Returns the mean of all supplied values. One or more values can be specified. For example, to light a PWMLED as the average of several potentiometers connected to an MCP3008 ADC:

from gpiozero import MCP3008, PWMLED
from gpiozero.tools import averaged
from signal import pause

pot1 = MCP3008(channel=0)
pot2 = MCP3008(channel=1)
pot3 = MCP3008(channel=2)
led = PWMLED(4)
led.source = averaged(pot1.values, pot2.values, pot3.values)
pause()

Artifical sources

gpiozero.tools.cos_values(period=360)[source]

Provides an infinite source of values representing a cosine wave (from -1 to +1) which repeats every period values. For example, to produce a “siren” effect with a couple of LEDs that repeats once a second:

from gpiozero import PWMLED
from gpiozero.tools import cos_values, scaled, inverted
from signal import pause

red = PWMLED(2)
blue = PWMLED(3)
red.source_delay = 0.01
blue.source_delay = 0.01
red.source = scaled(cos_values(100), 0, 1, -1, 1)
blue.source = inverted(red.values)
pause()

If you require a different range than -1 to +1, see scaled().

gpiozero.tools.random_values()[source]

Provides an infinite source of random values between 0 and 1. For example, to produce a “flickering candle” effect with an LED:

from gpiozero import PWMLED
from gpiozero.tools import random_values
from signal import pause

led = PWMLED(4)
led.source = random_values()
pause()

If you require a wider range than 0 to 1, see scaled().

gpiozero.tools.sin_values(period=360)[source]

Provides an infinite source of values representing a sine wave (from -1 to +1) which repeats every period values. For example, to produce a “siren” effect with a couple of LEDs that repeats once a second:

from gpiozero import PWMLED
from gpiozero.tools import sin_values, scaled, inverted
from signal import pause

red = PWMLED(2)
blue = PWMLED(3)
red.source_delay = 0.01
blue.source_delay = 0.01
red.source = scaled(sin_values(100), 0, 1, -1, 1)
blue.source = inverted(red.values)
pause()

If you require a different range than -1 to +1, see scaled().