From 3f960f6da3683bba3175eca65728b376c031fd16 Mon Sep 17 00:00:00 2001 From: Ben Nuttall Date: Mon, 28 Sep 2015 11:11:00 +0100 Subject: [PATCH] Update docstrings and add initial set of documentation --- README.rst | 25 ++-- docs/boards.md | 227 +++++++++++++++++++++++++++++++++++++ docs/index.md | 196 +++++++------------------------- docs/inputs.md | 142 +++++++++++++++++++++++ docs/notes.md | 41 +++++++ docs/outputs.md | 119 +++++++++++++++++++ docs/recipes.md | 156 +++++++++++++++++++++++++ gpiozero/boards.py | 88 +++++++------- gpiozero/input_devices.py | 19 ++-- gpiozero/output_devices.py | 123 ++++---------------- mkdocs.yml | 9 +- setup.py | 5 +- 12 files changed, 831 insertions(+), 319 deletions(-) create mode 100644 docs/boards.md create mode 100644 docs/inputs.md create mode 100644 docs/notes.md create mode 100644 docs/outputs.md create mode 100644 docs/recipes.md diff --git a/README.rst b/README.rst index 17e1bf7..44ee232 100644 --- a/README.rst +++ b/README.rst @@ -4,7 +4,7 @@ gpiozero A simple interface to everyday GPIO components used with Raspberry Pi -*A work in progress* +v0.6.0 Public beta Motivation ========== @@ -28,33 +28,38 @@ Install with pip:: sudo pip install gpiozero sudo pip-3.2 install gpiozero +Both Python 3 and Python 2 are supported. Python 3 is recommended! + Usage ===== -Example usage for flashing an LED:: +Example usage for lighting up an LED:: from gpiozero import LED - from time import sleep led = LED(2) - while True: - led.on() - sleep(1) - led.off() - sleep(1) + led.on() + +Documentation +============= + +Comprehensive documentation is available at `pythonhosted.org/gpiozero`_. Development =========== This project is being developed on `GitHub`_. Join in: -* Provide suggestions +* Provide suggestions, report bugs and ask questions as `Issues`_ * Help design the `API`_ * Contribute to the code -Alternatively, email suggestions and feedback to ben@raspberrypi.org +Alternatively, email suggestions and feedback to ben@raspberrypi.org or add to the `Google Doc`_. +.. _`pythonhosted.org/gpiozero`: http://pythonhosted.org/gpiozero +.. _`pythonhosted.org/gpiozero`: http://pythonhosted.org/gpiozero/issues .. _`GitHub`: https://github.com/RPi-Distro/python-gpiozero .. _`API`: https://github.com/RPi-Distro/python-gpiozero/issues/7 +.. _`Google Doc`: https://docs.google.com/document/d/1EbbVjdgXbKVPFlgH_pEEtPZ0zOZVSPHT4sQNW88Am7w/edit?usp=sharing diff --git a/docs/boards.md b/docs/boards.md new file mode 100644 index 0000000..14982b3 --- /dev/null +++ b/docs/boards.md @@ -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 | diff --git a/docs/index.md b/docs/index.md index 7f2fdea..ee11b73 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. diff --git a/docs/inputs.md b/docs/inputs.md new file mode 100644 index 0000000..98969a4 --- /dev/null +++ b/docs/inputs.md @@ -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 + +... diff --git a/docs/notes.md b/docs/notes.md new file mode 100644 index 0000000..bc07893 --- /dev/null +++ b/docs/notes.md @@ -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. diff --git a/docs/outputs.md b/docs/outputs.md new file mode 100644 index 0000000..73af042 --- /dev/null +++ b/docs/outputs.md @@ -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 | diff --git a/docs/recipes.md b/docs/recipes.md new file mode 100644 index 0000000..e130b36 --- /dev/null +++ b/docs/recipes.md @@ -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() +``` diff --git a/gpiozero/boards.py b/gpiozero/boards.py index 150d310..962d283 100644 --- a/gpiozero/boards.py +++ b/gpiozero/boards.py @@ -7,7 +7,7 @@ from time import sleep class LEDBoard(object): """ - A Generic LED Board or collecfion of LEDs. + A Generic LED Board or collection of LEDs. """ def __init__(self, leds): self._leds = tuple(LED(led) for led in leds) @@ -38,38 +38,27 @@ class LEDBoard(object): for led in self._leds: led.toggle() - def blink(self, on_time=1, off_time=1): + def blink(self, on_time=1, off_time=1, n=None, background=True): """ - Make all the LEDs turn on and off repeatedly in the background. + Make all the LEDs turn on and off repeatedly. on_time: 1 Number of seconds to be on off_time: 1 Number of seconds to be off + + n: None + Number of times to blink; None means forever + + background: True + If True, start a background thread to continue blinking and return + immediately. If False, only return when the blink is finished + (warning: the default value of n will result in this method never + returning). """ for led in self._leds: - led.blink(on_time, off_time) - - def flash(self, on_time=1, off_time=1, n=1): - """ - Turn all the LEDs on and off a given number of times. - - on_time: 1 - Number of seconds on - - off_time: 1 - Number of seconds off - - n: 1 - Number of iterations - """ - for i in range(n): - self.on() - sleep(on_time) - self.off() - if i+1 < n: # don't sleep on final iteration - sleep(off_time) + led.blink(on_time, off_time, n, background) class PiLiter(LEDBoard): @@ -116,7 +105,7 @@ class PiTraffic(TrafficLights): class FishDish(TrafficLights): """ - Pi Supply FishDish: horizontal traffic light LEDs, a button and a buzzer. + Pi Supply FishDish: traffic light LEDs, a button and a buzzer. """ def __init__(self): red, amber, green = (9, 22, 4) @@ -151,6 +140,28 @@ class FishDish(TrafficLights): for thing in self._all: thing.toggle() + def blink(self, on_time=1, off_time=1, n=None, background=True): + """ + Make all the board's components turn on and off repeatedly. + + on_time: 1 + Number of seconds to be on + + off_time: 1 + Number of seconds to be off + + n: None + Number of times to blink; None means forever + + background: True + If True, start a background thread to continue blinking and return + immediately. If False, only return when the blink is finished + (warning: the default value of n will result in this method never + returning). + """ + for thing in self._all: + led.blink(on_time, off_time, n, background) + def lights_on(self): """ Turn all the board's LEDs on. @@ -170,30 +181,31 @@ class FishDish(TrafficLights): """ super(FishDish, self).toggle() - def flash_lights(self, on_time=1, off_time=1, n=1): + def blink_lights(self, on_time=1, off_time=1, n=None, background=True): """ - Turn all the LEDs on and off a given number of times. + Make all the board's LEDs turn on and off repeatedly. on_time: 1 - Number of seconds on + Number of seconds to be on off_time: 1 - Number of seconds off + Number of seconds to be off - n: 1 - Number of iterations + n: None + Number of times to blink; None means forever + + background: True + If True, start a background thread to continue blinking and return + immediately. If False, only return when the blink is finished + (warning: the default value of n will result in this method never + returning). """ - for i in range(n): - [led.on() for led in self.leds] - sleep(on_time) - [led.off() for led in self.leds] - if i+1 < n: # don't sleep on final iteration - sleep(off_time) + super(FishDish, self).blink(on_time, off_time, n, background) class TrafficHat(FishDish): """ - Ryanteck Traffic HAT: horizontal traffic light LEDs, a button and a buzzer. + Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer. """ def __init__(self): red, amber, green = (22, 23, 24) diff --git a/gpiozero/input_devices.py b/gpiozero/input_devices.py index 2fa6595..adb035b 100644 --- a/gpiozero/input_devices.py +++ b/gpiozero/input_devices.py @@ -14,7 +14,8 @@ from .devices import GPIODeviceError, GPIODevice, GPIOQueue def _alias(key): return property( lambda self: getattr(self, key), - lambda self, val: setattr(self, key, val)) + lambda self, val: setattr(self, key, val) + ) class InputDeviceError(GPIODeviceError): @@ -28,12 +29,12 @@ class InputDevice(GPIODevice): def __init__(self, pin=None, pull_up=False): super(InputDevice, self).__init__(pin) self._pull_up = pull_up - self._active_edge = (GPIO.RISING, GPIO.FALLING)[pull_up] - self._inactive_edge = (GPIO.FALLING, GPIO.RISING)[pull_up] - if pull_up: - self._active_state = GPIO.LOW - self._inactive_state = GPIO.HIGH - GPIO.setup(pin, GPIO.IN, (GPIO.PUD_DOWN, GPIO.PUD_UP)[pull_up]) + self._active_edge = GPIO.FALLING if pull_up else GPIO.RISING + self._inactive_edge = GPIO.RISING if pull_up else GPIO.FALLING + self._active_state = GPIO.LOW if pull_up else GPIO.HIGH + self._inactive_state = GPIO.HIGH if pull_up else GPIO.LOW + pull = GPIO.PUD_UP if pull_up else GPIO.PUD_DOWN + GPIO.setup(pin, GPIO.IN, pull) @property def pull_up(self): @@ -46,7 +47,7 @@ class InputDevice(GPIODevice): class WaitableInputDevice(InputDevice): """ - A time-dependent Generic Input Device. + An action-dependent Generic Input Device. """ def __init__(self, pin=None, pull_up=False): super(WaitableInputDevice, self).__init__(pin, pull_up) @@ -216,6 +217,8 @@ class Button(DigitalInputDevice): def __init__(self, pin=None, pull_up=True, bouncetime=None): super(Button, self).__init__(pin, pull_up, bouncetime) + is_pressed = alias('is_active') + when_pressed = _alias('when_activated') when_released = _alias('when_deactivated') diff --git a/gpiozero/output_devices.py b/gpiozero/output_devices.py index d79e395..3a87b8a 100644 --- a/gpiozero/output_devices.py +++ b/gpiozero/output_devices.py @@ -34,7 +34,7 @@ class OutputDevice(GPIODevice): class DigitalOutputDevice(OutputDevice): """ - Generic Digital GPIO Output Device (on/off/blink/toggle/flash). + Generic Digital GPIO Output Device (on/off/toggle/blink). """ def __init__(self, pin=None): super(DigitalOutputDevice, self).__init__(pin) @@ -55,9 +55,20 @@ class DigitalOutputDevice(OutputDevice): self._stop_blink() super(DigitalOutputDevice, self).off() + def toggle(self): + """ + Reverse the state of the device. + If it's on, turn it off; if it's off, turn it on. + """ + with self._lock: + if self.is_active: + self.off() + else: + self.on() + def blink(self, on_time=1, off_time=1, n=None, background=True): """ - Make the device turn on and off repeatedly in the background. + Make the device turn on and off repeatedly. on_time: 1 Number of seconds on @@ -83,17 +94,6 @@ class DigitalOutputDevice(OutputDevice): self._blink_thread.join() self._blink_thread = None - def toggle(self): - """ - Reverse the state of the device. - If it's on, turn it off; if it's off, turn it on. - """ - with self._lock: - if self.is_active: - self.off() - else: - self.on() - def _stop_blink(self): if self._blink_thread: self._blink_thread.stop() @@ -114,104 +114,21 @@ class LED(DigitalOutputDevice): """ An LED (Light Emmitting Diode) component. """ - def on(self): - """ - Turn the LED on. - """ - super(LED, self).on() - - def off(self): - """ - Turn the LED off. - """ - super(LED, self).off() - - def blink(self, on_time=1, off_time=1, n=None, background=True): - """ - Make the LED turn on and off repeatedly in the background. - - on_time: 1 - Number of seconds on - - off_time: 1 - Number of seconds off - - n: None - Number of times to blink; None means forever - - background: True - If True, start a background thread to continue blinking and return - immediately. If False, only return when the blink is finished - (warning: the default value of n will result in this method never - returning). - """ - super(LED, self).blink(on_time, off_time, n, background) - - def toggle(self): - """ - Reverse the state of the LED. - If it's on, turn it off; if it's off, turn it on. - """ - super(LED, self).toggle() + pass class Buzzer(DigitalOutputDevice): """ - A Buzzer component. + A digital Buzzer component. """ - def on(self): - """ - Turn the Buzzer on. - """ - super(Buzzer, self).on() - - def off(self): - """ - Turn the Buzzer off. - """ - super(Buzzer, self).off() - - def blink(self, on_time=1, off_time=1, n=None, background=True): - """ - Make the Buzzer turn on and off repeatedly in the background. - - on_time: 1 - Number of seconds on - - off_time: 1 - Number of seconds off - - n: None - Number of times to blink; None means forever - - background: True - If True, start a background thread to continue blinking and return - immediately. If False, only return when the blink is finished - (warning: the default value of n will result in this method never - returning). - """ - super(Buzzer, self).blink(on_time, off_time, n, background) - - def toggle(self): - """ - Reverse the state of the Buzzer. - If it's on, turn it off; if it's off, turn it on. - """ - super(Buzzer, self).toggle() + pass class Motor(OutputDevice): - def on(self): - """ - Turns the Motor on. - """ - super(Motor, self).toggle() - - def off(self): - """ - Turns the Motor off. - """ - super(Motor, self).toggle() + """ + Generic single-direction motor. + """ + pass class Robot(object): diff --git a/mkdocs.yml b/mkdocs.yml index e0e135b..0964442 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,10 +1,15 @@ -site_name: gpio-zero +site_name: GPIO Zero theme: readthedocs site_url: http://pythonhosted.org/gpiozero -repo_url: https://github.com/RPi-Distro/gpio-zero +repo_url: https://github.com/RPi-Distro/python-gpiozero site_description: A simple interface to everyday GPIO components used with Raspberry Pi site_author: Ben Nuttall site_dir: pythonhosted google_analytics: ['UA-46270871-6', 'pythonhosted.org/gpiozero'] pages: - 'Home': 'index.md' +- 'Input Devices': 'inputs.md' +- 'Output Devices': 'outputs.md' +- 'Boards and Accessories': 'boards.md' +- 'Notes': 'notes.md' +- 'Recipes': 'recipes.md' diff --git a/setup.py b/setup.py index 01dac5d..80bbf92 100644 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ def read(fname): setup( name="gpiozero", - version="0.5.0", + version="0.6.0", author="Ben Nuttall", description="A simple interface to everyday GPIO components used with Raspberry Pi", license="BSD", @@ -24,8 +24,9 @@ setup( ], long_description=read('README.rst'), classifiers=[ - "Development Status :: 3 - Alpha", + "Development Status :: 4 - Beta", "Intended Audience :: Education", + "Intended Audience :: Developers", "Topic :: Education", "Topic :: System :: Hardware", "License :: OSI Approved :: BSD License",