Merge pull request #523 from RPi-Distro/docs-updates

Docs updates: add installing, advanced recipes, remote gpio and remote recipes, close #428, close #434, close #520

README.rst

@@ -58,23 +58,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
 =============
@@ -118,6 +110,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
@@ -137,4 +130,3 @@ Other contributors:
 .. _Clare Macrae: https://github.com/claremacrae
 .. _Tim Golden: https://github.com/tjguk
 .. _Phil Howard: https://github.com/Gadgetoid
-

docs/api_spi.rst

@@ -64,7 +64,7 @@ omit any arguments from either scheme. The defaults are:
 * *clock_pin* defaults to 11, *mosi_pin* defaults to 10, *miso_pin* defaults
   to 9, and *select_pin* defaults to 8.
 
-Hence the following constructors are all equiavlent::
+Hence the following constructors are all equivalent::
 
     from gpiozero import MCP3008
 

docs/api_tools.rst

@@ -5,10 +5,9 @@ Source Tools
 .. currentmodule:: gpiozero.tools
 
 GPIO Zero includes several utility routines which are intended to be used with
-the :attr:`~gpiozero.SourceMixin.source` and
-:attr:`~gpiozero.ValuesMixin.values` attributes common to most devices in the
-library. These utility routines are in the ``tools`` module of GPIO Zero and
-are typically imported as follows::
+the :doc:`source_values` attributes common to most devices in the library. These
+utility routines are in the ``tools`` module of GPIO Zero and are typically
+imported as follows::
 
     from gpiozero.tools import scaled, negated, all_values
 
@@ -76,4 +75,3 @@ Artificial sources
 .. autofunction:: random_values
 
 .. autofunction:: sin_values
-

docs/contributing.rst

@@ -34,7 +34,7 @@ LED example").
 Commits which close (or intend to close) an issue should include the phrase
 "fix #123" or "close #123" where ``#123`` is the issue number, as well as
 include a short description, for example: "Add LED example, close #123", and
-pull requests should aim to match or closely match the correspoding issue
+pull requests should aim to match or closely match the corresponding issue
 title.
 
 Backwards compatibility

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()

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()

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)

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)

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)

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)

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)

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()

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()

docs/examples/pi_zero_remote.py

@@ -0,0 +1,9 @@
+from gpiozero import LED
+from gpiozero.pins.pigpio import PiGPIOPin
+from signal import pause
+
+led = LED(PiGPIOPin(17, host='raspberrypi.local'))
+
+led.blink()
+
+pause()

docs/examples/sense_hat_remote.py

@@ -0,0 +1,10 @@
+from gpiozero import MotionSensor
+from gpiozero.pins.pigpio import PiGPIOPin
+from sense_hat import SenseHat
+
+pir = MotionSensor(PiGPIOPin(4, host='192.168.1.4'))  # remote motion sensor
+sense = SenseHat()  # local sense hat
+
+while True:
+    pir.wait_for_motion()
+    sense.show_message(sense.temperature)

docs/examples/sense_hat_remote_2.py

@@ -0,0 +1,15 @@
+from gpiozero import LightSensor
+from gpiozero.pins.pigpio import PiGPIOPin
+from sense_hat import SenseHat
+
+light = LightSensor(PiGPIOPin(4, host='192.168.1.4'))  # remote motion sensor
+sense = SenseHat()  # local sense hat
+
+blue = (0, 0, 255)
+yellow = (255, 255, 0)
+
+while True:
+    if light.value > 0.5:
+        sense.clear(yellow)
+    else:
+        sense.clear(blue)

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

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

docs/index.rst

@@ -8,6 +8,7 @@ Table of Contents
 
     recipes
     notes
+    installing
     api_input
     api_output
     api_spi
@@ -19,8 +20,10 @@ Table of Contents
     api_exc
     cli_tools
     source_values
+    remote_gpio
+    recipes_advanced
+    recipes_remote_gpio
     contributing
     development
     changelog
     license
