Input Devices¶

These input device component interfaces have been provided for simple use of everyday components. Components must be wired up correctly before use in code.

Note

All GPIO pin numbers use Broadcom (BCM) numbering. See the Recipes page for more information.

Button¶

class gpiozero.Button(pin, pull_up=True, bounce_time=None)[source]¶

Extends DigitalInputDevice and represents a simple push button or switch.

Connect one side of the button to a ground pin, and the other to any GPIO pin. Alternatively, connect one side of the button to the 3V3 pin, and the other to any GPIO pin, then set pull_up to False in the Button constructor.

The following example will print a line of text when the button is pushed:

from gpiozero import Button

button = Button(4)
button.wait_for_press()
print("The button was pressed!")

Parameters:

pin (int) – The GPIO pin which the button is attached to. See Notes for valid pin numbers.
pull_up (bool) – If True (the default), the GPIO pin will be pulled high by default. In this case, connect the other side of the button to ground. If False, the GPIO pin will be pulled low by default. In this case, connect the other side of the button to 3V3.
bounce_time (float) – If None (the default), no software bounce compensation will be performed. Otherwise, this is the length in time (in seconds) that the component will ignore changes in state after an initial change.

wait_for_press(timeout=None)¶

Pause the script until the device is activated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is active.

wait_for_release(timeout=None)¶

Pause the script until the device is deactivated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is inactive.

is_pressed¶: Returns True if the device is currently active and False otherwise.

pin¶: The Pin that the device is connected to. This will be None if the device has been closed (see the close() method). When dealing with GPIO pins, query pin.number to discover the GPIO pin (in BCM numbering) that the device is connected to.

pull_up¶: If True, the device uses a pull-up resistor to set the GPIO pin “high” by default. Defaults to False.

when_pressed¶

The function to run when the device changes state from inactive to active.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.

Set this property to None (the default) to disable the event.

when_released¶

The function to run when the device changes state from active to inactive.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that deactivated will be passed as that parameter.

Set this property to None (the default) to disable the event.

Motion Sensor (PIR)¶

class gpiozero.MotionSensor(pin, queue_len=1, sample_rate=10, threshold=0.5, partial=False)[source]¶

Extends SmoothedInputDevice and represents a passive infra-red (PIR) motion sensor like the sort found in the CamJam #2 EduKit.

A typical PIR device has a small circuit board with three pins: VCC, OUT, and GND. VCC should be connected to a 5V pin, GND to one of the ground pins, and finally OUT to the GPIO specified as the value of the pin parameter in the constructor.

The following code will print a line of text when motion is detected:

from gpiozero import MotionSensor

pir = MotionSensor(4)
pir.wait_for_motion()
print("Motion detected!")

Parameters:

pin (int) – The GPIO pin which the button is attached to. See Notes for valid pin numbers.
queue_len (int) – The length of the queue used to store values read from the sensor. This defaults to 1 which effectively disables the queue. If your motion sensor is particularly “twitchy” you may wish to increase this value.
sample_rate (float) – The number of values to read from the device (and append to the internal queue) per second. Defaults to 10.
threshold (float) – Defaults to 0.5. When the mean of all values in the internal queue rises above this value, the sensor will be considered “active” by the is_active property, and all appropriate events will be fired.
partial (bool) – When False (the default), the object will not return a value for is_active until the internal queue has filled with values. Only set this to True if you require values immediately after object construction.

wait_for_motion(timeout=None)¶

Pause the script until the device is activated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is active.

wait_for_no_motion(timeout=None)¶

Pause the script until the device is deactivated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is inactive.

motion_detected¶: Returns True if the device is currently active and False otherwise.

pin¶: The Pin that the device is connected to. This will be None if the device has been closed (see the close() method). When dealing with GPIO pins, query pin.number to discover the GPIO pin (in BCM numbering) that the device is connected to.

when_motion¶

The function to run when the device changes state from inactive to active.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.

Set this property to None (the default) to disable the event.

when_no_motion¶

The function to run when the device changes state from active to inactive.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that deactivated will be passed as that parameter.

Set this property to None (the default) to disable the event.

Light Sensor (LDR)¶

class gpiozero.LightSensor(pin, queue_len=5, charge_time_limit=0.01, threshold=0.1, partial=False)[source]¶

Extends SmoothedInputDevice and represents a light dependent resistor (LDR).

