From dea7ba6ec28e45edf812e6c671b6ad68781ad1b2 Mon Sep 17 00:00:00 2001 From: Ben Nuttall Date: Tue, 10 Jan 2017 09:43:53 +0000 Subject: [PATCH] Docs updates: add installing, advanced recipes, remote gpio and remote recipes - wip --- README.rst | 20 +- docs/examples/led_button_remote_1.py | 10 + docs/examples/led_button_remote_2.py | 12 ++ docs/examples/led_remote_1.py | 11 ++ docs/examples/led_remote_2.py | 14 ++ docs/examples/led_remote_3.py | 14 ++ docs/examples/led_remote_4.py | 14 ++ docs/examples/led_remote_5.py | 17 ++ docs/examples/multi_room_doorbell.py | 14 ++ docs/examples/multi_room_motion_alert.py | 14 ++ docs/examples/traffichat_remote_1.py | 7 + docs/examples/traffichat_remote_2.py | 8 + docs/index.rst | 3 +- docs/installing.rst | 82 ++++++++ docs/notes.rst | 5 +- docs/recipes.rst | 92 +-------- docs/recipes_advanced.rst | 66 +++++++ docs/recipes_remote_gpio.rst | 45 +++++ docs/remote_gpio.rst | 229 +++++++++++++++++++++++ 19 files changed, 578 insertions(+), 99 deletions(-) create mode 100644 docs/examples/led_button_remote_1.py create mode 100644 docs/examples/led_button_remote_2.py create mode 100644 docs/examples/led_remote_1.py create mode 100644 docs/examples/led_remote_2.py create mode 100644 docs/examples/led_remote_3.py create mode 100644 docs/examples/led_remote_4.py create mode 100644 docs/examples/led_remote_5.py create mode 100644 docs/examples/multi_room_doorbell.py create mode 100644 docs/examples/multi_room_motion_alert.py create mode 100644 docs/examples/traffichat_remote_1.py create mode 100644 docs/examples/traffichat_remote_2.py create mode 100644 docs/installing.rst create mode 100644 docs/recipes_advanced.rst create mode 100644 docs/recipes_remote_gpio.rst create mode 100644 docs/remote_gpio.rst diff --git a/README.rst b/README.rst index 8ecedd0..3210fec 100644 --- a/README.rst +++ b/README.rst @@ -56,23 +56,15 @@ together: The library includes interfaces to many simple everyday components, as well as some more complex things like sensors, analogue-to-digital converters, full -colour LEDs, robotics kits and more. +colour LEDs, robotics kits and more. See the :doc:`recipes` page for ideas on +how to get started. Install ======= -First, update your repositories list:: - - sudo apt-get update - -Then install the package of your choice. Both Python 3 and Python 2 are -supported. Python 3 is recommended:: - - sudo apt-get install python3-gpiozero - -or:: - - sudo apt-get install python-gpiozero +GPIO Zero is installed by default in Raspbian Jessie, available from +`raspberrypi.org`_. To install on Jessie Lite or other operating systems, +including for PCs using remote GPIO, see the :doc:`installing` page. Documentation ============= @@ -116,6 +108,7 @@ Other contributors: .. _Raspberry Pi Foundation: https://www.raspberrypi.org/ +.. _raspberrypi.org: https://www.raspberrypi.org/downloads/ .. _GitHub: https://github.com/RPi-Distro/python-gpiozero .. _issues: https://github.com/RPi-Distro/python-gpiozero/issues .. _recipes: https://gpiozero.readthedocs.io/en/latest/recipes.html @@ -135,4 +128,3 @@ Other contributors: .. _Clare Macrae: https://github.com/claremacrae .. _Tim Golden: https://github.com/tjguk .. _Phil Howard: https://github.com/Gadgetoid - diff --git a/docs/examples/led_button_remote_1.py b/docs/examples/led_button_remote_1.py new file mode 100644 index 0000000..7fb7363 --- /dev/null +++ b/docs/examples/led_button_remote_1.py @@ -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() diff --git a/docs/examples/led_button_remote_2.py b/docs/examples/led_button_remote_2.py new file mode 100644 index 0000000..bacc443 --- /dev/null +++ b/docs/examples/led_button_remote_2.py @@ -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() diff --git a/docs/examples/led_remote_1.py b/docs/examples/led_remote_1.py new file mode 100644 index 0000000..0bfd9f4 --- /dev/null +++ b/docs/examples/led_remote_1.py @@ -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) diff --git a/docs/examples/led_remote_2.py b/docs/examples/led_remote_2.py new file mode 100644 index 0000000..c3bdb02 --- /dev/null +++ b/docs/examples/led_remote_2.py @@ -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) diff --git a/docs/examples/led_remote_3.py b/docs/examples/led_remote_3.py new file mode 100644 index 0000000..1e7133b --- /dev/null +++ b/docs/examples/led_remote_3.py @@ -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) diff --git a/docs/examples/led_remote_4.py b/docs/examples/led_remote_4.py new file mode 100644 index 0000000..5d88d8b --- /dev/null +++ b/docs/examples/led_remote_4.py @@ -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) diff --git a/docs/examples/led_remote_5.py b/docs/examples/led_remote_5.py new file mode 100644 index 0000000..ab403ee --- /dev/null +++ b/docs/examples/led_remote_5.py @@ -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) diff --git a/docs/examples/multi_room_doorbell.py b/docs/examples/multi_room_doorbell.py new file mode 100644 index 0000000..da8a070 --- /dev/null +++ b/docs/examples/multi_room_doorbell.py @@ -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() diff --git a/docs/examples/multi_room_motion_alert.py b/docs/examples/multi_room_motion_alert.py new file mode 100644 index 0000000..8f3e5d1 --- /dev/null +++ b/docs/examples/multi_room_motion_alert.py @@ -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() diff --git a/docs/examples/traffichat_remote_1.py b/docs/examples/traffichat_remote_1.py new file mode 100644 index 0000000..9b08eb7 --- /dev/null +++ b/docs/examples/traffichat_remote_1.py @@ -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 diff --git a/docs/examples/traffichat_remote_2.py b/docs/examples/traffichat_remote_2.py new file mode 100644 index 0000000..5795455 --- /dev/null +++ b/docs/examples/traffichat_remote_2.py @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 0f36e08..964bcb1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 - diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 0000000..2777540 --- /dev/null +++ b/docs/installing.rst @@ -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 diff --git a/docs/notes.rst b/docs/notes.rst index 7c4ba69..d207ae6 100644 --- a/docs/notes.rst +++ b/docs/notes.rst @@ -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/ diff --git a/docs/recipes.rst b/docs/recipes.rst index 5c64dd3..e32c794 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -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/ - diff --git a/docs/recipes_advanced.rst b/docs/recipes_advanced.rst new file mode 100644 index 0000000..dd4520c --- /dev/null +++ b/docs/recipes_advanced.rst @@ -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). diff --git a/docs/recipes_remote_gpio.rst b/docs/recipes_remote_gpio.rst new file mode 100644 index 0000000..a322682 --- /dev/null +++ b/docs/recipes_remote_gpio.rst @@ -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). diff --git a/docs/remote_gpio.rst b/docs/remote_gpio.rst new file mode 100644 index 0000000..7737dea --- /dev/null +++ b/docs/remote_gpio.rst @@ -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/