KevinMidboe/python-gpiozero
1
0
Fork 0
mirror of https://github.com/KevinMidboe/python-gpiozero.git synced 2025-10-29 17:50:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs updates: add installing, advanced recipes, remote gpio and remote recipes - wip

Browse Source
This commit is contained in:
Ben Nuttall
2017-01-10 09:43:53 +00:00
parent ed12ac1994
commit dea7ba6ec2
19 changed files with 578 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/examples/led_button_remote_1.py Normal file
View File

@@ -0,0 +1,10 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from signal import pause
button = Button(2)
led = LED(PiGPIOPin(17, host='192.168.1.3'))
led.source = button.values
pause()

12
docs/examples/led_button_remote_2.py Normal file
View File

@@ -0,0 +1,12 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from gpiozero.tools import all_values
from signal import pause
led = LED(17)
button_1 = Button(PiGPIOPin(17, host='192.168.1.3'))
button_2 = Button(PiGPIOPin(17, host='192.168.1.4'))
led.source = all_values(button_1.values, button_2.values)
pause()

11
docs/examples/led_remote_1.py Normal file
View File

@@ -0,0 +1,11 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from time import sleep
led = LED(PiGPIOPin(17, host='192.168.1.3'))
while True:
led.on()
sleep(1)
led.off()
sleep(1)

14
docs/examples/led_remote_2.py Normal file
View File

@@ -0,0 +1,14 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from time import sleep
led_1 = LED(PiGPIOPin(17, host='192.168.1.3'))
led_2 = LED(PiGPIOPin(17, host='192.168.1.4'))
while True:
led_1.on()
led_2.off()
sleep(1)
led_1.off()
led_2.on()
sleep(1)

14
docs/examples/led_remote_3.py Normal file
View File

@@ -0,0 +1,14 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from time import sleep
led_1 = LED(17) # local pin
led_2 = LED(PiGPIOPin(17, host='192.168.1.3')) # remote pin
while True:
led_1.on()
led_2.off()
sleep(1)
led_1.off()
led_2.on()
sleep(1)

14
docs/examples/led_remote_4.py Normal file
View File

@@ -0,0 +1,14 @@
from gpiozero import LED
from gpiozero.pins.rpigpio import RPiGPIOPin
from time import sleep
led_1 = LED(RPiGPIOPin(17)) # local pin
led_2 = LED(17) # remote pin
while True:
led_1.on()
led_2.off()
sleep(1)
led_1.off()
led_2.on()
sleep(1)

17
docs/examples/led_remote_5.py Normal file
View File

@@ -0,0 +1,17 @@
from gpiozero import LED
from gpiozero.pins.pigpio import PiGPIOPin
from time import sleep
led_1 = LED(17) # local pin
led_2 = LED(PiGPIOPin(17, host='192.168.1.3')) # remote pin on one pi
led_3 = LED(PiGPIOPin(17, host='192.168.1.4')) # remote pin on another pi
while True:
led_1.on()
led_2.off()
led_3.on()
sleep(1)
led_1.off()
led_2.on()
led_3.off()
sleep(1)

14
docs/examples/multi_room_doorbell.py Normal file
View File

@@ -0,0 +1,14 @@
from gpiozero import Buzzer, Button
from gpiozero.pins.pigpio import PiGPIOPin
from signal import pause
ips = ['192.168.1.3', '192.168.1.4', '192.168.1.5', '192.168.1.6']
remote_pins = [PiGPIOPin(17, host=ip) for ip in ips]
button = Button(17) # button on this pi
buzzers = [Buzzer(pin) for pin in remote_pins] # buzzers on remote pins
for buzzer in buzzers:
buzzer.source = button.values
pause()

14
docs/examples/multi_room_motion_alert.py Normal file
View File

@@ -0,0 +1,14 @@
from gpiozero import LEDBoard, MotionSensor
from gpiozero.pins.pigpio import PiGPIOPin
from signal import pause
ips = ['192.168.1.3', '192.168.1.4', '192.168.1.5', '192.168.1.6']
remote_pins = [PiGPIOPin(17, host=ip) for ip in ips]
leds = LEDBoard(2, 3, 4, 5) # leds on this pi
sensors = [MotionSensor(pin) for pin in remote_pins] # motion sensors on other pis
for led, sensor in zip(leds, sensors):
led.source = sensor.values
pause()