Connect one leg of the LDR to the 3V3 pin; connect one leg of a 1µf capacitor to a ground pin; connect the other leg of the LDR and the other leg of the capacitor to the same GPIO pin. This class repeatedly discharges the capacitor, then times the duration it takes to charge (which will vary according to the light falling on the LDR).

The following code will print a line of text when light is detected:

from gpiozero import LightSensor

ldr = LightSensor(18)
ldr.wait_for_light()
print("Light detected!")

Parameters:

pin (int) – The GPIO pin which the button is attached to. See Notes for valid pin numbers.
queue_len (int) – The length of the queue used to store values read from the circuit. This defaults to 5.
charge_time_limit (float) – If the capacitor in the circuit takes longer than this length of time to charge, it is assumed to be dark. The default (0.01 seconds) is appropriate for a 0.01µf capacitor coupled with the LDR from the CamJam #2 EduKit. You may need to adjust this value for different valued capacitors or LDRs.
threshold (float) – Defaults to 0.1. When the mean of all values in the internal queue rises above this value, the area will be considered “light”, and all appropriate events will be fired.
partial (bool) – When False (the default), the object will not return a value for is_active until the internal queue has filled with values. Only set this to True if you require values immediately after object construction.

wait_for_dark(timeout=None)¶

Pause the script until the device is deactivated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is inactive.

wait_for_light(timeout=None)¶

Pause the script until the device is activated, or the timeout is reached.

Parameters:	timeout (float) – Number of seconds to wait before proceeding. If this is `None` (the default), then wait indefinitely until the device is active.

light_detected¶: Returns True if the device is currently active and False otherwise.

pin¶: The Pin that the device is connected to. This will be None if the device has been closed (see the close() method). When dealing with GPIO pins, query pin.number to discover the GPIO pin (in BCM numbering) that the device is connected to.

when_dark¶

The function to run when the device changes state from active to inactive.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that deactivated will be passed as that parameter.

Set this property to None (the default) to disable the event.

when_light¶

The function to run when the device changes state from inactive to active.

This can be set to a function which accepts no (mandatory) parameters, or a Python function which accepts a single mandatory parameter (with as many optional parameters as you like). If the function accepts a single mandatory parameter, the device that activated will be passed as that parameter.

Set this property to None (the default) to disable the event.

Analog to Digital Converters (ADC)¶

class gpiozero.MCP3004(channel=0, device=0, differential=False)[source]¶

The MCP3004 is a 10-bit analog to digital converter with 4 channels (0-3).

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3008(channel=0, device=0, differential=False)[source]¶

The MCP3008 is a 10-bit analog to digital converter with 8 channels (0-7).

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3204(channel=0, device=0, differential=False)[source]¶

The MCP3204 is a 12-bit analog to digital converter with 4 channels (0-3).

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3208(channel=0, device=0, differential=False)[source]¶

The MCP3208 is a 12-bit analog to digital converter with 8 channels (0-7).

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3301(device=0)[source]¶

The MCP3301 is a signed 13-bit analog to digital converter. Please note that the MCP3301 always operates in differential mode between its two channels and the output value is scaled from -1 to +1.

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3302(channel=0, device=0, differential=False)[source]¶

The MCP3302 is a 12/13-bit analog to digital converter with 4 channels (0-3). When operated in differential mode, the device outputs a signed 13-bit value which is scaled from -1 to +1. When operated in single-ended mode (the default), the device outputs an unsigned 12-bit value scaled from 0 to 1.

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.

class gpiozero.MCP3304(channel=0, device=0, differential=False)[source]¶

The MCP3304 is a 12/13-bit analog to digital converter with 8 channels (0-7). When operated in differential mode, the device outputs a signed 13-bit value which is scaled from -1 to +1. When operated in single-ended mode (the default), the device outputs an unsigned 12-bit value scaled from 0 to 1.

bus¶: The SPI bus that the device is connected to. As the Pi only has a single (user accessible) SPI bus, this always returns 0.

channel¶: The channel to read data from. The MCP3008/3208/3304 have 8 channels (0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the MCP3301 only has 1 channel.

device¶: The select pin that the device is connected to. The Pi has two select pins so this will be 0 or 1.

differential¶

If True, the device is operated in pseudo-differential mode. In this mode one channel (specified by the channel attribute) is read relative to the value of a second channel (implied by the chip’s design).

Please refer to the device data-sheet to determine which channel is used as the relative base value (for example, when using an MCP3008 in differential mode, channel 0 is read relative to channel 1).

value¶: The current value read from the device, scaled to a value between 0 and 1.