mirror of
https://github.com/KevinMidboe/python-gpiozero.git
synced 2025-12-08 20:39:01 +00:00
Docs updates: add installing, advanced recipes, remote gpio and remote recipes - wip
This commit is contained in:
Ben Nuttall
229
docs/remote_gpio.rst
Normal file
229
docs/remote_gpio.rst
Normal 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/
|
||||
Reference in New Issue
Block a user