7
docs/examples/traffichat_remote_1.py Normal file
View File

@@ -0,0 +1,7 @@
import gpiozero
from gpiozero import TrafficHat
from gpiozero.pins.pigpio import PiGPIOFactory
from time import sleep
gpiozero.Device._set_pin_factory(PiGPIOFactory(host='192.168.1.3'))
th = TrafficHat() # traffic hat on 192.168.1.3 using remote pins

8
docs/examples/traffichat_remote_2.py Normal file
View File

@@ -0,0 +1,8 @@
import gpiozero
from gpiozero import TrafficHat
from gpiozero.pins.pigpio import PiGPIOFactory
from time import sleep
th_1 = TrafficHat() # traffic hat using local pins
gpiozero.Device._set_pin_factory(PiGPIOFactory(host='192.168.1.3'))
th_2 = TrafficHat() # traffic hat on 192.168.1.3 using remote pins

3
docs/index.rst
View File

@@ -7,6 +7,7 @@ Table of Contents
:maxdepth: 2
recipes
recipes_remote_gpio
notes
contributing
api_input
@@ -18,7 +19,7 @@ Table of Contents
api_tools
api_pins
api_exc
remote_gpio
source_values
changelog
license

82
docs/installing.rst Normal file
View File

@@ -0,0 +1,82 @@
====================
Installing GPIO Zero
====================
GPIO Zero is installed by default in `Raspbian Jessie`_ and `PIXEL x86`_, available
from `raspberrypi.org`_. Follow these guides to installing on other operating
systems, including for PCs using the :doc:`remote_gpio` feature.
Raspberry Pi
============
First, update your repositories list::
sudo apt-get update
Then install the package for Python 3::
sudo apt-get install python3-gpiozero
or Python 2::
sudo apt-get install python-gpiozero
Linux
=====
First, update your distribution's repositories list. For example::
sudo apt-get update
Then install pip for Python 3::
sudo apt-get install python3-pip
or Python 3::
sudo apt-get install python-pip
(Alternatively, install pip with `get-pip`_.)
Next, install gpiozero for Python 3::
sudo pip3 install gpiozero
or Python 2::
sudo pip install gpiozero
.. note::
We welcome Linux distribution maintainers to include the gpiozero packages
in their repositories. Any questions you have, please ask questions on
`GitHub`_ and we'll be happy to help.
Mac OS
======
First, install pip::
???
Next, install gpiozero with pip::
pip install gpiozero
Windows
=======
First, install pip::
???
Next, install gpiozero with pip::
pip install gpiozero
.. Raspbian Jessie_: https://www.raspberrypi.org/downloads/raspbian/
.. PIXEL x86_: https://www.raspberrypi.org/blog/pixel-pc-mac/
.. raspberrypi.org_: https://www.raspberrypi.org/downloads/
.. get-pip_: https://pip.pypa.io/en/stable/installing/
.. GitHub: https://github.com/RPi-Distro/python-gpiozero/issues

5
docs/notes.rst
View File

@@ -35,7 +35,6 @@ manually (e.g. by pressing Ctrl+C). Similarly, when setting up callbacks on
button presses or other input devices, the script needs to be running for the
events to be detected::
from gpiozero import Button
from signal import pause
@@ -93,3 +92,7 @@ the ``pip`` utility. This can be done with the following command in Raspbian::
$ sudo apt-get install python-pip
Alternatively, install pip with `get-pip`_.
.. get_pip: https://pip.pypa.io/en/stable/installing/

92
docs/recipes.rst
View File

