python-gpiozero/docs/inputs.md

Input Devices

These input device component interfaces have been provided for simple use of everyday components.

Components must be wired up correctly before used in code.

Note all GPIO pin numbers use BCM numbering. See the notes page for more information.

Button

A physical push button or switch.

Wiring

Connect one side of the button to a ground pin, and the other to any GPIO pin:

Alternatively, connect to 3V3 and to a GPIO, and set pull_up to False when you create your Button object.

Code

Ensure the Button class is imported at the top of the file:

from gpiozero import Button

Create a Button object by passing in the pin number the button is connected to:

button = Button(2)

Initialisation options

Button(pin=None, pull_up=True, bounce_time=None)

Argument	Description	Values	Default
pin	The GPIO pin number the button is connected to.	Integer	Required
pull_up	The pull state of the pin. True means pull up, False means pull down.	Boolean	True
bounce_time	Specifies the length of time (in seconds) that the component will ignore changes in state after an initial change.	Integer or Float	None

Methods

Method	Description	Arguments
wait_for_press()	Halt the program until the button is pressed.	timeout - The number of seconds to wait before proceeding if no event is detected. Default: None
wait_for_release()	Halt the program until the button is released.	timeout - The number of seconds to wait before proceeding if no event is detected. Default: None

Properties

Property	Description	Type
pin	The GPIO pin number the button is connected to.	Integer
is_pressed	The current state of the pin (True if pressed; otherwise False).	Boolean
pull_up	The pull state of the pin (True if pulled up; False if pulled down).	Boolean
when_pressed	A reference to the function to be called when the button is pressed.	None or Function
when_released	A reference to the function to be called when the button is released.	None or Function
value	The current value of the button. 0 if off; 1 if on.	Float
values	A generator continuously yielding the button's current value.	Generator

Motion Sensor

A PIR (Passive Infra-Red) motion sensor.

Wiring

Connect the pin labelled VCC to a 5V pin; connect the one labelled GND to a ground pin; and connect the one labelled OUT to any GPIO pin:

Code

Ensure the MotionSensor class is imported at the top of the file:

from gpiozero import MotionSensor

Create a MotionSensor object by passing in the pin number the sensor is connected to:

pir = MotionSensor(4)

Initialisation options

MotionSensor(pin=None, queue_len=1, sample_rate=10, threshold=0.5, partial=False)

Argument	Description	Values	Default
pin	The GPIO pin number the sensor is connected to.	Integer	Required
queue_len	???	Integer	1
sample_rate	???	Integer	10
threshold	Proportion of sensor values required to determine motion state.	Float: 0 to 1	0.5
partial	???	Boolean	False

Methods

Method	Description	Arguments
wait_for_motion()	Halt the program until motion is detected.	timeout - The number of seconds to wait before proceeding if no motion is detected. Default: None
wait_for_no_motion()	Halt the program until no motion is detected.	timeout - The number of seconds to wait before proceeding if motion is still detected. Default: None

Properties

Property	Description	Type
pin	The GPIO pin number the sensor is connected to.	Integer
motion_detected	The current state of the sensor (True if motion is detected; otherwise False).	Boolean
when_motion	A reference to the function to be called when motion is detected.	None or Function
when_no_motion	A reference to the function to be called when no motion is detected.	None or Function
value	The current value of the sensor. 0 if still; 1 if motion.	Float
values	A generator continuously yielding the sensor's current value.	Generator

Light Sensor

An LDR (Light Dependent Resistor) Light Sensor.

Wiring

...

Code

Ensure the LightSensor class is imported at the top of the file:

from gpiozero import LightSensor

Create a LightSensor object by passing in the pin number the sensor is connected to:

light = LightSensor(4)

Initialisation options

LightSensor(pin=None, queue_len=5, charge_time_limit=10,
    threshold=0.1, partial=False)

Argument	Description	Values	Default
pin	The GPIO pin number the sensor is connected to.	Integer	Required
queue_len	???	Integer	5
charge_time_limit	Maximum amount of time allowed to determine darkness.	Integer	10
threshold	Proportion of sensor values required to determine light level.	Float: 0 to 1	0.1
partial	???	Boolean	False

Methods

Method	Description	Arguments
wait_for_light()	Halt the program until light is detected.	timeout - The number of seconds to wait before proceeding if light is not detected. Default: None
wait_for_dark()	Halt the program until darkness is detected.	timeout - The number of seconds to wait before proceeding if darkness is not detected. Default: None

Properties

Property	Description	Type
pin	The GPIO pin number the sensor is connected to.	Integer
light_detected	The current state of the sensor (True if light; otherwise False).	Boolean
when_light	A reference to the function to be called when light is detected.	None or Function
when_dark	A reference to the function to be called when darkness is detected.	None or Function
value	The current value of the sensor. 0 if dark; 1 if light.	Float
values	A generator continuously yielding the sensor's current value.	Generator

MCP3008 Analogue-to-Digital Converter

MCP3008 ADC (Analogue-to-Digital converter).

The MCP3008 chip provides access to up to 8 analogue inputs, such as potentiometers, and reads their values in digital form.

Wiring

...

Code

Ensure the MCP3008 class is imported at the top of the file:

from gpiozero import MCP3008

Create an MCP3008 object:

pot = MCP3008()

Alternatively, access an input value with the MCP3008's context manager:

with MCP3008() as pot:
    # do something with pot

Initialisation options

MCP3008(channel=0, device=0)

Argument	Description	Values	Default
channel	Which of the 8 ADC channels to access.	Integer: 0 to 7	0
device	Which of the two Chip Select SPI pins to access.	Integer: 0 or 1	0

Properties

Property	Description	Type
channel	The ADC channel the device is connected to.	Integer
device	The chip select pin the device is connected to.	Integer
value	The current value of the device.	Float
values	A generator continuously yielding the device's current value.	Generator

MCP3004 Analogue-to-Digital Converter

MCP3004 ADC (Analogue-to-Digital converter).

The MCP3004 chip provides access to up to 4 analogue inputs, such as potentiometers, and reads their values in digital form.

The interface is identical to MCP3008, except that only channels 0 to 3 are accessible.