Merge pull request #577 from RPi-Distro/pinout-man

Prepare for v1.4.0 release

.gitignore

@@ -30,3 +30,4 @@ coverage
 
 # Generated documentation
 docs/_build
+man/

Makefile

@@ -55,7 +55,7 @@ DIST_DEB=dist/python-$(NAME)_$(VER)$(DEB_SUFFIX)_all.deb \
 DIST_DSC=dist/$(NAME)_$(VER)$(DEB_SUFFIX).tar.gz \
 	dist/$(NAME)_$(VER)$(DEB_SUFFIX).dsc \
 	dist/$(NAME)_$(VER)$(DEB_SUFFIX)_source.changes
-MAN_PAGES=
+MAN_PAGES=man/pinout.1 man/remote-gpio.7
 
 
 # Default target

README.rst

@@ -96,14 +96,15 @@ Other contributors:
 - `Clare Macrae`_
 - `Tim Golden`_
 - `Phil Howard`_
+- `Stewart Adcock`_
 
 
 .. _Raspberry Pi Foundation: https://www.raspberrypi.org/
 .. _raspberrypi.org: https://www.raspberrypi.org/downloads/
-.. _Recipes: http://gpiozero.readthedocs.io/en/latest/recipes.html
+.. _Recipes: https://gpiozero.readthedocs.io/en/stable/recipes.html
-.. _Contributing: http://gpiozero.readthedocs.io/en/latest/contributing.html
+.. _Contributing: https://gpiozero.readthedocs.io/en/stable/contributing.html
-.. _Development: http://gpiozero.readthedocs.io/en/latest/development.html
+.. _Development: https://gpiozero.readthedocs.io/en/stable/development.html
-.. _Installing: http://gpiozero.readthedocs/io/en/latest/installing.html
+.. _Installing: https://gpiozero.readthedocs.io/en/stable/installing.html
 
 .. _Ben Nuttall: https://github.com/bennuttall
 .. _Dave Jones: https://github.com/waveform80
@@ -120,3 +121,4 @@ Other contributors:
 .. _Clare Macrae: https://github.com/claremacrae
 .. _Tim Golden: https://github.com/tjguk
 .. _Phil Howard: https://github.com/Gadgetoid
+.. _Stewart Adcock: https://github.com/stewartadcock

debian/rules

@@ -10,6 +10,8 @@ export DH_OPTIONS
 override_dh_auto_install:
 	python setup.py install --root debian/python-gpiozero --install-layout=deb
 	python3 setup.py install --root debian/python3-gpiozero --install-layout=deb
+	# Strip out binaries from the py2 package
+	rm debian/python-gpiozero/usr/bin/pinout
 
 #override_dh_auto_test:
 #	# Don't run the tests!

docs/api_pins.rst

@@ -31,6 +31,8 @@ default factory can be constructed (e.g. because no GPIO implementations are
 installed, or all of them fail to load for whatever reason), an
 :exc:`ImportError` will be raised.
 
+.. _changing-pin-factory:
+
 Changing the pin factory
 ========================
 

docs/api_tools.rst

@@ -1,6 +1,6 @@
-====================
+=========================
-API - Device Sources
+API - Device Source Tools
-====================
+=========================
 
 .. module:: gpiozero.tools
 

docs/changelog.rst

@@ -5,6 +5,54 @@ Changelog
 .. currentmodule:: gpiozero
 
 
