diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..5ffc23d --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,86 @@ +.. _faq: + +========================== +Frequently Asked Questions +========================== + +.. currentmodule:: gpiozero + + +My event handler isn't being called? +==================================== + +When assigning event handlers, don't call the function you're assigning. For +example:: + + from gpiozero import Button + + def pushed(): + print("Don't push the button!") + + b = Button(17) + b.when_pressed = pushed() + +In the case above, when assigning to the ``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:: + + b.when_pressed = None + +This doesn't raise an error because it's perfectly valid: it's what you assign +when you don't want the event handler to do anything. Instead, you want to +do the following:: + + b.when_pressed = pushed + +This will assign the function to the event handler *without calling it*. This +is the crucial difference between ``my_function`` (a reference to a function) +and ``my_function()`` (the result of calling a function). + + +Why do I get PinFactoryFallback warnings when I import gpiozero? +================================================================ + +You are most likely working in a virtual Python environment and have forgotten +to install a pin driver library like ``RPi.GPIO``. GPIO Zero relies upon lower +level pin drivers to handle interfacing to the GPIO pins on the Raspberry Pi, +so you can eliminate the warning simply by installing GPIO Zero's first +preference: + +.. code-block:: console + + $ pip install rpi.gpio + +When GPIO Zero is imported it attempts to find a pin driver by importing them +in a preferred order (detailed in :doc:`api_pins`). If it fails to load its +first preference (``RPi.GPIO``) it notifies you with a warning, then falls back +to trying its second preference and so on. Eventually it will fall back all the +way to the ``native`` implementation. This is a pure Python implementation +built into GPIO Zero itself. While this will work for most things it's almost +certainly not what you want (it doesn't support PWM, and it's quite slow at +certain things). + +If you want to use a pin driver other than the default, and you want to +suppress the warnings you've got a couple of options: + +1. Explicitly specify what pin driver you want via an environment variable. For + example: + + .. code-block:: console + + $ GPIOZERO_PIN_FACTORY=pigpio python + + 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 + be raised. + +2. Suppress the warnings and let the fallback mechanism work:: + + >>> import warnings + >>> warnings.simplefilter('ignore') + >>> import gpiozero + + Refer to the :mod:`warnings` module documentation for more refined ways to + filter out specific warning classes. + diff --git a/docs/index.rst b/docs/index.rst index f2deb81..c3d385e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ Table of Contents remote_gpio recipes_advanced recipes_remote_gpio + faq contributing development changelog