.. GPIO Zero: a library for controlling the Raspberry Pi's GPIO pins .. .. Copyright (c) 2015-2023 Dave Jones .. Copyright (c) 2019-2021 Ben Nuttall .. .. SPDX-License-Identifier: BSD-3-Clause ========== API - Pins ========== .. module:: gpiozero.pins .. currentmodule:: gpiozero As of release 1.1, the GPIO Zero library can be roughly divided into two things: pins and the devices that are connected to them. The majority of the documentation focuses on devices as pins are below the level that most users are concerned with. However, some users may wish to take advantage of the capabilities of alternative GPIO implementations or (in future) use GPIO extender chips. This is the purpose of the pins portion of the library. When you construct a device, you pass in a pin specification. This is passed to a pin :class:`Factory` which turns it into a :class:`Pin` implementation. The default factory can be queried (and changed) with :attr:`Device.pin_factory`. However, all classes (even internal devices) accept a *pin_factory* keyword argument to their constructors permitting the factory to be overridden on a per-device basis (the reason for allowing per-device factories is made apparent in the :doc:`remote_gpio` chapter). This is illustrated in the following flow-chart: .. image:: images/device_pin_flowchart.* :align: center The default factory is constructed when the first device is initialised; if no default factory can be constructed (e.g. because no GPIO implementations are installed, or all of them fail to load for whatever reason), a :exc:`BadPinFactory` exception will be raised at construction time. After importing gpiozero, until constructing a gpiozero device, the pin factory is :data:`None`, but at the point of first construction the default pin factory will come into effect: .. code-block:: console pi@raspberrypi:~ $ python3 Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from gpiozero import Device, LED >>> print(Device.pin_factory) None >>> led = LED(2) >>> Device.pin_factory >>> led.pin_factory As above, on a Raspberry Pi with the RPi.GPIO library installed, (assuming no environment variables are set), the default pin factory will be :class:`~gpiozero.pins.rpigpio.RPiGPIOFactory`. On a PC (with no pin libraries installed and no environment variables set), importing will work but attempting to create a device will raise :exc:`BadPinFactory`: .. code-block:: console ben@magicman:~ $ python3 Python 3.6.8 (default, Aug 20 2019, 17:12:48) [GCC 8.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from gpiozero import Device, LED >>> print(Device.pin_factory) None >>> led = LED(2) ... BadPinFactory: Unable to load any default pin factory! .. _changing-pin-factory: Changing the pin factory ======================== The default pin factory can be replaced by specifying a value for the :envvar:`GPIOZERO_PIN_FACTORY` environment variable. For example: .. code-block:: console pi@raspberrypi:~ $ GPIOZERO_PIN_FACTORY=native python3 Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from gpiozero import Device >>> Device._default_pin_factory() To set the :envvar:`GPIOZERO_PIN_FACTORY` for the rest of your session you can :command:`export` this value: .. code-block:: console pi@raspberrypi:~ $ export GPIOZERO_PIN_FACTORY=native pi@raspberrypi:~ $ python3 Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import gpiozero >>> Device._default_pin_factory() >>> quit() pi@raspberrypi:~ $ python3 Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import gpiozero >>> Device._default_pin_factory() If you add the :command:`export` command to your :file:`~/.bashrc` file, you'll set the default pin factory for all future sessions too. If the environment variable is set, the corresponding pin factory will be used, otherwise each of the four GPIO pin factories will be attempted to be used in turn. The following values, and the corresponding :class:`Factory` and :class:`Pin` classes are listed in the table below. Factories are listed in the order that they are tried by default. +---------+-----------------------------------------------+-------------------------------------------+ | Name | Factory class | Pin class | +=========+===============================================+===========================================+ | lgpio | :class:`gpiozero.pins.lgpio.LGPIOFactory` | :class:`gpiozero.pins.lgpio.LGPIOPin` | +---------+-----------------------------------------------+-------------------------------------------+ | rpigpio | :class:`gpiozero.pins.rpigpio.RPiGPIOFactory` | :class:`gpiozero.pins.rpigpio.RPiGPIOPin` | +---------+-----------------------------------------------+-------------------------------------------+ | pigpio | :class:`gpiozero.pins.pigpio.PiGPIOFactory` | :class:`gpiozero.pins.pigpio.PiGPIOPin` | +---------+-----------------------------------------------+-------------------------------------------+ | native | :class:`gpiozero.pins.native.NativeFactory` | :class:`gpiozero.pins.native.NativePin` | +---------+-----------------------------------------------+-------------------------------------------+ If you need to change the default pin factory from within a script, either set :attr:`Device.pin_factory` to the new factory instance to use:: from gpiozero.pins.native import NativeFactory from gpiozero import Device, LED Device.pin_factory = NativeFactory() # These will now implicitly use NativePin instead of RPiGPIOPin led1 = LED(16) led2 = LED(17) Or use the *pin_factory* keyword parameter mentioned above:: from gpiozero.pins.native import NativeFactory from gpiozero import LED my_factory = NativeFactory() # This will use NativePin instead of RPiGPIOPin for led1 # but led2 will continue to use RPiGPIOPin led1 = LED(16, pin_factory=my_factory) led2 = LED(17) Certain factories may take default information from additional sources. For example, to default to creating pins with :class:`gpiozero.pins.pigpio.PiGPIOPin` on a remote pi called "remote-pi" you can set the :envvar:`PIGPIO_ADDR` environment variable when running your script: .. code-block:: console $ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=remote-pi python3 my_script.py Like the :envvar:`GPIOZERO_PIN_FACTORY` value, these can be exported from your :file:`~/.bashrc` script too. .. warning:: The astute and mischievous reader may note that it is possible to mix factories, e.g. using :class:`~gpiozero.pins.rpigpio.RPiGPIOFactory` for one pin, and :class:`~gpiozero.pins.native.NativeFactory` for another. This is unsupported, and if it results in your script crashing, your components failing, or your Raspberry Pi turning into an actual raspberry pie, you have only yourself to blame. Sensible uses of multiple pin factories are given in :doc:`remote_gpio`. .. _mock-pins: Mock pins ========= There's also a :class:`~gpiozero.pins.mock.MockFactory` which generates entirely fake pins. This was originally intended for GPIO Zero developers who wish to write tests for devices without having to have the physical device wired in to their Pi. However, they have also proven useful in developing GPIO Zero scripts without having a Pi to hand. This pin factory will never be loaded by default; it must be explicitly specified, either by setting an environment variable or setting the pin factory within the script. For example: .. code-block:: console pi@raspberrypi:~ $ GPIOZERO_PIN_FACTORY=mock python3 or: .. code-block:: python from gpiozero import Device, LED from gpiozero.pins.mock import MockFactory Device.pin_factory = MockFactory() led = LED(2) You can create device objects and inspect their value changing as you'd expect: .. code-block:: pycon pi@raspberrypi:~ $ GPIOZERO_PIN_FACTORY=mock python3 Python 3.7.3 (default, Apr 3 2019, 05:39:12) [GCC 8.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from gpiozero import LED >>> led = LED(2) >>> led.value 0 >>> led.on() >>> led.value 1 You can even control pin state changes to simulate device behaviour: .. code-block:: pycon >>> from gpiozero import LED, Button # Construct a couple of devices attached to mock pins 16 and 17, and link the devices >>> led = LED(17) >>> btn = Button(16) >>> led.source = btn # Initailly the button isn't "pressed" so the LED should be off >>> led.value 0 # Drive the pin low (this is what would happen electrically when the button is pressed) >>> btn.pin.drive_low() # The LED is now on >>> led.value 1 >>> btn.pin.drive_high() # The button is now "released", so the LED should be off again >>> led.value 0 Several sub-classes of mock pins exist for emulating various other things (pins that do/don't support PWM, pins that are connected together, pins that drive high after a delay, etc), for example, you have to use :class:`~gpiozero.pins.mock.MockPWMPin` to be able to use devices requiring PWM: .. code-block:: console pi@raspberrypi:~ $ GPIOZERO_PIN_FACTORY=mock GPIOZERO_MOCK_PIN_CLASS=mockpwmpin python3 or: .. code-block:: python from gpiozero import Device, LED from gpiozero.pins.mock import MockFactory, MockPWMPin Device.pin_factory = MockFactory(pin_class=MockPWMPin) led = LED(2) Interested users are invited to read the `GPIO Zero test suite`_ for further examples of usage. .. _`GPIO Zero test suite`: https://github.com/gpiozero/gpiozero/tree/master/tests Base classes ============ .. autoclass:: Factory :members: .. autoclass:: Pin :members: .. autoclass:: SPI :members: .. module:: gpiozero.pins.pi .. autoclass:: gpiozero.pins.pi.PiFactory :members: .. autoclass:: gpiozero.pins.pi.PiPin :members: .. module:: gpiozero.pins.local .. autoclass:: LocalPiFactory :members: .. autoclass:: LocalPiPin :members: RPi.GPIO ======== .. module:: gpiozero.pins.rpigpio .. autoclass:: gpiozero.pins.rpigpio.RPiGPIOFactory .. autoclass:: gpiozero.pins.rpigpio.RPiGPIOPin lgpio ===== .. module:: gpiozero.pins.lgpio .. autoclass:: gpiozero.pins.lgpio.LGPIOFactory .. autoclass:: gpiozero.pins.lgpio.LGPIOPin PiGPIO ====== .. module:: gpiozero.pins.pigpio .. autoclass:: gpiozero.pins.pigpio.PiGPIOFactory .. autoclass:: gpiozero.pins.pigpio.PiGPIOPin Native ====== .. module:: gpiozero.pins.native .. autoclass:: gpiozero.pins.native.NativeFactory .. autoclass:: gpiozero.pins.native.NativePin .. autoclass:: gpiozero.pins.native.Native2835Pin .. autoclass:: gpiozero.pins.native.Native2711Pin Mock ==== .. module:: gpiozero.pins.mock .. autoclass:: gpiozero.pins.mock.MockFactory :members: .. autoclass:: gpiozero.pins.mock.MockPin .. autoclass:: gpiozero.pins.mock.MockPWMPin .. autoclass:: gpiozero.pins.mock.MockConnectedPin .. autoclass:: gpiozero.pins.mock.MockChargingPin .. autoclass:: gpiozero.pins.mock.MockTriggerPin .. autoclass:: gpiozero.pins.mock.MockSPIDevice