+Release 1.4.0 (2017-07-26)
+==========================
+
+* Pin factory is now :ref:`configurable from device constructors
+  <changing-pin-factory>` as well as command line. NOTE: this is a backwards
+  incompatible change for manual pin construction but it's hoped this is
+  (currently) a sufficiently rare use case that this won't affect too many
+  people and the benefits of the new system warrant such a change, i.e. the
+  ability to use remote pin factories with HAT classes that don't accept pin
+  assignations (`#279`_)
+* Major work on SPI, primarily to support remote hardware SPI (`#421`_,
+  `#459`_, `#465`_, `#468`_, `#575`_)
+* Pin reservation now works properly between GPIO and SPI devices (`#459`_,
+  `#468`_)
+* Lots of work on the documentation: :doc:`source/values chapter
+  <source_values>`, better charts, more recipes, :doc:`remote GPIO
+  configuration <remote_gpio>`, mock pins, better PDF output (`#484`_, `#469`_,
+  `#523`_, `#520`_, `#434`_, `#565`_, `#576`_)
+* Support for :class:`StatusZero` and :class:`StatusBoard` HATs (`#558`_)
+* Added :program:`pinout` command line tool to provide a simple
+  reference to the GPIO layout and information about the associated Pi
+  (`#497`_, `#504`_) thanks to Stewart Adcock for the initial work
+* :func:`pi_info` made more lenient for new (unknown) Pi models (`#529`_)
+* Fixed a variety of packaging issues (`#535`_, `#518`_, `#519`_)
+* Improved text in factory fallback warnings (`#572`_)
+
+.. _#279: https://github.com/RPi-Distro/python-gpiozero/issues/279
+.. _#421: https://github.com/RPi-Distro/python-gpiozero/issues/421
+.. _#434: https://github.com/RPi-Distro/python-gpiozero/issues/434
+.. _#459: https://github.com/RPi-Distro/python-gpiozero/issues/459
+.. _#465: https://github.com/RPi-Distro/python-gpiozero/issues/465
+.. _#468: https://github.com/RPi-Distro/python-gpiozero/issues/468
+.. _#469: https://github.com/RPi-Distro/python-gpiozero/issues/469
+.. _#484: https://github.com/RPi-Distro/python-gpiozero/issues/484
+.. _#497: https://github.com/RPi-Distro/python-gpiozero/issues/497
+.. _#504: https://github.com/RPi-Distro/python-gpiozero/issues/504
+.. _#518: https://github.com/RPi-Distro/python-gpiozero/issues/518
+.. _#519: https://github.com/RPi-Distro/python-gpiozero/issues/519
+.. _#520: https://github.com/RPi-Distro/python-gpiozero/issues/520
+.. _#523: https://github.com/RPi-Distro/python-gpiozero/issues/523
+.. _#529: https://github.com/RPi-Distro/python-gpiozero/issues/529
+.. _#535: https://github.com/RPi-Distro/python-gpiozero/issues/535
+.. _#558: https://github.com/RPi-Distro/python-gpiozero/issues/558
+.. _#565: https://github.com/RPi-Distro/python-gpiozero/issues/565
+.. _#572: https://github.com/RPi-Distro/python-gpiozero/issues/572
+.. _#575: https://github.com/RPi-Distro/python-gpiozero/issues/575
+.. _#576: https://github.com/RPi-Distro/python-gpiozero/issues/576
+
 Release 1.3.2 (2017-03-03)
 ==========================
 

docs/cli_pinout.rst