@@ -1,14 +1,13 @@
=======
Recipes
=======
================
Recipes (Simple)
================
.. currentmodule:: gpiozero
The following recipes demonstrate some of the capabilities of the gpiozero
The following recipes demonstrate some of the capabilities of the GPIO Zero
library. Please note that all recipes are written assuming Python 3. Recipes
*may* work under Python 2, but no guarantees!
.. _pin_numbering:
Pin Numbering
@@ -26,7 +25,6 @@ example, if an LED was attached to "GPIO17" you would specify the pin number as
.. image:: images/pin_layout.*
LED
===
@@ -46,7 +44,6 @@ Alternatively:
may be reset. Keep your script alive with :func:`signal.pause`. See
:ref:`keep-your-script-running` for more information.
LED with variable brightness
============================
@@ -61,7 +58,6 @@ out continuously):
.. literalinclude:: examples/led_pulse.py
Button
======
@@ -93,7 +89,6 @@ Similarly, functions can be attached to button releases:
.. literalinclude:: examples/button_4.py
Button controlled LED
=====================
@@ -107,7 +102,6 @@ Alternatively:
.. literalinclude:: examples/button_led_2.py
Button controlled camera
========================
@@ -125,7 +119,6 @@ another to capture:
.. literalinclude:: examples/button_camera_2.py
Shutdown button
===============
@@ -135,7 +128,6 @@ the Raspberry Pi when the button is held for 2 seconds:
.. literalinclude:: examples/button_shutdown.py
LEDBoard
========
@@ -148,7 +140,6 @@ controlled:
.. literalinclude:: examples/led_board_2.py
LEDBarGraph
===========
@@ -165,7 +156,6 @@ values using LED brightness:
.. literalinclude:: examples/led_bargraph_2.py
Traffic Lights
==============
@@ -185,19 +175,6 @@ Using :class:`LED` components:
.. literalinclude:: examples/traffic_lights_3.py
Travis build LED indicator
==========================
Use LEDs to indicate the status of a Travis build. A green light means the
tests are passing, a red light means the build is broken:
.. literalinclude:: examples/led_travis.py
Note this recipe requires `travispy`_. Install with ``sudo pip3 install
travispy``.
Push button stop motion
=======================
@@ -207,7 +184,6 @@ Capture a picture with the camera module every time a button is pressed:
See `Push Button Stop Motion`_ for a full resource.
Reaction Game
=============
@@ -219,7 +195,6 @@ When you see the light come on, the first person to press their button wins!
See `Quick Reaction Game`_ for a full resource.
GPIO Music Box
==============
@@ -229,7 +204,6 @@ Each button plays a different sound!
See `GPIO Music Box`_ for a full resource.
All on when pressed
===================
@@ -247,7 +221,6 @@ Using :class:`LED`, :class:`Buzzer`, and :class:`Button` components:
.. literalinclude:: examples/all_on_3.py
Full color LED
==============
@@ -257,7 +230,6 @@ Making colours with an :class:`RGBLED`:
.. literalinclude:: examples/rgbled.py
Motion sensor
=============
@@ -267,7 +239,6 @@ Light an :class:`LED` when a :class:`MotionSensor` detects motion:
.. literalinclude:: examples/motion_sensor.py
Light sensor
============
@@ -286,7 +257,6 @@ level:
.. literalinclude:: examples/light_sensor_3.py
Distance sensor
===============
@@ -300,7 +270,6 @@ Run a function when something gets near the sensor:
.. literalinclude:: examples/distance_sensor_2.py
Motors
======
@@ -310,7 +279,6 @@ Spin a :class:`Motor` around forwards and backwards:
.. literalinclude:: examples/motor.py
Robot
=====
@@ -325,7 +293,6 @@ Make a robot with a distance sensor that runs away when things get within
.. literalinclude:: examples/robot_2.py
Button controlled robot
=======================
@@ -333,11 +300,6 @@ Use four GPIO buttons as forward/back/left/right controls for a robot:
.. literalinclude:: examples/robot_buttons_1.py
Alternatively, use four buttons to program the directions and add a fifth
button to process them in turn, like a Bee-Bot or Turtle robot.
.. literalinclude:: examples/robot_buttons_2.py
Keyboard controlled robot
=========================
@@ -362,7 +324,6 @@ suffice:
with ``sudo pip3 install evdev`` first. Be aware that ``evdev`` will only
work with local input devices; this recipe will *not* work over SSH.
Motion sensor robot
===================
@@ -374,7 +335,6 @@ Alternatively:
.. literalinclude:: examples/robot_motion_2.py
Potentiometer
=============
@@ -390,7 +350,6 @@ states that won't "fill" an LED:
.. literalinclude:: examples/pot_2.py
Measure temperature with an ADC
===============================
@@ -401,7 +360,6 @@ analog to digital converter:
.. literalinclude:: examples/thermometer.py
Full color LED controlled by 3 potentiometers
=============================================
@@ -419,48 +377,16 @@ Alternatively, the following example is identical, but uses the
Please note the example above requires Python 3. In Python 2, :func:`zip`
doesn't support lazy evaluation so the script will simply hang.
More recipes
============
Controlling the Pi's own LEDs
=============================
Continue to:
On certain models of Pi (specifically the model A+, B+, and 2B) it's possible
to control the power and activity LEDs. This can be useful for testing GPIO
functionality without the need to wire up your own LEDs (also useful because
the power and activity LEDs are "known good").
Firstly you need to disable the usual triggers for the built-in LEDs. This can
be done from the terminal with the following commands::
$ echo none | sudo tee /sys/class/leds/led0/trigger
$ echo gpio | sudo tee /sys/class/leds/led1/trigger
Now you can control the LEDs with gpiozero like so:
.. literalinclude:: examples/led_builtin.py
To revert the LEDs to their usual purpose you can either reboot your Pi or
run the following commands::
$ echo mmc0 | sudo tee /sys/class/leds/led0/trigger
$ echo input | sudo tee /sys/class/leds/led1/trigger
.. note::
On the Pi Zero you can control the activity LED with this recipe, but
there's no separate power LED to control (it's also worth noting the
activity LED is active low, so set ``active_high=False`` when constructing
your LED component).
On the original Pi 1 (model A or B), the activity LED can be controlled
with GPIO16 (after disabling its trigger as above) but the power LED is
hard-wired on.
On the Pi 3B the LEDs are controlled by a GPIO expander which is not
accessible from gpiozero (yet).
* :doc:`recipes_advanced`
* :doc:`recipes_remote_gpio`
.. _travispy: https://travispy.readthedocs.io/
.. _Push Button Stop Motion: https://www.raspberrypi.org/learning/quick-reaction-game/
.. _Quick Reaction Game: https://www.raspberrypi.org/learning/quick-reaction-game/
.. _GPIO Music Box: https://www.raspberrypi.org/learning/gpio-music-box/