-

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 update
+
+Then install the package for Python 3::
+
+    sudo apt install python3-gpiozero
+
+or Python 2::
+
+    sudo apt install python-gpiozero
+
+Linux
+=====
+
+First, update your distribution's repositories list. For example::
+
+    sudo apt update
+
+Then install pip for Python 3::
+
+    sudo apt install python3-pip
+
+or Python 3::
+
+    sudo apt 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

docs/notes.rst

@@ -36,7 +36,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
 
@@ -84,13 +83,13 @@ version of gpiozero is available in your Python environment like so:
 
     >>> from pkg_resources import require
     >>> require('gpiozero')
-    [gpiozero 1.2.0 (/usr/local/lib/python2.7/dist-packages)]
+    [gpiozero 1.3.2 (/usr/lib/python3/dist-packages)]
     >>> require('gpiozero')[0].version
-    '1.2.0'
+    '1.3.2'
 
-If you have multiple versions installed (e.g. from ``pip`` and ``apt-get``)
-they will not show up in the list returned by the ``require`` method. However,
-the first entry in the list will be the version that ``import gpiozero`` will
+If you have multiple versions installed (e.g. from ``pip`` and ``apt``) they
+will not show up in the list returned by the ``require`` method. However, the
+first entry in the list will be the version that ``import gpiozero`` will
 import.
 
 If you receive the error "No module named pkg_resources", you need to install
@@ -98,5 +97,9 @@ the ``pip`` utility. This can be done with the following command in Raspbian:
 
 .. code-block:: console
 
-    $ sudo apt-get install python-pip
+    sudo apt install python-pip
 
+Alternatively, install pip with `get-pip`_.
+
+
+.. _get_pip: https://pip.pypa.io/en/stable/installing/

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,52 +377,15 @@ 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:
-
-.. code-block:: console
-
-    $ 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:
-
-.. code-block:: console
-
-    $ 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/
-

docs/recipes_advanced.rst

@@ -0,0 +1,69 @@
+==================
+Recipes (Advanced)
+==================
+
+.. 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).
+
+
+.. _travispy: https://travispy.readthedocs.io/

docs/recipes_remote_gpio.rst

@@ -0,0 +1,61 @@
+===================
+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 as 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).
+
+Light sensor + Sense HAT
+=========================
+
+The `Sense HAT`_ (not supported by GPIO Zero) includes temperature, humidity and
+pressure sensors, but no light sensor. Remote pins allow an external light
+sensor to be used as well. The Sense HAT LED display can be used to show
+different colours according to the light levels:
+
+.. literalinclude:: examples/sense_hat_remote_2.py
+
+Note that in this case, the Sense HAT code must be run locally, and the GPIO
+remotely.
+
+
+.. _Sense HAT: https://www.raspberrypi.org/products/sense-hat/

docs/remote_gpio.rst

