20. API - Device Source Tools

GPIO Zero includes several utility routines which are intended to be used with the Source/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, all_values

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

20.1. Single source conversions

gpiozero.tools.absoluted(values)

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, -1, 1)
led.source = absoluted(motor)

pause()

gpiozero.tools.booleanized(values, min_value, max_value, hysteresis=0)

Returns True for each item in values between min_value and max_value, and False otherwise. hysteresis can optionally be used to add hysteresis which prevents the output value rapidly flipping when the input value is fluctuating near the min_value or max_value thresholds. For example, to light an LED only when a potentiometer is between ¼ and ¾ of its full range:

from gpiozero import LED, MCP3008
from gpiozero.tools import booleanized
from signal import pause

led = LED(4)
pot = MCP3008(channel=0)

led.source = booleanized(pot, 0.25, 0.75)

pause()

gpiozero.tools.clamped(values, output_min=0, output_max=1)

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, 0.5, 1.0)

pause()

gpiozero.tools.inverted(values, input_min=0, input_max=1)

Returns the inversion of the supplied values (input_min becomes input_max, input_max becomes input_min, input_min + 0.1 becomes input_max - 0.1, etc.). All items in values are assumed to be between input_min and input_max (which default to 0 and 1 respectively), and the output will be in the same range. 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)

pause()

gpiozero.tools.negated(values)

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)

pause()

gpiozero.tools.post_delayed(values, delay)

Waits for delay seconds after returning each item from values.

gpiozero.tools.post_periodic_filtered(values, repeat_after, block)

After every repeat_after items, blocks the next block items from values. Note that unlike pre_periodic_filtered(), repeat_after can’t be 0. For example, to block every tenth item read from an ADC:

from gpiozero import MCP3008
from gpiozero.tools import post_periodic_filtered

adc = MCP3008(channel=0)

for value in post_periodic_filtered(adc, 9, 1):
    print(value)

gpiozero.tools.pre_delayed(values, delay)

Waits for delay seconds before returning each item from values.

gpiozero.tools.pre_periodic_filtered(values, block, repeat_after)

Blocks the first block items from values, repeating the block after every repeat_after items, if repeat_after is non-zero. For example, to discard the first 50 values read from an ADC:

from gpiozero import MCP3008
from gpiozero.tools import pre_periodic_filtered

adc = MCP3008(channel=0)

for value in pre_periodic_filtered(adc, 50, 0):
    print(value)

Or to only display every even item read from an ADC:

from gpiozero import MCP3008
from gpiozero.tools import pre_periodic_filtered

adc = MCP3008(channel=0)

for value in pre_periodic_filtered(adc, 1, 1):
    print(value)

gpiozero.tools.quantized(values, steps, input_min=0, input_max=1)

Returns values quantized to steps increments. All items in values are assumed to be between input_min and input_max (which default to 0 and 1 respectively), and the output will be in the same range.

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, 4)

pause()

gpiozero.tools.queued(values, qsize)

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], 5)
    leds[i].source_delay = 0.01

leds[4].source = btn

pause()

gpiozero.tools.smoothed(values, qsize, average=<function mean>)

Queues up readings from values (the number of readings queued is determined by qsize) and begins yielding the average of the last qsize values when the queue is full. The larger the qsize, the more the values are smoothed. For example, to smooth the analog values read from an ADC:

from gpiozero import MCP3008
from gpiozero.tools import smoothed

adc = MCP3008(channel=0)

for value in smoothed(adc, 5):
    print(value)

gpiozero.tools.scaled(values, output_min, output_max, input_min=0, input_max=1)

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, -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).

20.2. Combining sources

gpiozero.tools.all_values(*values)

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, btn2)

pause()

gpiozero.tools.any_values(*values)

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, btn2)

pause()

gpiozero.tools.averaged(*values)

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, pot2, pot3)

pause()

gpiozero.tools.multiplied(*values)

Returns the product of all supplied values. One or more values can be specified. For example, to light a PWMLED as the product (i.e. multiplication) of several potentiometers connected to an MCP3008 ADC:

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

pot1 = MCP3008(channel=0)
pot2 = MCP3008(channel=1)
pot3 = MCP3008(channel=2)
led = PWMLED(4)

led.source = multiplied(pot1, pot2, pot3)

pause()

gpiozero.tools.summed(*values)

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

from gpiozero import MCP3008, PWMLED
from gpiozero.tools import summed, scaled
from signal import pause

pot1 = MCP3008(channel=0)
pot2 = MCP3008(channel=1)
pot3 = MCP3008(channel=2)
led = PWMLED(4)

led.source = scaled(summed(pot1, pot2, pot3), 0, 1, 0, 3)

pause()

gpiozero.tools.zip_values(*devices)

Provides a source constructed from the values of each item, for example:

from gpiozero import MCP3008, Robot
from gpiozero.tools import zip_values
from signal import pause

robot = Robot(left=(4, 14), right=(17, 18))

left = MCP3008(0)
right = MCP3008(1)

robot.source = zip_values(left, right)

pause()

zip_values(left, right) is equivalent to zip(left.values, right.values).

20.3. Artificial sources

gpiozero.tools.alternating_values(initial_value=False)

Provides an infinite source of values alternating between True and False, starting wth initial_value (which defaults to False). For example, to produce a flashing LED:

from gpiozero import LED
from gpiozero.tools import alternating_values
from signal import pause

red = LED(2)

red.source_delay = 0.5
red.source = alternating_values()

pause()

gpiozero.tools.cos_values(period=360)

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_half, inverted
from signal import pause

red = PWMLED(2)
blue = PWMLED(3)

red.source_delay = 0.01
blue.source_delay = red.source_delay
red.source = scaled_half(cos_values(100))
blue.source = inverted(red)

pause()

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

gpiozero.tools.ramping_values(period=360)

Provides an infinite source of values representing a triangle wave (from 0 to 1 and back again) which repeats every period values. For example, to pulse an LED once a second:

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

red = PWMLED(2)

red.source_delay = 0.01
red.source = ramping_values(100)

pause()

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

gpiozero.tools.random_values()

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)

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_half, inverted
from signal import pause

red = PWMLED(2)
blue = PWMLED(3)

red.source_delay = 0.01
blue.source_delay = red.source_delay
red.source = scaled_half(sin_values(100))
blue.source = inverted(red)

pause()

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