66
docs/recipes_advanced.rst Normal file
View File

@@ -0,0 +1,66 @@
================
Recipes (Simple)
================
.. currentmodule:: gpiozero
The following recipes demonstrate some of the capabilities of the GPIO Zero
library. Please note that all recipes are written assuming Python 3. Recipes
*may* work under Python 2, but no guarantees!
Travis build LED indicator
==========================
Use LEDs to indicate the status of a Travis build. A green light means the
tests are passing, a red light means the build is broken:
.. literalinclude:: examples/led_travis.py
Note this recipe requires `travispy`_. Install with ``sudo pip3 install
travispy``.
Button controlled robot
=======================
Alternatively, use four buttons to program the directions and add a fifth
button to process them in turn, like a Bee-Bot or Turtle robot.
.. literalinclude:: examples/robot_buttons_2.py
Controlling the Pi's own LEDs
=============================
On certain models of Pi (specifically the model A+, B+, and 2B) it's possible
to control the power and activity LEDs. This can be useful for testing GPIO
functionality without the need to wire up your own LEDs (also useful because
the power and activity LEDs are "known good").
Firstly you need to disable the usual triggers for the built-in LEDs. This can
be done from the terminal with the following commands::
$ echo none | sudo tee /sys/class/leds/led0/trigger
$ echo gpio | sudo tee /sys/class/leds/led1/trigger
Now you can control the LEDs with gpiozero like so:
.. literalinclude:: examples/led_builtin.py
To revert the LEDs to their usual purpose you can either reboot your Pi or
run the following commands::
$ echo mmc0 | sudo tee /sys/class/leds/led0/trigger
$ echo input | sudo tee /sys/class/leds/led1/trigger
.. note::
On the Pi Zero you can control the activity LED with this recipe, but
there's no separate power LED to control (it's also worth noting the
activity LED is active low, so set ``active_high=False`` when constructing
your LED component).
On the original Pi 1 (model A or B), the activity LED can be controlled
with GPIO16 (after disabling its trigger as above) but the power LED is
hard-wired on.
On the Pi 3B the LEDs are controlled by a GPIO expander which is not
accessible from gpiozero (yet).

