KevinMidboe/python-gpiozero
1
0
Fork 0
mirror of https://github.com/KevinMidboe/python-gpiozero.git synced 2025-10-29 17:50:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Generic docs need reST

Browse Source 
Conversion of all docs to reST so that the generic docs can link easily
with the rest of the docs.
This commit is contained in:
Dave Jones
2015-10-27 21:08:36 +00:00
parent bcb8758dcf
commit 0bc62aee73
44 changed files with 5315 additions and 2010 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
gpiozero/input_devices.py
View File

@@ -1,3 +1,5 @@
# vim: set fileencoding=utf-8:
from __future__ import (
unicode_literals,
print_function,
@@ -22,19 +24,19 @@ class InputDevice(GPIODevice):
"""
Represents a generic GPIO input device.
This class extends `GPIODevice` to add facilities common to GPIO input
devices. The constructor adds the optional `pull_up` parameter to specify
how the pin should be pulled by the internal resistors. The `is_active`
property is adjusted accordingly so that `True` still means active
regardless of the `pull_up` setting.
This class extends :class:`GPIODevice` to add facilities common to GPIO
input devices. The constructor adds the optional *pull_up* parameter to
specify how the pin should be pulled by the internal resistors. The
:attr:`~GPIODevice.is_active` property is adjusted accordingly so that
``True`` still means active regardless of the :attr:`pull_up` setting.
pin: `None`
The GPIO pin (in BCM numbering) that the device is connected to. If
this is `None` a GPIODeviceError will be raised.
:param int pin:
The GPIO pin (in Broadcom numbering) that the device is connected to.
If this is ``None`` a :exc:`GPIODeviceError` will be raised.
pull_up: `False`
If `True`, the pin will be pulled high with an internal resistor. If
`False` (the default), the pin will be pulled low.
:param bool pull_up:
If ``True``, the pin will be pulled high with an internal resistor. If
``False`` (the default), the pin will be pulled low.
"""
def __init__(self, pin=None, pull_up=False):
if pin in (2, 3) and not pull_up:
@@ -74,8 +76,8 @@ class InputDevice(GPIODevice):
@property
def pull_up(self):
"""
If `True`, the device uses a pull-up resistor to set the GPIO pin
"high" by default. Defaults to `False`.
If ``True``, the device uses a pull-up resistor to set the GPIO pin
"high" by default. Defaults to ``False``.
"""
return self._pull_up
@@ -91,11 +93,11 @@ class WaitableInputDevice(InputDevice):
"""
Represents a generic input device with distinct waitable states.
This class extends `InputDevice` with methods for waiting on the device's
status (`wait_for_active` and `wait_for_inactive`), and properties that
hold functions to be called when the device changes state (`when_activated`
and `when_deactivated`). These are aliased appropriately in various
subclasses.
This class extends :class:`InputDevice` with methods for waiting on the
device's status (:meth:`wait_for_active` and :meth:`wait_for_inactive`),
and properties that hold functions to be called when the device changes
state (:meth:`when_activated` and :meth:`when_deactivated`). These are
aliased appropriately in various subclasses.
Note that this class provides no means of actually firing its events; it's
effectively an abstract base class.
@@ -113,9 +115,9 @@ class WaitableInputDevice(InputDevice):
Pause the script until the device is activated, or the timeout is
reached.
timeout: `None`
Number of seconds to wait before proceeding. If this is `None` (the
default), then wait indefinitely until the device is active.
:param float timeout:
Number of seconds to wait before proceeding. If this is ``None``
(the default), then wait indefinitely until the device is active.
"""
return self._active_event.wait(timeout)
@@ -124,9 +126,9 @@ class WaitableInputDevice(InputDevice):
Pause the script until the device is deactivated, or the timeout is
reached.
timeout: `None`
Number of seconds to wait before proceeding. If this is `None` (the
default), then wait indefinitely until the device is inactive.
:param float timeout:
Number of seconds to wait before proceeding. If this is ``None``
(the default), then wait indefinitely until the device is inactive.
"""
return self._inactive_event.wait(timeout)
@@ -142,9 +144,7 @@ class WaitableInputDevice(InputDevice):
single mandatory parameter, the device that activated will be passed
as that parameter.
Set this property to `None` (the default) to disable the event.
See also: when_deactivated.
Set this property to ``None`` (the default) to disable the event.
"""
return self._when_activated
@@ -164,9 +164,7 @@ class WaitableInputDevice(InputDevice):
single mandatory parameter, the device that deactivated will be
passed as that parameter.
Set this property to `None` (the default) to disable the event.
See also: when_activated.
Set this property to ``None`` (the default) to disable the event.
"""
return self._when_deactivated
@@ -234,15 +232,15 @@ class DigitalInputDevice(WaitableInputDevice):
"""
Represents a generic input device with typical on/off behaviour.
This class extends `WaitableInputDevice` with machinery to fire the active
and inactive events for devices that operate in a typical digital manner:
straight forward on / off states with (reasonably) clean transitions
between the two.
This class extends :class:`WaitableInputDevice` with machinery to fire the
active and inactive events for devices that operate in a typical digital
manner: straight forward on / off states with (reasonably) clean
transitions between the two.
bounce_time: `None`
:param float bouncetime:
Specifies the length of time (in seconds) that the component will
ignore changes in state after an initial change. This defaults to
`None` which indicates that no bounce compensation will be performed.
``None`` which indicates that no bounce compensation will be performed.
"""
def __init__(self, pin=None, pull_up=False, bounce_time=None):
super(DigitalInputDevice, self).__init__(pin, pull_up)
@@ -267,32 +265,33 @@ class SmoothedInputDevice(WaitableInputDevice):
Represents a generic input device which takes its value from the mean of a
queue of historical values.
This class extends `WaitableInputDevice` with a queue which is filled by a
background thread which continually polls the state of the underlying
device. The mean of the values in the queue is compared to a threshold
which is used to determine the state of the `is_active` property.
This class extends :class:`WaitableInputDevice` with a queue which is
filled by a background thread which continually polls the state of the
underlying device. The mean of the values in the queue is compared to a
threshold which is used to determine the state of the :attr:`is_active`
property.
This class is intended for use with devices which either exhibit analog
behaviour (such as the charging time of a capacitor with an LDR), or those
which exhibit "twitchy" behaviour (such as certain motion sensors).
threshold: `0.5`
:param float threshold:
The value above which the device will be considered "on".
queue_len: `5`
:param int queue_len:
The length of the internal queue which is filled by the background
thread.
sample_wait: `0.0`
:param float sample_wait:
The length of time to wait between retrieving the state of the
underlying device. Defaults to 0.0 indicating that values are retrieved
as fast as possible.
partial: `False`
If `False` (the default), attempts to read the state of the device
(from the `is_active` property) will block until the queue has filled.
If `True`, a value will be returned immediately, but be aware that this
value is likely to fluctuate excessively.
:param bool partial:
If ``False`` (the default), attempts to read the state of the device
(from the :attr:`is_active` property) will block until the queue has
filled. If ``True``, a value will be returned immediately, but be
aware that this value is likely to fluctuate excessively.
"""
def __init__(
self, pin=None, pull_up=False, threshold=0.5,
@@ -338,7 +337,7 @@ class SmoothedInputDevice(WaitableInputDevice):
def queue_len(self):
"""
The length of the internal queue of values which is averaged to
determine the overall state of the device. This defaults to `5`.
determine the overall state of the device. This defaults to 5.
"""
self._check_open()
return self._queue.queue.maxlen
@@ -346,8 +345,8 @@ class SmoothedInputDevice(WaitableInputDevice):
@property
def partial(self):
"""
If `False` (the default), attempts to read the `value` or `is_active`
properties will block until the queue has filled.
If ``False`` (the default), attempts to read the :attr:`value` or
:attr:`is_active` properties will block until the queue has filled.
"""
self._check_open()
return self._queue.partial
@@ -355,8 +354,9 @@ class SmoothedInputDevice(WaitableInputDevice):
@property
def value(self):
"""
Returns the mean of the values in the internal queue. This is
compared to `threshold` to determine whether `is_active` is `True`.
Returns the mean of the values in the internal queue. This is compared
to :attr:`threshold` to determine whether :attr:`is_active` is
``True``.
"""
self._check_open()
return self._queue.value
@@ -364,7 +364,8 @@ class SmoothedInputDevice(WaitableInputDevice):
@property
def threshold(self):
"""
If `value` exceeds this amount, then `is_active` will return `True`.
If :attr:`value` exceeds this amount, then :attr:`is_active` will
return ``True``.
"""
return self._threshold
@@ -379,18 +380,44 @@ class SmoothedInputDevice(WaitableInputDevice):
@property
def is_active(self):
"""
Returns `True` if the device is currently active and `False` otherwise.
Returns ``True`` if the device is currently active and ``False``
otherwise.
"""
return self.value > self.threshold
class Button(DigitalInputDevice):
"""
A physical push button or switch.
Extends :class:`DigitalInputDevice` and represents a simple push button
or switch.
A typical configuration of such a device is to connect a GPIO pin to one
side of the switch, and ground to the other (the default `pull_up` value
is `True`).
Connect one side of the button to a ground pin, and the other to any GPIO
pin. Alternatively, connect one side of the button to the 3V3 pin, and the
other to any GPIO pin, then set *pull_up* to ``False`` in the
:class:`Button` constructor.
The following example will print a line of text when the button is pushed::
from gpiozero import Button
button = Button(4)
button.wait_for_press()
print("The button was pressed!")
:param int pin:
The GPIO pin which the button is attached to. See :doc:`notes` for
valid pin numbers.
:param bool pull_up:
If ``True`` (the default), the GPIO pin will be pulled high by default.
In this case, connect the other side of the button to ground. If
``False``, the GPIO pin will be pulled low by default. In this case,
connect the other side of the button to 3V3.
:param float bounce_time:
If ``None`` (the default), no software bounce compensation will be
performed. Otherwise, this is the length in time (in seconds) that the
component will ignore changes in state after an initial change.
"""
def __init__(self, pin=None, pull_up=True, bounce_time=None):
super(Button, self).__init__(pin, pull_up, bounce_time)
@@ -418,17 +445,48 @@ LineSensor.wait_for_no_line = LineSensor.wait_for_inactive
class MotionSensor(SmoothedInputDevice):
"""
A PIR (Passive Infra-Red) motion sensor.
Extends :class:`SmoothedInputDevice` and represents a passive infra-red
(PIR) motion sensor like the sort found in the `CamJam #2 EduKit`_.
.. _CamJam #2 EduKit: http://camjam.me/?page_id=623
A typical PIR device has a small circuit board with three pins: VCC, OUT,
and GND. VCC should be connected to the Pi's +5V pin, GND to one of the
Pi's ground pins, and finally OUT to the GPIO specified as the value of the
`pin` parameter in the constructor.
and GND. VCC should be connected to a 5V pin, GND to one of the ground
pins, and finally OUT to the GPIO specified as the value of the *pin*
parameter in the constructor.
This class defaults `queue_len` to 1, effectively removing the averaging
of the internal queue. If your PIR sensor has a short fall time and is
particularly "jittery" you may wish to set this to a higher value (e.g. 5)
to mitigate this.
The following code will print a line of text when motion is detected::
from gpiozero import MotionSensor
pir = MotionSensor(4)
pir.wait_for_motion()
print("Motion detected!")
:param int pin:
The GPIO pin which the button is attached to. See :doc:`notes` for
valid pin numbers.
:param int queue_len:
The length of the queue used to store values read from the sensor. This
defaults to 1 which effectively disables the queue. If your motion
sensor is particularly "twitchy" you may wish to increase this value.
:param float sample_rate:
The number of values to read from the device (and append to the
internal queue) per second. Defaults to 10.
:param float threshold:
Defaults to 0.5. When the mean of all values in the internal queue
rises above this value, the sensor will be considered "active" by the
:attr:`~SmoothedInputDevice.is_active` property, and all appropriate
events will be fired.
:param bool partial:
When ``False`` (the default), the object will not return a value for
:attr:`~SmoothedInputDevice.is_active` until the internal queue has
filled with values. Only set this to ``True`` if you require values
immediately after object construction.
"""
def __init__(
self, pin=None, queue_len=1, sample_rate=10, threshold=0.5,
@@ -452,12 +510,50 @@ MotionSensor.wait_for_no_motion = MotionSensor.wait_for_inactive
class LightSensor(SmoothedInputDevice):
"""
An LDR (Light Dependent Resistor) Light Sensor.
Extends :class:`SmoothedInputDevice` and represents a light dependent
resistor (LDR).
A typical LDR circuit connects one side of the LDR to the 3v3 line from the
Pi, and the other side to a GPIO pin, and a capacitor tied to ground. This
class repeatedly discharges the capacitor, then times the duration it takes
to charge (which will vary according to the light falling on the LDR).
Connect one leg of the LDR to the 3V3 pin; connect one leg of a 1µf
capacitor to a ground pin; connect the other leg of the LDR and the other
leg of the capacitor to the same GPIO pin. This class repeatedly discharges
the capacitor, then times the duration it takes to charge (which will vary
according to the light falling on the LDR).
The following code will print a line of text when light is detected::
from gpiozero import LightSensor
ldr = LightSensor(18)
ldr.wait_for_light()
print("Light detected!")
:param int pin:
The GPIO pin which the button is attached to. See :doc:`notes` for
valid pin numbers.
:param int queue_len:
The length of the queue used to store values read from the circuit.
This defaults to 5.
:param float charge_time_limit:
If the capacitor in the circuit takes longer than this length of time
to charge, it is assumed to be dark. The default (0.01 seconds) is
appropriate for a 0.01µf capacitor coupled with the LDR from the
`CamJam #2 EduKit`_. You may need to adjust this value for different
valued capacitors or LDRs.
:param float threshold:
Defaults to 0.1. When the mean of all values in the internal queue
rises above this value, the area will be considered "light", and all
appropriate events will be fired.
:param bool partial:
When ``False`` (the default), the object will not return a value for
:attr:`~SmoothedInputDevice.is_active` until the internal queue has
filled with values. Only set this to ``True`` if you require values
immediately after object construction.
.. _CamJam #2 EduKit: http://camjam.me/?page_id=623
"""
def __init__(
self, pin=None, queue_len=5, charge_time_limit=0.01,
@@ -506,6 +602,31 @@ LightSensor.wait_for_dark = LightSensor.wait_for_inactive
class AnalogInputDevice(CompositeDevice):
"""
Represents an analog input device connected to SPI (serial interface).
Typical analog input devices are `analog to digital converters`_ (ADCs).
Several classes are provided for specific ADC chips, including
:class:`MCP3004`, :class:`MCP3008`, :class:`MCP3204`, and :class:`MCP3208`.
The following code demonstrates reading the first channel of an MCP3008
chip attached to the Pi's SPI pins::
from gpiozero import MCP3008
pot = MCP3008(0)
print(pot.value)
The :attr:`value` attribute is normalized such that its value is always
between 0.0 and 1.0 (or in special cases, such as differential sampling,
-1 to +1). Hence, you can use an analog input to control the brightness of
a :class:`PWMLED` like so::
from gpiozero import MCP3008, PWMLED
pot = MCP3008(0)
led = PWMLED(17)
led.source = pot.values
.. _analog to digital converters: https://en.wikipedia.org/wiki/Analog-to-digital_converter
"""
def __init__(self, device=0, bits=None):
@@ -572,6 +693,11 @@ class AnalogInputDevice(CompositeDevice):
class MCP3xxx(AnalogInputDevice):
"""
Extends :class:`AnalogInputDevice` to implement an interface for all ADC
chips with a protocol similar to the Microchip MCP3xxx series of devices.
"""
def __init__(self, channel=0, device=0, bits=10, differential=False):
self._channel = channel
self._bits = bits
@@ -583,20 +709,22 @@ class MCP3xxx(AnalogInputDevice):
"""
The channel to read data from. The MCP3008/3208/3304 have 8 channels
(0-7), while the MCP3004/3204/3302 have 4 channels (0-3), and the
MCP3301 only has 2 channels.
MCP3301 only has 1 channel.
"""
return self._channel
@property
def differential(self):
"""
If True, the device is operated in pseudo-differential mode. In this
mode one channel (specified by the channel attribute) is read relative
to the value of a second channel (implied by the chip's design).
If ``True``, the device is operated in pseudo-differential mode. In
this mode one channel (specified by the channel attribute) is read
relative to the value of a second channel (implied by the chip's
design).
Please refer to the device data-sheet to determine which channel is
used as the relative base value (for example, when using an MCP3008
in differential mode, channel 0 is read relative to channel 1).
used as the relative base value (for example, when using an
:class:`MCP3008` in differential mode, channel 0 is read relative to
channel 1).
"""
return self._differential
@@ -625,6 +753,12 @@ class MCP3xxx(AnalogInputDevice):
class MCP33xx(MCP3xxx):
"""
Extends :class:`MCP3xxx` with functionality specific to the MCP33xx family
of ADCs; specifically this handles the full differential capability of
these chips supporting the full 13-bit signed range of output values.
"""
def __init__(self, channel=0, device=0, differential=False):
super(MCP33xx, self).__init__(channel, device, 12, differential)
@@ -669,7 +803,10 @@ class MCP33xx(MCP3xxx):
class MCP3004(MCP3xxx):
"""
The MCP3004 is a 10-bit analog to digital converter with 4 channels (0-3).
The `MCP3004`_ is a 10-bit analog to digital converter with 4 channels
(0-3).
.. _MCP3004: http://www.farnell.com/datasheets/808965.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 4:
@@ -679,7 +816,10 @@ class MCP3004(MCP3xxx):
class MCP3008(MCP3xxx):
"""
The MCP3008 is a 10-bit analog to digital converter with 8 channels (0-7).
The `MCP3008`_ is a 10-bit analog to digital converter with 8 channels
(0-7).
.. _MCP3008: http://www.farnell.com/datasheets/808965.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 8:
@@ -689,7 +829,10 @@ class MCP3008(MCP3xxx):
class MCP3204(MCP3xxx):
"""
The MCP3204 is a 12-bit analog to digital converter with 4 channels (0-3).
The `MCP3204`_ is a 12-bit analog to digital converter with 4 channels
(0-3).
.. _MCP3204: http://www.farnell.com/datasheets/808967.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 4:
@@ -699,7 +842,10 @@ class MCP3204(MCP3xxx):
class MCP3208(MCP3xxx):
"""
The MCP3208 is a 12-bit analog to digital converter with 8 channels (0-7).
The `MCP3208`_ is a 12-bit analog to digital converter with 8 channels
(0-7).
.. _MCP3208: http://www.farnell.com/datasheets/808967.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 8:
@@ -709,9 +855,11 @@ class MCP3208(MCP3xxx):
class MCP3301(MCP33xx):
"""
The MCP3301 is a signed 13-bit analog to digital converter. Please note
The `MCP3301`_ is a signed 13-bit analog to digital converter. Please note
that the MCP3301 always operates in differential mode between its two
channels and the output value is scaled from -1 to +1.
.. _MCP3301: http://www.farnell.com/datasheets/1669397.pdf
"""
def __init__(self, device=0):
super(MCP3301, self).__init__(0, device, differential=True)
@@ -722,11 +870,13 @@ class MCP3301(MCP33xx):
class MCP3302(MCP33xx):
"""
The MCP3302 is a 12/13-bit analog to digital converter with 4 channels
The `MCP3302`_ is a 12/13-bit analog to digital converter with 4 channels
(0-3). When operated in differential mode, the device outputs a signed
13-bit value which is scaled from -1 to +1. When operated in single-ended
mode (the default), the device outputs an unsigned 12-bit value scaled from
0 to 1.
.. _MCP3302: http://www.farnell.com/datasheets/1486116.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 4:
@@ -736,11 +886,13 @@ class MCP3302(MCP33xx):
class MCP3304(MCP33xx):
"""
The MCP3304 is a 12/13-bit analog to digital converter with 8 channels
The `MCP3304`_ is a 12/13-bit analog to digital converter with 8 channels
(0-7). When operated in differential mode, the device outputs a signed
13-bit value which is scaled from -1 to +1. When operated in single-ended
mode (the default), the device outputs an unsigned 12-bit value scaled from
0 to 1.
.. _MCP3304: http://www.farnell.com/datasheets/1486116.pdf
"""
def __init__(self, channel=0, device=0, differential=False):
if not 0 <= channel < 8: