KevinMidboe/python-gpiozero
1
0
Fork 0
mirror of https://github.com/KevinMidboe/python-gpiozero.git synced 2025-12-08 20:39:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docstrings and add initial set of documentation

Browse Source
This commit is contained in:
Ben Nuttall
2015-09-28 11:11:00 +01:00
parent a38ab6cd45
commit 3f960f6da3
12 changed files with 831 additions and 319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
docs/boards.md Normal file
View File

@@ -0,0 +1,227 @@
# Add-on boards and accessories
These additional interfaces have been provided to group collections of components together for ease of use, and as examples. They are made up of components from the various [input devices](inputs.md) and [output devices](outputs.md) provided by `gpiozero`. See those pages for more information on using components individually.
*Note all GPIO pin numbers use BCM numbering. See the [notes](notes.md) page for more information.*
## LED Board
A Generic LED Board or collection of LEDs.
Ensure the `LEDBoard` class is imported at the top of the file:
```python
from gpiozero import LEDBoard
```
Create an `LEDBoard` object by passing in a list of the LED pin numbers:
```python
leds = LEDBoard([2, 3, 4, 5, 6])
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all the LEDs on. | None |
| `off()` | Turn all the LEDs off. | None |
| `toggle()` | Toggle all the LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all the LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
## Traffic Lights
Generic Traffic Lights set.
Ensure the `TrafficLights` class is imported at the top of the file:
```python
from gpiozero import TrafficLights
```
Create a `TrafficLights` object by passing in the LED pin numbers by name:
```python
traffic = TrafficLights(red=2, amber=3, green=4)
```
or just in order (red, amber, green):
```python
traffic = TrafficLights(2, 3, 4)
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all three LEDs on. | None |
| `off()` | Turn all three LEDs off. | None |
| `toggle()` | Toggle all three LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all three LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `amber` | Direct access to the amber light as a single `LED` object. | LED |
| `green` | Direct access to the green light as a single `LED` object. | LED |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
## PiLITEr
Ciseco Pi-LITEr: strip of 8 very bright LEDs.
Ensure the `PiLiter` class is imported at the top of the file:
```python
from gpiozero import PiLiter
```
Create a `PiLiter` object:
```python
lite = PiLiter()
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all eight LEDs on. | None |
| `off()` | Turn all eight LEDs off. | None |
| `toggle()` | Toggle all eight LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all eight LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
## PI-TRAFFIC
Low Voltage Labs PI-TRAFFIC: vertical traffic lights board on pins 9, 10 and 11.
Ensure the `PiTraffic` class is imported at the top of the file:
```python
from gpiozero import PiTraffic
```
Create a `PiTraffic` object:
```python
traffic = PiTraffic()
```
`PiTraffic` provides an identical interface to the generic `TrafficLights` interface, without the need to specify the pin numbers to be used.
To use the PI-TRAFFIC board on another set of pins, just use the generic `TrafficLights` interface.
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all three LEDs on. | None |
| `off()` | Turn all three LEDs off. | None |
| `toggle()` | Toggle all three LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all three LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `amber` | Direct access to the amber light as a single `LED` object. | LED |
| `green` | Direct access to the green light as a single `LED` object. | LED |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
## Fish Dish
Pi Supply Fish Dish: traffic light LEDs, a button and a buzzer.
Ensure the `FishDish` class is imported at the top of the file:
```python
from gpiozero import FishDish
```
Create a `FishDish` object:
```python
fish = FishDish()
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all the board's output components on. | None |
| `off()` | Turn all the board's output components off. | None |
| `toggle()` | Toggle all the board's output components. For each component, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all the board's output components turn on and off repeatedly. | `on_time=1`, `off_time=1`, `nx=1`, `background=True` |
| `lights_on()` | Turn all three LEDs on. | None |
| `lights_off()` | Turn all three LEDs off. | None |
| `toggle_lights()` | Toggle all the board's LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink_lights()` | Make all the board's LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `amber` | Direct access to the amber light as a single `LED` object. | LED |
| `green` | Direct access to the green light as a single `LED` object. | LED |
| `buzzer` | Direct access to the buzzer as a single `Buzzer` object. | LED |
| `button` | Direct access to the button as a single `Button` object. | LED |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
| `all` | A collection of the board's output components to access each one individually, or to iterate over them in sequence. | Tuple |
## Traffic HAT
Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer.
Ensure the `TrafficHat` class is imported at the top of the file:
```python
from gpiozero import TrafficHat
```
Create a `TrafficHat` object by passing in the LED pin numbers by name:
```python
traffic = TrafficHat()
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all the board's output components on. | None |
| `off()` | Turn all the board's output components off. | None |
| `toggle()` | Toggle all the board's output components. For each component, if it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make all the board's output components turn on and off repeatedly. | `on_time=1`, `off_time=1`, `nx=1`, `background=True` |
| `lights_on()` | Turn all three LEDs on. | None |
| `lights_off()` | Turn all three LEDs off. | None |
| `toggle_lights()` | Toggle all the board's LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
| `blink_lights()` | Make all the board's LEDs turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `amber` | Direct access to the amber light as a single `LED` object. | LED |
| `green` | Direct access to the green light as a single `LED` object. | LED |
| `buzzer` | Direct access to the buzzer as a single `Buzzer` object. | LED |
| `button` | Direct access to the button as a single `Button` object. | LED |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
| `all` | A collection of the board's output components to access each one individually, or to iterate over them in sequence. | Tuple |

196
docs/index.md
View File

@@ -1,8 +1,12 @@
# gpio-zero
# GPIO Zero
A simple interface to everyday GPIO components used with Raspberry Pi
## Why?
## Latest release
The latest release is **v0.6.0 public beta 1** released on 28th September 2015.
## Motivation
The "hello world" program in Java is at least 5 lines long, and contains 11
jargon words which are to be ignored. The "hello world" program in Python is
@@ -39,7 +43,30 @@ red.on()
Any guesses how to turn it off?
## Implemented Components
## Install
Install with pip::
```bash
sudo apt-get install python-pip python3-pip
sudo pip install gpiozero
sudo pip-3.2 install gpiozero
```
Both Python 3 and Python 2 are supported. Python 3 is recommended!
### Upgrade
Upgrade to the latest version with:
```bash
sudo pip install gpiozero --upgrade
sudo pip-3.2 install gpiozero --upgrade
```
## What's included?
Components:
- LED
- Buzzer
@@ -49,160 +76,17 @@ Any guesses how to turn it off?
- Temperature Sensor
- Motor
## Usage
Boards & accessories:
### LED
- LED Board
- Traffic Lights
- PiLITEr
- PI-TRAFFIC
- Fish Dish
- Traffic HAT
Turn an LED on and off repeatedly:
## Getting started
```python
from gpiozero import LED
from time import sleep
red = LED(2)
while True:
red.on()
sleep(1)
red.off()
sleep(1)
```
Alternatively:
```python
from gpiozero import LED
red = LED(2)
red.blink(1, 1)
sleep(10)
```
### Buzzer
Turn a buzzer on and off repeatedly:
```python
from gpiozero import Buzzer
from time import sleep
buzzer = Buzzer(3)
while True:
buzzer.on()
sleep(1)
buzzer.off()
sleep(1)
```
### Button
Check if a button is pressed:
```python
from gpiozero import Button
button = Button(4)
if button.is_active:
print("Button is pressed")
else:
print("Button is not pressed")
```
Wait for a button to be pressed before continuing:
```python
from gpiozero import Button
button = Button(4)
button.wait_for_press()
print("Button was pressed")
```
Run a function every time the button is pressed:
```python
from gpiozero import Button
def warning():
print("Don't push the button!")
button = Button(4)
button.when_pressed = warning
```
### Motion Sensor
Detect motion and light an LED when it's detected:
```python
from gpiozero import MotionSensor, LED
pir = MotionSensor(5)
led = LED(16)
pir.when_motion = led.on
pir.when_no_motion = led.off
```
### Light Sensor
Wait for light and dark:
```python
from gpiozero import LightSensor
sensor = LightSensor(18)
while True:
sensor.wait_for_light()
print("It's light! :)")
sensor.wait_for_dark()
print("It's dark :(")
```
Run a function when the light changes:
```python
from gpiozero import LightSensor, LED
sensor = LightSensor(18)
led = LED(16)
sensor.when_dark = led.on
sensor.when_light = led.off
```
### Temperature Sensor
Retrieve light sensor value:
```python
from gpiozero import TemperatureSensor
temperature = TemperatureSensor(6)
print(temperature.value)
```
### Motor
Drive two motors forwards for 5 seconds:
```python
from gpiozero import Motor
from time import sleep
left_motor = Motor(7)
right_motor = Motor(8)
left_motor.on()
right_motor.on()
sleep(5)
left_motor.off()
right_motor.off()
```
See the [input devices](inputs.md) and [output devices](outputs.md) to get started. Also see the [boards & accessories](boards.md) page for examples of using the included accessories.
For common programs using multiple components together, see the [recipes](recipes.md) page.

142
docs/inputs.md Normal file
View File

@@ -0,0 +1,142 @@
# 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](notes.md) page for more information.*
## Button
A physical push button or switch.
### Wiring
...
### Code
Ensure the `Button` class is imported at the top of the file:
```python
from gpiozero import Button
```
Create a `Button` object by passing in the pin number the button is connected to:
```python
button = Button(2)
```
The default bahaviour is to set the *pull* state of the button to *up*. To change this behaviour, set the `pull_up` argument to `False` when creating your `Button` object.
```python
button = Button(pin=2, pull_up=False)
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `wait_for_press()` | Halt the program until the button is pressed. | `timeout=None` |
| `wait_for_release()` | Halt the program until the button is released. | `timeout=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 |
## Motion Sensor
A PIR (Passive Infra-Red) motion sensor.
### Wiring
...
### Code
Ensure the `MotionSensor` class is imported at the top of the file:
```python
from gpiozero import MotionSensor
```
Create a `MotionSensor` object by passing in the pin number the sensor is connected to:
```python
pir = MotionSensor(3)
```
### Methods
...
### Properties
...
## Light Sensor
An LDR (Light Dependent Resistor) Light Sensor.
### Wiring
...
### Code
Ensure the `LightSensor` class is imported at the top of the file:
```python
from gpiozero import LightSensor
```
Create a `LightSensor` object by passing in the pin number the sensor is connected to:
```python
light = LightSensor(4)
```
### Methods
...
### Properties
...
## Temperature Sensor
Digital Temperature Sensor.
### Wiring
...
### Code
Ensure the `TemperatureSensor` class is imported at the top of the file:
```python
from gpiozero import TemperatureSensor
```
Create a `TemperatureSensor` object:
```python
temp = TemperatureSensor()
```
### Properties
...
### Methods
...

41
docs/notes.md Normal file
View File

@@ -0,0 +1,41 @@
# Notes
1. BCM pin numbering
This library uses BCM pin numbering for the GPIO pins, as opposed to BOARD. Unlike the `RPi.GPIO` library, it is not configurable.
Any pin marked `GPIO` can be used for generic components.
The BCM pin layout is as follows:
| | |
|-----------:|:-----------|
| 3V3 | 5V |
| **GPIO2** | 5V |
| **GPIO3** | GND |
| **GPIO4** | **GPIO14** |
| GND | **GPIO15** |
| **GPIO17** | **GPIO18** |
| **GPIO27** | GND |
| **GPIO22** | **GPIO23** |
| 3V3 | **GPIO24** |
| **GPIO10** | GND |
| **GPIO9** | **GPIO25** |
| **GPIO11** | **GPIO8** |
| GND | **GPIO7** |
| DNC | DNC |
| **GPIO5** | GND |
| **GPIO6** | **GPIO12** |
| **GPIO13** | GND |
| **GPIO19** | **GPIO16** |
| **GPIO26** | **GPIO20** |
| GND | **GPIO21** |
- *GND = Ground*
- *3V3 = 3.3 Volts*
- *5V = 5 Volts*
- *DNC = Do not connect (special use pins)*
1. Wiring
All components must be wired up correctly before using with this library.

119
docs/outputs.md Normal file
View File

@@ -0,0 +1,119 @@
# Output Devices
These output 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](notes.md) page for more information.*
## LED
An LED (Light emitting diode) component.
### Wiring
...
### Code
Ensure the `LED` class is imported at the top of the file:
```python
from gpiozero import LED
```
Create an `LED` object by passing in the pin number the LED is connected to:
```python
led = LED(2)
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn the LED on. | None |
| `off()` | Turn the LED off. | None |
| `toggle()` | Toggle the LED. If it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make the LED turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `pin` | The GPIO pin number the LED is connected to. | Integer |
| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
## Buzzer
A digital Buzzer component.
### Wiring
...
### Code
Ensure the `Buzzer` class is imported at the top of the file:
```python
from gpiozero import Buzzer
```
Create a `Buzzer` object by passing in the pin number the buzzer is connected to:
```python
buzzer = Buzzer(3)
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn the buzzer on. | None |
| `off()` | Turn the buzzer off. | None |
| `toggle()` | Toggle the buzzer. If it's on, turn it off; if it's off, turn it on. | None |
| `blink()` | Make the buzzer turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `pin` | The GPIO pin number the buzzer is connected to. | Integer |
| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
## Motor
Generic single-direction motor.
### Wiring
...
### Code
Ensure the `Motor` class is imported at the top of the file:
```python
from gpiozero import Motor
```
Create a `Motor` object by passing in the pin number the motor is connected to:
```python
motor = Motor(4)
```
### Methods
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn the motor on. | None |
| `off()` | Turn the motor off. | None |
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `pin` | The GPIO pin number the motor is connected to. | Integer |
| `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |

156
docs/recipes.md Normal file
View File

@@ -0,0 +1,156 @@
# Recipes
## LED
Turn an LED on and off repeatedly:
```python
from gpiozero import LED
from time import sleep
red = LED(2)
while True:
red.on()
sleep(1)
red.off()
sleep(1)
```
Alternatively:
```python
from gpiozero import LED
red = LED(2)
red.blink()
```
## Buzzer
Turn a buzzer on and off repeatedly:
```python
from gpiozero import Buzzer
from time import sleep
buzzer = Buzzer(3)
while True:
buzzer.on()
sleep(1)
buzzer.off()
sleep(1)
```
## Button
Check if a button is pressed:
```python
from gpiozero import Button
button = Button(4)
if button.is_active:
print("Button is pressed")
else:
print("Button is not pressed")
```
Wait for a button to be pressed before continuing:
```python
from gpiozero import Button
button = Button(4)
button.wait_for_press()
print("Button was pressed")
```
Run a function every time the button is pressed:
```python
from gpiozero import Button
def warning():
print("Don't push the button!")
button = Button(4)
button.when_pressed = warning
```
## Motion Sensor
Detect motion and light an LED when it's detected:
```python
from gpiozero import MotionSensor, LED
pir = MotionSensor(5)
led = LED(16)
pir.when_motion = led.on
pir.when_no_motion = led.off
```
## Light Sensor
Wait for light and dark:
```python
from gpiozero import LightSensor
sensor = LightSensor(18)
while True:
sensor.wait_for_light()
print("It's light! :)")
sensor.wait_for_dark()
print("It's dark :(")
```
Run a function when the light changes:
```python
from gpiozero import LightSensor, LED
sensor = LightSensor(18)
led = LED(16)
sensor.when_dark = led.on
sensor.when_light = led.off
```
## Temperature Sensor
Retrieve light sensor value:
```python
from gpiozero import TemperatureSensor
temperature = TemperatureSensor(6)
print(temperature.value)
```
## Motor
Drive two motors forwards for 5 seconds:
```python
from gpiozero import Motor
from time import sleep
left_motor = Motor(7)
right_motor = Motor(8)
left_motor.on()
right_motor.on()
sleep(5)
left_motor.off()
right_motor.off()
```