diff --git a/.gitignore b/.gitignore index 583b828..54cf950 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ coverage # Generated documentation docs/_build +man/ diff --git a/Makefile b/Makefile index 4d7961c..000256b 100644 --- a/Makefile +++ b/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 diff --git a/README.rst b/README.rst index 736c99e..8830570 100644 --- a/README.rst +++ b/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 -.. _Contributing: http://gpiozero.readthedocs.io/en/latest/contributing.html -.. _Development: http://gpiozero.readthedocs.io/en/latest/development.html -.. _Installing: http://gpiozero.readthedocs/io/en/latest/installing.html +.. _Recipes: https://gpiozero.readthedocs.io/en/stable/recipes.html +.. _Contributing: https://gpiozero.readthedocs.io/en/stable/contributing.html +.. _Development: https://gpiozero.readthedocs.io/en/stable/development.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 diff --git a/debian/rules b/debian/rules index 0f66107..00f3387 100755 --- a/debian/rules +++ b/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! diff --git a/docs/api_pins.rst b/docs/api_pins.rst index e15017f..bec1dae 100644 --- a/docs/api_pins.rst +++ b/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 ======================== diff --git a/docs/api_tools.rst b/docs/api_tools.rst index 76e16d1..83aeaa1 100644 --- a/docs/api_tools.rst +++ b/docs/api_tools.rst @@ -1,6 +1,6 @@ -==================== -API - Device Sources -==================== +========================= +API - Device Source Tools +========================= .. module:: gpiozero.tools diff --git a/docs/changelog.rst b/docs/changelog.rst index cab5024..9f607f3 100644 --- a/docs/changelog.rst +++ b/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 + ` 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 + `, better charts, more recipes, :doc:`remote GPIO + configuration `, 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) ========================== diff --git a/docs/cli_pinout.rst b/docs/cli_pinout.rst new file mode 100644 index 0000000..dddc2d7 --- /dev/null +++ b/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 diff --git a/docs/cli_tools.rst b/docs/cli_tools.rst index 1b1443d..757d7d2 100644 --- a/docs/cli_tools.rst +++ b/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 -tool to output details of the GPIO pins available. +revisions of Raspberry Pi. This is queried by the :program:`pinout` +command-line tool to output details of the GPIO pins available. -Unless specified, the revision of the current device will be detected. A -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 +.. include:: cli_pinout.rst diff --git a/docs/conf.py b/docs/conf.py index fbbe280..ce35da0 100644 --- a/docs/conf.py +++ b/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 ------------------------------------------- diff --git a/docs/development.rst b/docs/development.rst index 3dcc75c..8d64ab8 100644 --- a/docs/development.rst +++ b/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 diff --git a/docs/examples/led_board_2.py b/docs/examples/led_board_2.py index 2b01a6d..aa7efbc 100644 --- a/docs/examples/led_board_2.py +++ b/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() diff --git a/docs/examples/led_board_3.py b/docs/examples/led_board_3.py new file mode 100644 index 0000000..0bb4f8a --- /dev/null +++ b/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() diff --git a/docs/examples/led_board_4.py b/docs/examples/led_board_4.py new file mode 100644 index 0000000..62b9b6b --- /dev/null +++ b/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) diff --git a/docs/examples/led_board_5.py b/docs/examples/led_board_5.py new file mode 100644 index 0000000..f329f39 --- /dev/null +++ b/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() diff --git a/docs/examples/led_board_6.py b/docs/examples/led_board_6.py new file mode 100644 index 0000000..8710cb2 --- /dev/null +++ b/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) diff --git a/docs/examples/led_board_7.py b/docs/examples/led_board_7.py new file mode 100644 index 0000000..5bfefe8 --- /dev/null +++ b/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) diff --git a/docs/examples/pi_zero_remote.py b/docs/examples/pi_zero_remote.py deleted file mode 100644 index 086683a..0000000 --- a/docs/examples/pi_zero_remote.py +++ /dev/null @@ -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() diff --git a/docs/faq.rst b/docs/faq.rst index 59f4631..618791f 100644 --- a/docs/faq.rst +++ b/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 -the ``pip`` utility. This can be done with the following command in Raspbian: +If you receive the error ``No module named pkg_resources``, you need to install +``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() - diff --git a/docs/images/pinout_pi3.png b/docs/images/pinout_pi3.png new file mode 100644 index 0000000..a3ba926 Binary files /dev/null and b/docs/images/pinout_pi3.png differ diff --git a/docs/images/pinout_pizero_w.png b/docs/images/pinout_pizero_w.png new file mode 100644 index 0000000..b5940e7 Binary files /dev/null and b/docs/images/pinout_pizero_w.png differ diff --git a/docs/installing.rst b/docs/installing.rst index 7b75927..836a943 100644 --- a/docs/installing.rst +++ b/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 ` +feature. Raspberry Pi ============ diff --git a/docs/license.rst b/docs/license.rst index 31ca3e0..7743470 100644 --- a/docs/license.rst +++ b/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/ diff --git a/docs/recipes.rst b/docs/recipes.rst index dc7fdba..a399dad 100644 --- a/docs/recipes.rst +++ b/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 +`. + 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:: diff --git a/docs/recipes_advanced.rst b/docs/recipes_advanced.rst index 5feecfd..6ed634b 100644 --- a/docs/recipes_advanced.rst +++ b/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 diff --git a/docs/recipes_remote_gpio.rst b/docs/recipes_remote_gpio.rst index 7eb1433..bf131d6 100644 --- a/docs/recipes_remote_gpio.rst +++ b/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 -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`. +The following recipes demonstrate some of the capabilities of the remote GPIO +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! @@ -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: diff --git a/docs/remote_gpio.rst b/docs/remote_gpio.rst index 2d19778..c2aeffe 100644 --- a/docs/remote_gpio.rst +++ b/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 -everything you need to use the remote GPIO feature. If you're using Raspbian -Lite, or another distribution, you'll need to install pigpio: +If you're using Raspbian (desktop - not Raspbian Lite) then you have everything +you need to use the remote GPIO feature. If you're using Raspbian Lite, or +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 -tool: +Alternatively, pigpio is available from `abyz.co.uk`_. + +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 -example: +This is for single-use and will not persist after a reboot. However, this method +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 -feature. To automate running the daemon at boot time: +To automate running the daemon at boot time, run: .. 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 -Raspbian x86), 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. +If the control computer (the computer you're running your Python code from) is +a Raspberry Pi running Raspbian (or a PC running Raspbian x86), 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 ------------ @@ -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 -the network: +following script will flash an LED on the controller Pi, and also on another Pi +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 -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: +using the hostname ``raspberrypi.local``. SSH into the Pi Zero, install pigpio +and run the pigpio daemon. -.. 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 - (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. + $ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=raspberrypi.local python3 led.py .. _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/ -.. _Pi Zero W: https://www.raspberrypi.org/products/pi-zero-w/ +.. _Raspberry Pi Zero: https://www.raspberrypi.org/products/raspberry-pi-zero/ +.. _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 diff --git a/gpiozero/boards.py b/gpiozero/boards.py index 20d819c..c6b6abf 100644 --- a/gpiozero/boards.py +++ b/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 diff --git a/setup.py b/setup.py index b0f590c..12bb7e6 100644 --- a/setup.py +++ b/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'