@@ -0,0 +1,270 @@
+===========
+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 install pigpio
+
+Then you just need to enable **Remote GPIO** in the Raspberry Pi configuration
+tool:
+
+.. image:: images/raspi-config.png
+
+(Alternatively, use ``sudo raspi-config`` on the command line)
+
+Then launch the pigpio daemon::
+
+    sudo pigpiod
+
+To only allow connections from a specific IP address, use the ``-n`` flag. For
+example::
+
+    sudo pigpiod -n localhost # allow localhost only
+    sudo pigpiod -n 192.168.1.65 # allow 192.168.1.65 only
+    sudo pigpiod -n localhost -n 192.168.1.65 # allow localhost and 192.168.1.65 only
+
+You will need to launch the pigpio daemon every time you wish to use this
+feature. To automate running the daemon at boot time::
+
+    sudo systemctl enable pigpiod
+
+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 update
+
+Then install the pigpio library for Python 3::
+
+    sudo apt install python3-pigpio
+
+or Python 2::
+
+    sudo apt 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 update
+
+Then install pip for Python 3::
+
+    sudo apt install python3-pip
+
+or Python 2::
+
+    sudo apt 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 using :meth:`~Device._set_pin_factory`:
+
+.. literalinclude:: examples/traffichat_remote_1.py
+
+This also allows you to swap between two IP addresses and create instances of
+multiple HATs connected to different Pis:
+
+.. literalinclude:: examples/traffichat_remote_2.py
+
+You could even use a HAT which is not supported by GPIO Zero (such as the
+`Sense HAT`_) on one Pi, and use remote pins to control another over the
+network:
+
+.. literalinclude:: examples/sense_hat_remote.py
+
+Note that in this case, the Sense HAT code must be run locally, and the GPIO
+remotely.
+
+Pi Zero USB OTG
+===============
+
+The `Raspberry Pi Zero`_ and `Pi Zero W`_ feature a USB OTG port, allowing users
+to configure the device as (amongst other things) an Ethernet device. In this
+mode, it is possible to control the Pi Zero's GPIO pins over USB from another
+computer using remote pins.
+
+First, configure the boot partition of the SD card:
+
+1. Edit ``config.txt`` and add ``dtoverlay=dwc2`` on a new line, then save the
+file.
+2. Create an empty file called ``ssh`` (no file extension) and save it in the
+boot partition.
+3. Edit ``cmdline.txt`` and insert ``modules-load=dwc2,g_ether`` after
+``rootwait``.
+
+(See `blog.gbaman.info`_ for more information)
+
+Then connect the Pi Zero to your computer using a micro USB cable (connecting it
+to the USB port, not the power port). You'll see the indicator LED flashing as
+the Pi Zero boots. When it's ready, you will be able to ping and SSH into it
+using the hostname ``raspberrypi.local``. SSH into the Pi Zero, ensure Remote
+GPIO is enabled and the pigpio daemon is running, and you can use remote pins
+from the computer, referencing the host by its hostname, like so:
+
+.. literalinclude:: examples/pi_zero_remote.py
+
+.. 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.
+
+
+.. _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/
+.. _Sense HAT: https://www.raspberrypi.org/products/sense-hat/
+.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/pi-zero/
+.. _Pi Zero W: https://www.raspberrypi.org/products/pi-zero-w/
+.. _blog.gbaman.info: http://blog.gbaman.info/?p=791

gpiozero/other_devices.py

@@ -39,10 +39,12 @@ class PingServer(InternalDevice):
         from gpiozero import PingServer, LED
         from signal import pause
 
-        server = PingServer('my-server')
+        google = PingServer('google.com')
         led = LED(4)
-        led.source_delay = 1
-        led.source = server.values
+
+        led.source_delay = 60  # check once per minute
+        led.source = google.values
+
         pause()
 
     :param str host:
@@ -86,8 +88,10 @@ class CPUTemperature(InternalDevice):
         # Use minimums and maximums that are closer to "normal" usage so the
         # bar graph is a bit more "lively"
         temp = CPUTemperature(min_temp=50, max_temp=90)
+
         graph = LEDBarGraph(5, 6, 13, 19, 25, pwm=True)
         graph.source = temp.values
+
         pause()
 
     :param str sensor_file:
@@ -158,14 +162,15 @@ class TimeOfDay(InternalDevice):
     The following example turns on a lamp attached to an :class:`Energenie`
     plug between 7 and 8 AM::
 
-        from datetime import time
         from gpiozero import TimeOfDay, Energenie
+        from datetime import time
         from signal import pause
 
         lamp = Energenie(0)
         morning = TimeOfDay(time(7), time(8))
-        morning.when_activated = lamp.on
-        morning.when_deactivated = lamp.off
+
+        lamp.source = morning.values
+
         pause()
 
     :param ~datetime.time start_time:
@@ -240,4 +245,3 @@ class TimeOfDay(InternalDevice):
             return self.start_time <= datetime.utcnow().time() <= self.end_time
         else:
             return self.start_time <= datetime.now().time() <= self.end_time
-