45
docs/recipes_remote_gpio.rst Normal file
View File

@@ -0,0 +1,45 @@
===================
Remote GPIO Recipes
===================
.. currentmodule:: gpiozero
The following recipes demonstrate some of the capabilities of the feature of the
GPIO Zero library. Before you start following these examples, please read up on
preparing your Pi and your host PC to work with :doc:`remote_gpio`.
Please note that all recipes are written assuming Python 3. Recipes *may* work
under Python 2, but no guarantees!
LED + Button
============
Let a button on one Raspberry Pi control the LED of another:
.. literalinclude:: examples/led_button_remote_1.py
LED + 2 Buttons
===============
The LED will come on when both buttons are pressed:
.. literalinclude:: examples/led_button_remote_2.py
Multi-room motion alert
=======================
Install a Raspberry Pi with a motion sensor in each room of your house, and have
an LED indicator showing when there's motion in each room:
.. literalinclude:: examples/multi_room_motion_alert.py
Multi-room doorbell
===================
Install a Raspberry Pi with a buzzer attached in each room you want to hear the
doorbell, and use a push button ad the doorbell::
.. literalinclude:: examples/multi_room_doorbell.py
This could also be used as an internal doorbell (tell people it's time for
dinner from the kitchen).

229
docs/remote_gpio.rst Normal file
View File

