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
becomesFalse
, andFalse
becomesTrue
). 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 simultaneouslyTrue
). One or more values can be specified. For example, to light anLED
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 currentlyTrue
). One or more values can be specified. For example, to light anLED
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 anMCP3008
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()
.