gpiozero
GPIO Zero provides a method of using the declarative programming paradigm to connect devices together: feeding the values of one device into another, for example the values of a button into an LED:
examples/led_button.py
which is equivalent to:
examples/led_button_loop.py
except that the former is updated in a background thread, which enables you to do other things at the same time.
Every device has a ~Device.value property (the device's current value). Input devices (like buttons) can only have their values read, but output devices (like LEDs) can also have their value set to alter the state of the device:
>>> led = PWMLED(17)
>>> led.value # LED is initially off
0.0
>>> led.on() # LED is now on
>>> led.value
1.0
>>> led.value = 0 # LED is now offEvery device also has a ~ValuesMixin.values property (a generator continuously yielding the device's current value). All output devices have a ~SourceMixin.source property which can be set to any iterator. The device will iterate over the values of the device provided, setting the device's value to each element at a rate specified in the ~SourceMixin.source_delay property (the default is 0.01 seconds).
The most common use case for this is to set the source of an output device to match the values of an input device, like the example above. A more interesting example would be a potentiometer controlling the brightness of an LED:
examples/pwmled_pot.py
The way this works is that the input device's ~ValuesMixin.values property is used to feed values into the output device. Prior to v1.5, the ~SourceMixin.source had to be set directly to a device's ~ValuesMixin.values property:
examples/pwmled_pot_values.py
Note
Although this method is still supported, the recommended way is now to set the ~SourceMixin.source to a device object.
It is also possible to set an output device's ~SourceMixin.source to another output device, to keep them matching. In this example, the red LED is set to match the button, and the green LED is set to match the red LED, so both LEDs will be on when the button is pressed:
examples/matching_leds.py
The device's values can also be processed before they are passed to the ~SourceMixin.source:
For example, writing a generator function to pass the opposite of the Button value into the LED:
examples/source_value_processing.py
Alternatively, a custom generator can be used to provide values from an artificial source:
For example, writing a generator function to randomly yield 0 or 1:
examples/custom_generator.py
If the iterator is infinite (i.e. an infinite generator), the elements will be processed until the ~SourceMixin.source is changed or set to None.
If the iterator is finite (e.g. a list), this will terminate once all elements are processed (leaving the device's value at the final element):
examples/custom_generator_finite.py
GPIO Zero provides a set of ready-made functions for dealing with source/values, called source tools. These are available by importing from gpiozero.tools.
Some of these source tools are artificial sources which require no input:
In this example, random values between 0 and 1 are passed to the LED, giving it a flickering candle effect:
examples/random_values.py
Note that in the above example, ~SourceMixin.source_delay is used to make the LED iterate over the random values slightly slower. ~SourceMixin.source_delay can be set to a larger number (e.g. 1 for a one second delay) or set to 0 to disable any delay.
Some tools take a single source and process its values:
In this example, the LED is lit only when the button is not pressed:
examples/negated.py
Note
Note that source tools which take one or more value parameters support passing either ~ValuesMixin derivatives, or iterators, including a device's ~ValuesMixin.values property.
Some tools combine the values of multiple sources:
In this example, the LED is lit only if both buttons are pressed (like an AND gate):
examples/combining_sources.py
Similarly, ~tools.any_values with two buttons would simulate an OR gate.
While most devices have a ~Device.value range between 0 and 1, some have a range between -1 and 1 (e.g. Motor, Servo and TonalBuzzer). Some source tools output values between -1 and 1, which are ideal for these devices, for example passing ~tools.sin_values in:
examples/sin_values.py
In this example, all three devices are following the sine wave. The motor value ramps up from 0 (stopped) to 1 (full speed forwards), then back down to 0 and on to -1 (full speed backwards) in a cycle. Similarly, the servo moves from its mid point to the right, then towards the left; and the buzzer starts with its mid tone, gradually raises its frequency, to its highest tone, then down towards its lowest tone. Note that setting ~SourceMixin.source_delay will alter the speed at which the device iterates through the values. Alternatively, the tool ~tools.cos_values could be used to start from -1 and go up to 1, and so on.
GPIO Zero also provides several internal devices <api_internal> which represent facilities provided by the operating system itself. These can be used to react to things like the time of day, or whether a server is available on the network. These classes include a ~ValuesMixin.values property which can be used to feed values into a device's ~SourceMixin.source. For example, a lamp connected to an Energenie socket can be controlled by a TimeOfDay object so that it is on between the hours of 8am and 8pm:
examples/timed_heat_lamp.py
Using the DiskUsage class with LEDBarGraph can show your Pi's disk usage percentage on a bar graph:
examples/disk_usage_bar_graph.py
Demonstrating a garden light system whereby the light comes on if it's dark and there's motion is simple enough, but it requires using the ~tools.booleanized source tool to convert the light sensor from a float value into a boolean:
examples/garden_light.py
The ~Device.value of a composite device made up of the nested values of its devices. For example, the value of a Robot object is a 2-tuple containing its left and right motor values:
>>> from gpiozero import Robot
>>> robot = Robot(left=(14, 15), right=(17, 18))
>>> robot.value
RobotValue(left_motor=0.0, right_motor=0.0)
>>> tuple(robot.value)
(0.0, 0.0)
>>> robot.forward()
>>> tuple(robot.value)
(1.0, 1.0)
>>> robot.backward()
>>> tuple(robot.value)
(-1.0, -1.0)
>>> robot.value = (1, 1) # robot is now driven forwardsUse two potentiometers to control the left and right motor speed of a robot:
examples/robot_pots_1.py
To include reverse direction, scale the potentiometer values from 0->1 to -1->1:
examples/robot_pots_2.py
Note that this example uses the built-in zip rather than the tool ~tools.zip_values as the ~tools.scaled tool yields values which do not need converting, just zipping. Also note that this use of zip will not work in Python 2, instead use izip.