@@ -0,0 +1,229 @@
===========
Remote GPIO
===========
.. currentmodule:: gpiozero
GPIO Zero supports a number of different pin implementations (low-level pin
libraries which deal with the GPIO pins directly). By default, the `RPi.GPIO`_
library is used (assuming it is installed on your system), but you can
optionally specify one to use. For more information, see the :doc:`pins`
documentation page.
One of the pin libraries supported, `pigpio`_, provides the ability to control
GPIO pins remotely over the network, which means you can use GPIO Zero to
control devices connected to a Raspberry Pi on the network. You can do this from
another Raspberry Pi, or even from a PC.
See the :doc:`recipes_remote_gpio` page for examples on how remote pins can be
used.
Preparing the Raspberry Pi
==========================
If you're using Raspbian Jessie (desktop - not Jessie Lite) then you have
everything you need to use the remote GPIO feature. If you're using Jessie Lite,
or another distribution, you'll need to install pigpio::
sudo apt-get install pigpio
Then you just need to enable **Remote GPIO** in the Raspberry Pi configuration
tool:
IMAGE
(Alternatively, use ``sudo raspi-config`` on the command line)
Then launch the pigpio daemon::
sudo pigpiod
You will need to launch the pigpio daemon every time you wish to use this
feature. To automate running the daemon at boot time:
???
Preparing the host computer
===========================
If the host computer is a Raspberry Pi running Raspbian Jessie (or a PC running
x86 PIXEL), then you have everything you need. If you're using another Linux
distribution, Mac OS or Windows then you'll need to install the pigpio Python
library on the PC.
Raspberry Pi
------------
First, update your repositories list::
sudo apt-get update
Then install the pigpio library for Python 3::
sudo apt-get install python3-pigpio
or Python 2::
sudo apt-get install python-pigpio
Alternatively, install with pip::
sudo pip3 install pigpio
or:
sudo pip install pigpio
Linux
-----
First, update your distribution's repositories list. For example::
sudo apt-get update
Then install pip for Python 3::
sudo apt-get install python3-pip
or Python 2::
sudo apt-get install python-pip
(Alternatively, install pip with `get-pip`_.)
Next, install pigpio for Python 3::
sudo pip3 install pigpio
or Python 2::
sudo pip install pigpio
Mac OS
------
First, install pip::
???
Next, install pigpio with pip::
pip install pigpio
Windows
-------
First install pip::
???
Next, install pigpio with pip::
pip install pigpio
Environment variables
=====================
The simplest way to use devices with remote pins is to set the ``PIGPIO_ADDR``
environment variable to the IP address of the desired Raspberry Pi. You must
run your Python script or launch your development environment with the
environment variable set using the command line. For example, one of the
following::
$ PIGPIO_ADDR=192.168.1.3 python3 hello.py
$ PIGPIO_ADDR=192.168.1.3 python3
$ PIGPIO_ADDR=192.168.1.3 ipython3
$ PIGPIO_ADDR=192.168.1.3 idle3 &
If you are running this from a PC (not a Raspberry Pi) with gpiozero and the
pigpio Python library installed, this will work with no further configuration.
However, if you are running this from a Raspberry Pi, you will also need to
ensure the default pin factory is set to ``PiGPIOPin``. If ``RPi.GPIO`` is
installed, this will be selected as the default pin factory, so either uninstall
it, or use another environment variable to set it to ``PiGPIOPin``::
$ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=192.168.1.3 python3 hello.py
This usage will set the pin factory to :class:`PiGPIOPin` with a default host of
``192.168.1.3``. The pin factory can be changed inline in the code, as seen in
the following sections.
With this usage, you can write gpiozero code like you would on a Raspberry Pi,
with no modifications needed. For example:
.. literalinclude:: examples/led_1.py
When run with::
$ PIGPIO_ADDR=192.168.1.3 python3 led.py
will flash the LED connected to pin 17 of the Raspberry Pi with the IP address
``192.168.1.3``. And::
$ PIGPIO_ADDR=192.168.1.4 python3 led.py
will flash the LED connected to pin 17 of the Raspberry Pi with the IP address
``192.168.1.4``, without any code changes.
Pin objects
===========
An alternative (or additional) method of configuring gpiozero objects to use
remote pins is to create instances of :class:PiGPIOPin objects, and
instantiating device objects with those pin objects, rather than just numbers.
For example, with no environment variables set:
.. literalinclude:: examples/led_remote_1.py
This allows devices on multiple Raspberry Pis to be used in the same script:
.. literalinclude:: examples/led_remote_2.py
You can, of course, continue to create gpiozero device objects as normal, and
create others using remote pins. For example, if run on a Raspberry Pi, the
following script will flash an LED on the host Pi, and also on another Pi on the
network:
.. literalinclude:: examples/led_remote_3.py
Alternatively, when run with the environment variables
``GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=192.168.1.3`` set, the following
script will behave exactly the same as the previous one:
.. literalinclude:: examples/led_remote_4.py
Of course, multiple IP addresses can be used:
.. literalinclude:: examples/led_remote_5.py
Note that these examples use the :class:`LED` class, which takes a ``pin``
argument to initialise. Some classes, particularly those representing HATs and
other add-on boards, do not require their pin numbers to be specified. However,
it is still possible to use remote pins with these devices, either using
environment variables, or by setting ``gpiozero.Device._pin_factory``:
.. literalinclude:: examples/traffichat_remote_1.py
This also allows you to swap between two IP addresses and create instances of
mutliple HATs connected to different Pis:
.. literalinclude:: examples/traffichat_remote_2.py
Energenie example???
MCP3008 example???
.. note::
When running code directly on a Raspberry Pi, any pin type can be used
(assuming the relevant library is installed), but when a device is used
remotely, only :class:`PiGPIOPin` can be used, as ``pigpio`` is the only
pin library which supports remote GPIO.
Pi Zero
=======
???
.. RPi.GPIO_: https://pypi.python.org/pypi/RPi.GPIO
.. pigpio_: http://abyz.co.uk/rpi/pigpio/python.html
.. get-pip_: https://pip.pypa.io/en/stable/installing/