@@ -0,0 +1,175 @@
+pinout
+======
+
+.. image:: images/pinout_pi3.png
+
+Synopsis
+--------
+
+::
+
+    pinout [-h] [-r REVISION] [-c] [-m]
+
+Description
+-----------
+
+A utility for querying Raspberry Pi GPIO pin-out information. Running
+:program:`pinout` on its own will output a board diagram, and GPIO header
+diagram for the current Raspberry Pi. It is also possible to manually specify a
+revision of Pi, or (by :doc:`remote_gpio`) to output information about a
+remote Pi.
+
+Options
+-------
+
+.. program:: pinout
+
+.. option:: -h, --help
+
+    show this help message and exit
+
+.. option:: -r REVISION, --revision REVISION
+
+    RPi revision. Default is to autodetect revision of current device
+
+.. option:: -c, --color
+
+    Force colored output (by default, the output will include ANSI color codes
+    if run in a color-capable terminal). See also :option:`--monochrome`
+
+.. option:: -m, --monochrome
+
+    Force monochrome output. See also :option:`--color`
+
+Examples
+--------
+
+To output information about the current Raspberry Pi:
+
+.. code-block:: console
+
+    $ pinout
+
+For a Raspberry Pi model 3B, this will output something like the following:
+
+.. code-block:: none
+
+    ,--------------------------------.
+    | oooooooooooooooooooo J8     +====
+    | 1ooooooooooooooooooo        | USB
+    |                             +====
+    |      Pi Model 3B V1.1          |
+    |      +----+                 +====
+    | |D|  |SoC |                 | USB
+    | |S|  |    |                 +====
+    | |I|  +----+                    |
+    |                   |C|     +======
+    |                   |S|     |   Net
+    | pwr        |HDMI| |I||A|  +======
+    `-| |--------|    |----|V|-------'
+
+    Revision           : a02082
+    SoC                : BCM2837
+    RAM                : 1024Mb
+    Storage            : MicroSD
+    USB ports          : 4 (excluding power)
+    Ethernet ports     : 1
+    Wi-fi              : True
+    Bluetooth          : True
+    Camera ports (CSI) : 1
+    Display ports (DSI): 1
+
+    J8:
+       3V3  (1) (2)  5V
+     GPIO2  (3) (4)  5V
+     GPIO3  (5) (6)  GND
+     GPIO4  (7) (8)  GPIO14
+       GND  (9) (10) GPIO15
+    GPIO17 (11) (12) GPIO18
+    GPIO27 (13) (14) GND
+    GPIO22 (15) (16) GPIO23
+       3V3 (17) (18) GPIO24
+    GPIO10 (19) (20) GND
+     GPIO9 (21) (22) GPIO25
+    GPIO11 (23) (24) GPIO8
+       GND (25) (26) GPIO7
+     GPIO0 (27) (28) GPIO1
+     GPIO5 (29) (30) GND
+     GPIO6 (31) (32) GPIO12
+    GPIO13 (33) (34) GND
+    GPIO19 (35) (36) GPIO16
+    GPIO26 (37) (38) GPIO20
+       GND (39) (40) GPIO21
+
+By default, if stdout is a console that supports color, ANSI codes will be used
+to produce color output. Output can be forced to be :option:`--monochrome`:
+
+.. code-block:: console
+
+    $ pinout --monochrome
+
+Or forced to be :option:`--color`, in case you are redirecting to something
+capable of supporting ANSI codes:
+
+.. code-block:: console
+
+    $ pinout --color | less -SR
+
+To manually specify the revision of Pi you want to query, use
+:option:`--revision`. The tool understands both old-style `revision codes`_
+(such as for the model B):
+
+.. code-block:: console
+
+    $ pinout -r 000d
+
+Or new-style `revision codes`_ (such as for the Pi Zero W):
+
+.. code-block:: console
+
+    $ pinout -r 9000c1
+
+.. image:: images/pinout_pizero_w.png
+
+You can also use the tool with :doc:`remote_gpio` to query remote Raspberry
+Pi's:
+
+.. code-block:: console
+
+    $ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=other_pi pinout
+
+Or run the tool directly on a PC using the mock pin implementation (although in
+this case you'll almost certainly want to specify the Pi revision manually):
+
+.. code-block:: console
+
+    $ GPIOZERO_PIN_FACTORY=mock pinout -r a22042
+
+Environment Variables
+---------------------
+
+GPIOZERO_PIN_FACTORY
+    The library to use when communicating with the GPIO pins. Defaults to
+    attempting to load RPi.GPIO, then RPIO, then pigpio, and finally uses a
+    native Python implementation. Valid values include "rpigpio", "rpio",
+    "pigpio", "native", and "mock". The latter is most useful on non-Pi
+    platforms as it emulates a Raspberry Pi model 3B (by default).
+
+PIGPIO_ADDR
+    The hostname of the Raspberry Pi the pigpio library should attempt to
+    connect to (if the pigpio pin factory is being used). Defaults to
+    ``localhost``.
+
+PIGPIO_PORT
+    The port number the pigpio library should attempt to connect to (if the
+    pigpio pin factory is being used). Defaults to ``8888``.
+
+
+.. only:: builder_man
+
+    See Also
+    --------
+
+        :manpage:`remote-gpio(7)`
+
+.. _revision codes: http://elinux.org/RPi_HardwareHistory

docs/cli_tools.rst

@@ -2,25 +2,8 @@
 Command-line Tools
 ==================
 
-Pinout
-======
-
 The gpiozero package contains a database of information about the various
-revisions of Raspberry Pi. This is queried by the ``pinout`` command-line
+revisions of Raspberry Pi. This is queried by the :program:`pinout`
-tool to output details of the GPIO pins available.
+command-line tool to output details of the GPIO pins available.
 
-Unless specified, the revision of the current device will be detected. A
+.. include:: cli_pinout.rst
-particular revision may be selected with the --revision command-line
-option. For example::
-
-    pinout --revision 000d
-
-By default, the output will include ANSI color codes if run in a color-capable
-terminal. This behaviour may be overridden by the --color or --monochrome
-options to force colored or non-colored output, respectively. For example::
-
-    pinout --monochrome
-
-Full usage details are available with::
-
-    pinout --help

docs/conf.py

@@ -153,9 +153,12 @@ epub_show_urls = 'no'
 
 # -- Options for manual page output ---------------------------------------
 
-man_pages = []
+man_pages = [
+    ('cli_pinout',  'pinout',      'GPIO Zero pinout tool',       [_setup.__author__], 1),
+    ('remote_gpio', 'remote-gpio', 'GPIO Zero remote GPIO guide', [_setup.__author__], 7),
+]
 
-#man_show_urls = False
+man_show_urls = True
 
 # -- Options for Texinfo output -------------------------------------------
 

docs/development.rst

@@ -32,7 +32,7 @@ within a virtual Python environment:
 
 .. code-block:: console
 
-    $ sudo apt-get install lsb-release build-essential git git-core \
+    $ sudo apt install lsb-release build-essential git git-core \
     >   exuberant-ctags virtualenvwrapper python-virtualenv python3-virtualenv \
     >   python-dev python3-dev
     $ cd
@@ -89,7 +89,7 @@ command should install all required dependencies:
 
 .. code-block:: console
 
-    $ sudo apt-get install texlive-latex-recommended texlive-latex-extra \
+    $ sudo apt install texlive-latex-recommended texlive-latex-extra \
         texlive-fonts-recommended graphviz inkscape
 
 Once these are installed, you can use the "doc" target to build the

docs/examples/led_board_2.py

@@ -1,5 +1,8 @@
 from gpiozero import LEDBoard
+from signal import pause
 
 leds = LEDBoard(5, 6, 13, 19, 26, pwm=True)
 
 leds.value = (0.2, 0.4, 0.6, 0.8, 1.0)
+
+pause()

docs/examples/led_board_3.py

@@ -0,0 +1,9 @@
+from gpiozero import LEDBoard
+from time import sleep
+
+leds = LEDBoard(5, 6, 13, 19, 26)
+
+for led in leds:
+    led.on()
+    sleep(1)
+    led.off()

docs/examples/led_board_4.py

@@ -0,0 +1,11 @@
+from gpiozero import LEDBoard
+from time import sleep
+
+leds = LEDBoard(2, 3, 4, 5, 6, 7, 8, 9)
+
+leds[0].on()  # first led on
+sleep(1)
+leds[7].on()  # last led on
+sleep(1)
+leds[-1].off()  # last led off
+sleep(1)

docs/examples/led_board_5.py

@@ -0,0 +1,24 @@
+from gpiozero import LEDBoard
+from time import sleep
+
+leds = LEDBoard(2, 3, 4, 5, 6, 7, 8, 9)
+
+for led in leds[3:]:  # leds 3 and onward
+    led.on()
+sleep(1)
+leds.off()
+
+for led in leds[:2]:  # leds 0 and 1
+    led.on()
+sleep(1)
+leds.off()
+
+for led in leds[::2]:  # even leds (0, 2, 4...)
+    led.on()
+sleep(1)
+leds.off()
+
+for led in leds[1::2]:  # odd leds (1, 3, 5...)
+    led.on()
+sleep(1)
+leds.off()

docs/examples/led_board_6.py

@@ -0,0 +1,11 @@
+from gpiozero import LEDBoard
+from time import sleep
+
+leds = LEDBoard(red=2, green=3, blue=4)
+
+leds.red.on()
+sleep(1)
+leds.green.on()
+sleep(1)
+leds.blue.on()
+sleep(1)

docs/examples/led_board_7.py

@@ -0,0 +1,15 @@
+from gpiozero import LEDBoard
+from time import sleep
+
+leds = LEDBoard(red=LEDBoard(top=2, bottom=3), green=LEDBoard(top=4, bottom=5))
+
+leds.red.on() ## both reds on
+sleep(1)
+leds.green.on()  # both greens on
+sleep(1)
+leds.off()  # all off
+sleep(1)
+leds.red.top.on()  # top red on
+sleep(1)
+leds.green.bottom.on()  # bottom green on
+sleep(1)

docs/examples/pi_zero_remote.py

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

docs/faq.rst

@@ -7,6 +7,50 @@ Frequently Asked Questions
 .. currentmodule:: gpiozero
 
 
+.. _keep-your-script-running:
+
+How do I keep my script running?
+================================
+
+The following script looks like it should turn an LED on::
+
+    from gpiozero import LED
+
+    led = LED(17)
+    led.on()
+
+And it does, if you're using the Python (or IPython or IDLE) shell. However,
+if you saved this script as a Python file and ran it, it would flash on
+briefly, then the script would end and it would turn off.
+
+The following file includes an intentional :func:`~signal.pause` to keep the
+script alive::
+
+    from gpiozero import LED
+    from signal import pause
+
+    led = LED(17)
+    led.on()
+
+    pause()
+
+Now the script will stay running, leaving the LED on, until it is terminated
+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
+
+    def hello():
+        print("Hello")
+
+    button = Button(2)
+    button.when_pressed = hello
+
+    pause()
+
+
 My event handler isn't being called?
 ====================================
 
@@ -21,7 +65,7 @@ example::
     b = Button(17)
     b.when_pressed = pushed()
 
-In the case above, when assigning to the ``when_pressed``, the thing that is
+In the case above, when assigning to ``when_pressed``, the thing that is
 assigned is the *result of calling* the ``pushed`` function. Because ``pushed``
 doesn't explicitly return anything, the result is ``None``. Hence this is
 equivalent to doing::
@@ -69,7 +113,7 @@ suppress the warnings you've got a couple of options:
 
    .. code-block:: console
 
-       $ GPIOZERO_PIN_FACTORY=pigpio python
+       $ GPIOZERO_PIN_FACTORY=pigpio python3
 
    In this case no warning is issued because there's no fallback; either the
    specified factory loads or it fails in which case an :exc:`ImportError` will
@@ -96,65 +140,22 @@ version of gpiozero is available in your Python environment like so:
 
     >>> from pkg_resources import require
     >>> require('gpiozero')
-    [gpiozero 1.3.2 (/usr/lib/python3/dist-packages)]
+    [gpiozero 1.4.0 (/usr/lib/python3/dist-packages)]
     >>> require('gpiozero')[0].version
-    '1.3.2'
+    '1.4.0'
 
 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
+If you receive the error ``No module named pkg_resources``, you need to install
-the ``pip`` utility. This can be done with the following command in Raspbian:
+``pip``. This can be done with the following command in Raspbian:
 
 .. code-block:: console
 
-    $ sudo apt install python-pip
+    $ sudo apt install python3-pip
 
 Alternatively, install pip with `get-pip`_.
 
 .. _get-pip: https://pip.pypa.io/en/stable/installing/
-
-
-.. _keep-your-script-running:
-
-How do I keep my script running?
-================================
-
-The following script looks like it should turn an LED on::
-
-    from gpiozero import LED
-
-    led = LED(17)
-    led.on()
-
-And it does, if you're using the Python (or IPython or IDLE) shell. However,
-if you saved this script as a Python file and ran it, it would flash on
-briefly, then the script would end and it would turn off.
-
-The following file includes an intentional :func:`~signal.pause` to keep the
-script alive::
-
-    from gpiozero import LED
-    from signal import pause
-
-    led = LED(17)
-    led.on()
-    pause()
-
-Now the script will stay running, leaving the LED on, until it is terminated
-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
-
-    def hello():
-        print("Hello")
-
-    button = Button(2)
-    button.when_pressed = hello
-    pause()
-

docs/installing.rst

@@ -4,7 +4,8 @@ Installing GPIO Zero
 
 GPIO Zero is installed by default in `Raspbian Jessie`_ and `Raspbian x86`_,
 available from `raspberrypi.org`_. Follow these guides to installing on other
-operating systems, including for PCs using the :doc:`remote_gpio` feature.
+operating systems, including for PCs using the :doc:`remote GPIO <remote_gpio>`
+feature.
 
 Raspberry Pi
 ============

docs/license.rst

@@ -4,7 +4,7 @@
 License
 =======
 
-Copyright 2015 `Raspberry Pi Foundation`_.
+Copyright 2015-2017 `Raspberry Pi Foundation`_.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -31,4 +31,4 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-.. _Raspberry Pi Foundation: http://raspberrypi.org/
+.. _Raspberry Pi Foundation: https://www.raspberrypi.org/

docs/recipes.rst

@@ -167,6 +167,9 @@ controlled:
 
 .. literalinclude:: examples/led_board_2.py
 
+See more :class:`LEDBoard` examples in the :ref:`advanced LEDBoard recipes
+<ledboard-advanced>`.
+
 LEDBarGraph
 ===========
 
@@ -399,7 +402,7 @@ Alternatively, the following example is identical, but uses the
 :attr:`~SourceMixin.source` property rather than a :keyword:`while` loop:
 
 .. literalinclude:: examples/rgbled_pot_2.py
-    :emphasize-lines: 8
+    :emphasize-lines: 9
 
 .. note::
 

docs/recipes_advanced.rst

@@ -8,6 +8,48 @@ 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!
 
+.. _ledboard-advanced:
+
+LEDBoard
+========
+
+You can iterate over the LEDs in a :class:`LEDBoard` object one-by-one:
+
+.. literalinclude:: examples/led_board_3.py
+
+:class:`LEDBoard` also supports indexing. This means you can access the
+individual :class:`LED` objects using ``leds[i]`` where ``i`` is an integer
+from 0 up to (not including) the number of LEDs:
+
+.. literalinclude:: examples/led_board_4.py
+
+This also means you can use slicing to access a subset of the LEDs:
+
+.. literalinclude:: examples/led_board_5.py
+
+:class:`LEDBoard` objects can have their `LED` objects named upon construction.
+This means the individual LEDs can be accessed by their name:
+
+.. literalinclude:: examples/led_board_6.py
+
+:class:`LEDBoard` objects can also be nested within other :class:`LEDBoard`
+objects:
+
+.. literalinclude:: examples/led_board_7.py
+
+Who's home indicator
+====================
+
+Using a number of green-red LED pairs, you can show the status of who's home,
+according to which IP addresses you can ping successfully. Note that this
+assumes each person's mobile phone has a reserved IP address on the home router.
+
+.. literalinclude:: examples/whos_home_leds.py
+
+Alternatively, using the `STATUS Zero`_ board:
+
+.. literalinclude:: examples/whos_home_status.py
+
 Travis build LED indicator
 ==========================
 
@@ -28,19 +70,6 @@ a Bee-Bot or Turtle robot.
 
 .. literalinclude:: examples/robot_buttons_2.py
 
-Who's home indicator
-====================
-
-Using a number of green-red LED pairs, you can show the status of who's home,
-according to which IP addresses you can ping successfully. Note that this
-assumes each person's mobile phone has a reserved IP address on the home router.
-
-.. literalinclude:: examples/whos_home_leds.py
-
-Alternatively, using the `STATUS Zero`_ board:
-
-.. literalinclude:: examples/whos_home_status.py
-
 Robot controlled by 2 potentiometers
 ====================================
 
@@ -57,8 +86,8 @@ To include reverse direction, scale the potentiometer values from 0-1 to -1-1:
 
 .. literalinclude:: examples/robot_pots_2.py
 
-BlueDot
+BlueDot LED
-=======
+===========
 
 BlueDot is a Python library an Android app which allows you to easily add
 Bluetooth control to your Raspberry Pi project. A simple example to control a
@@ -127,4 +156,4 @@ run the following commands:
 
 .. _travispy: https://travispy.readthedocs.io/
 .. _STATUS Zero: https://thepihut.com/status
-.. _BlueDot documentation: http://bluedot.readthedocs.io/en/latest/index.html
+.. _BlueDot documentation: https://bluedot.readthedocs.io/en/latest/index.html

docs/recipes_remote_gpio.rst

@@ -4,9 +4,10 @@ Remote GPIO Recipes
 
 .. currentmodule:: gpiozero
 
-The following recipes demonstrate some of the capabilities of the feature of the
+The following recipes demonstrate some of the capabilities of the remote GPIO
-GPIO Zero library. Before you start following these examples, please read up on
+feature of the GPIO Zero library. Before you start following these examples,
-preparing your Pi and your host PC to work with :doc:`remote_gpio`.
+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!
@@ -57,7 +58,7 @@ 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
+pressure sensors, but no light sensor. Remote GPIO allows 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:
 

docs/remote_gpio.rst

@@ -21,29 +21,48 @@ used.
 Preparing the Raspberry Pi
 ==========================
 
-If you're using Raspbian Jessie (desktop - not Raspbian Lite) then you have
+If you're using Raspbian (desktop - not Raspbian Lite) then you have everything
-everything you need to use the remote GPIO feature. If you're using Raspbian
+you need to use the remote GPIO feature. If you're using Raspbian Lite, or
-Lite, or another distribution, you'll need to install pigpio:
+another distribution, you'll need to install pigpio:
 
 .. code-block:: console
 
     $ sudo apt install pigpio
 
-Then you just need to enable **Remote GPIO** in the Raspberry Pi configuration
+Alternatively, pigpio is available from `abyz.co.uk`_.
-tool:
+
+You'll need to launch the pigpio daemon on the Raspberry Pi to allow remote
+connections. You can do this in three different ways. Most users will find the
+desktop method the easiest (and can skip to the next section).
+
+Desktop
+-------
+
+On the Raspbian desktop image, enable **Remote GPIO** in the Raspberry Pi
+configuration tool:
 
 .. image:: images/raspi-config.png
 
-(Alternatively, use ``sudo raspi-config`` on the command line)
+This will launch the pigpio daemon automatically.
 
-Then launch the pigpio daemon:
+Command-line: raspi-config
+--------------------------
+
+Alternatively, enter ``sudo raspi-config`` on the command line, and enable
+Remote GPIO. This will also launch the pigpio daemon automatically.
+
+Command-line: manual
+--------------------
+
+Another option is to launch the pigpio daemon manually:
 
 .. code-block:: console
 
     $ sudo pigpiod
 
-To only allow connections from a specific IP address, use the ``-n`` flag. For
+This is for single-use and will not persist after a reboot. However, this method
-example:
+can be used to allow connections from a specific IP address, using the ``-n``
+flag. For example:
 
 .. code-block:: console
 
@@ -51,20 +70,19 @@ example:
     $ 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
+To automate running the daemon at boot time, run:
-feature. To automate running the daemon at boot time:
 
 .. code-block:: console
 
     $ sudo systemctl enable pigpiod
 
-Preparing the host computer
+Preparing the control computer
-===========================
+==============================
 
-If the host computer is a Raspberry Pi running Raspbian Jessie (or a PC running
+If the control computer (the computer you're running your Python code from) is
-Raspbian x86), then you have everything you need. If you're using another Linux
+a Raspberry Pi running Raspbian (or a PC running Raspbian x86), then you have
-distribution, Mac OS or Windows then you'll need to install the ``pigpio``
+everything you need. If you're using another Linux distribution, Mac OS or
-Python library on the PC.
+Windows then you'll need to install the ``pigpio`` Python library on the PC.
 
 Raspberry Pi
 ------------
@@ -213,7 +231,15 @@ will flash the LED connected to pin 17 of the Raspberry Pi with the IP address
     $ 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.
+``192.168.1.4``, without any code changes, as long as the Raspberry Pi has the
+pigpio daemon running.
+
+.. note::
+
+    When running code directly on a Raspberry Pi, any pin factory can be used
+    (assuming the relevant library is installed), but when a device is used
+    remotely, only :class:`PiGPIOFactory` can be used, as pigpio is the only
+    pin library which supports remote GPIO.
 
 Pin objects
 ===========
@@ -231,8 +257,8 @@ This allows devices on multiple Raspberry Pis to be used in the same script:
 
 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
+following script will flash an LED on the controller Pi, and also on another Pi
-the network:
+on the network:
 
 .. literalinclude:: examples/led_remote_3.py
 
@@ -288,30 +314,31 @@ First, configure the boot partition of the SD card:
 3. Edit ``cmdline.txt`` and insert ``modules-load=dwc2,g_ether`` after
    ``rootwait``.
 
-(See `blog.gbaman.info`_ for more information)
+(See guides on `blog.gbaman.info`_ and `learn.adafruit.com`_ for more detailed
+instructions)
 
 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
+using the hostname ``raspberrypi.local``. SSH into the Pi Zero, install pigpio
-GPIO is enabled and the pigpio daemon is running, and you can use remote pins
+and run the pigpio daemon.
-from the computer, referencing the host by its hostname, like so:
 
-.. literalinclude:: examples/pi_zero_remote.py
+Then, drop out of the SSH session and you can run Python code on your computer
+to control devices attached to the Pi Zero, referencing it by its hostname (or
+IP address if you know it), for example:
 
-.. note::
+.. code-block:: console
 
-    When running code directly on a Raspberry Pi, any pin factory can be used
+    $ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=raspberrypi.local python3 led.py
-    (assuming the relevant library is installed), but when a device is used
-    remotely, only :class:`PiGPIOFactory` 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
+.. _abyz.co.uk: http://abyz.co.uk/rpi/pigpio/download.html
 .. _get-pip: https://pip.pypa.io/en/stable/installing/
 .. _following this guide: https://www.raspberrypi.org/learning/using-pip-on-windows/worksheet/
 .. _Sense HAT: https://www.raspberrypi.org/products/sense-hat/
-.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/pi-zero/
+.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/raspberry-pi-zero/
-.. _Pi Zero W: https://www.raspberrypi.org/products/pi-zero-w/
+.. _Pi Zero W: https://www.raspberrypi.org/products/raspberry-pi-zero-w/
 .. _blog.gbaman.info: http://blog.gbaman.info/?p=791
+.. _learn.adafruit.com: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/ethernet-gadget

gpiozero/boards.py

@@ -1249,7 +1249,7 @@ class Robot(SourceMixin, CompositeDevice):
 
 class RyanteckRobot(Robot):
     """
-    Extends :class:`Robot` for the `Ryanteck MCB`_ robot.
+    Extends :class:`Robot` for the `Ryanteck motor controller board`_.
 
     The Ryanteck MCB pins are fixed and therefore there's no need to specify
     them when constructing this class. The following example drives the robot
@@ -1264,7 +1264,7 @@ class RyanteckRobot(Robot):
         See :doc:`api_pins` for more information (this is an advanced feature
         which most users can ignore).
 
-    .. _Ryanteck MCB: https://ryanteck.uk/add-ons/6-ryanteck-rpi-motor-controller-board-0635648607160.html
+    .. _Ryanteck motor controller board: https://ryanteck.uk/add-ons/6-ryanteck-rpi-motor-controller-board-0635648607160.html
     """
 
     def __init__(self, pin_factory=None):
@@ -1275,7 +1275,7 @@ class RyanteckRobot(Robot):
 
 class CamJamKitRobot(Robot):
     """
-    Extends :class:`Robot` for the `CamJam #3 EduKit`_ robot controller.
+    Extends :class:`Robot` for the `CamJam #3 EduKit`_ motor controller board.
 
     The CamJam robot controller pins are fixed and therefore there's no need
     to specify them when constructing this class. The following example drives

setup.py

@@ -22,7 +22,7 @@ except ImportError:
     pass
 
 __project__      = 'gpiozero'
-__version__      = '1.3.2'
+__version__      = '1.4.0'
 __author__       = 'Ben Nuttall'
 __author_email__ = 'ben@raspberrypi.org'
 __url__          = 'https://github.com/RPi-Distro/python-gpiozero'