# 19. 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.

## 19.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).

## 19.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)`.

## 19.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()`.