KevinMidboe/python-gpiozero
1
0
Fork 0
mirror of https://github.com/KevinMidboe/python-gpiozero.git synced 2025-12-08 20:39:01 +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

8
gpiozero/__init__.py
View File

@@ -13,9 +13,16 @@ from .exc import (
)
from .devices import (
GPIODevice,
CompositeDevice,
SourceMixin,
ValuesMixin,
)
from .input_devices import (
InputDevice,
WaitableInputDevice,
DigitalInputDevice,
SmoothedInputDevice,
AnalogInputDevice,
Button,
LineSensor,
MotionSensor,
@@ -31,6 +38,7 @@ from .input_devices import (
)
from .output_devices import (
OutputDevice,
DigitalOutputDevice,
PWMOutputDevice,
PWMLED,
LED,

241
gpiozero/boards.py
View File

@@ -20,7 +20,25 @@ from .devices import CompositeDevice, SourceMixin
class LEDBoard(SourceMixin, CompositeDevice):
"""
A Generic LED Board or collection of LEDs.
Extends :class:`CompositeDevice` and represents a generic LED board or
collection of LEDs.
The following example turns on all the LEDs on a board containing 5 LEDs
attached to GPIO pins 2 through 6::
from gpiozero import LEDBoard
leds = LEDBoard(2, 3, 4, 5, 6)
leds.on()
:param int \*pins:
Specify the GPIO pins that the LEDs of the board are attached to. You
can designate as many pins as necessary.
:param bool pwm:
If ``True``, construct :class:`PWMLED` instances for each pin. If
``False`` (the default), construct regular :class:`LED` instances. This
parameter can only be specified as a keyword parameter.
"""
def __init__(self, *pins, **kwargs):
super(LEDBoard, self).__init__()
@@ -39,15 +57,16 @@ class LEDBoard(SourceMixin, CompositeDevice):
@property
def leds(self):
"""
A tuple of all the `LED` objects contained by the instance.
A tuple of all the :class:`LED` or :class:`PWMLED` objects contained by
the instance.
"""
return self._leds
@property
def value(self):
"""
A tuple containing a boolean value for each LED on the board. This
property can also be set to update the state of all LEDs on the board.
A tuple containing a value for each LED on the board. This property can
also be set to update the state of all LEDs on the board.
"""
return tuple(led.value for led in self._leds)
@@ -82,19 +101,19 @@ class LEDBoard(SourceMixin, CompositeDevice):
"""
Make all the LEDs turn on and off repeatedly.
on_time: `1`
Number of seconds to be on
:param float on_time:
Number of seconds on
off_time: `1`
Number of seconds to be off
:param float off_time:
Number of seconds off
n: `None`
Number of times to blink; None means forever
:param int n:
Number of times to blink; ``None`` means forever
background: `True`
If `True`, start a background thread to continue blinking and
return immediately. If `False`, only return when the blink is
finished (warning: the default value of `n` will result in this
:param bool background:
If ``True``, start a background thread to continue blinking and
return immediately. If ``False``, only return when the blink is
finished (warning: the default value of *n* will result in this
method never returning).
"""
# XXX This isn't going to work for background=False
@@ -104,7 +123,22 @@ class LEDBoard(SourceMixin, CompositeDevice):
class PiLiter(LEDBoard):
"""
Ciseco Pi-LITEr: strip of 8 very bright LEDs.
Extends :class:`LEDBoard` for the Ciseco Pi-LITEr: a strip of 8 very bright
LEDs.
The Pi-LITEr pins are fixed and therefore there's no need to specify them
when constructing this class. The following example turns on all the LEDs
of the Pi-LITEr::
from gpiozero import PiLiter
lite = PiLiter()
lite.on()
:param bool pwm:
If ``True``, construct :class:`PWMLED` instances for each pin. If
``False`` (the default), construct regular :class:`LED` instances. This
parameter can only be specified as a keyword parameter.
"""
def __init__(self, pwm=False):
super(PiLiter, self).__init__(4, 17, 27, 18, 22, 23, 24, 25, pwm=pwm)
@@ -115,16 +149,30 @@ TrafficLightTuple = namedtuple('TrafficLightTuple', ('red', 'amber', 'green'))
class TrafficLights(LEDBoard):
"""
Generic Traffic Lights set.
Extends :class:`LEDBoard` for devices containing red, amber, and green
LEDs.
red: `None`
Red LED pin
The following example initializes a device connected to GPIO pins 2, 3,
and 4, then lights the amber LED attached to GPIO 3::
amber: `None`
Amber LED pin
from gpiozero import TrafficLights
green: `None`
Green LED pin
traffic = TrafficLights(2, 3, 4)
traffic.amber.on()
:param int red:
The GPIO pin that the red LED is attached to.
:param int amber:
The GPIO pin that the amber LED is attached to.
:param int green:
The GPIO pin that the green LED is attached to.
:param bool pwm:
If ``True``, construct :class:`PWMLED` instances to represent each
LED. If ``False`` (the default), construct regular :class:`LED`
instances.
"""
def __init__(self, red=None, amber=None, green=None, pwm=False):
if not all([red, amber, green]):
@@ -135,6 +183,10 @@ class TrafficLights(LEDBoard):
@property
def value(self):
"""
A 3-tuple containing values for the red, amber, and green LEDs. This
property can also be set to alter the state of the LEDs.
"""
return TrafficLightTuple(*super(TrafficLights, self).value)
@value.setter
@@ -145,29 +197,41 @@ class TrafficLights(LEDBoard):
@property
def red(self):
"""
The `LED` object representing the red LED.
The :class:`LED` or :class:`PWMLED` object representing the red LED.
"""
return self.leds[0]
@property
def amber(self):
"""
The `LED` object representing the red LED.
The :class:`LED` or :class:`PWMLED` object representing the red LED.
"""
return self.leds[1]
@property
def green(self):
"""
The `LED` object representing the green LED.
The :class:`LED` or :class:`PWMLED` object representing the green LED.
"""
return self.leds[2]
class PiTraffic(TrafficLights):
"""
Low Voltage Labs PI-TRAFFIC: vertical traffic lights board on pins 9, 10
and 11.
Extends :class:`TrafficLights` for the Low Voltage Labs PI-TRAFFIC:
vertical traffic lights board when attached to GPIO pins 9, 10, and 11.
There's no need to specify the pins if the PI-TRAFFIC is connected to the
default pins (9, 10, 11). The following example turns on the amber LED on
the PI-TRAFFIC::
from gpiozero import PiTraffic
traffic = PiTraffic()
traffic.amber.on()
To use the PI-TRAFFIC board when attached to a non-standard set of pins,
simply use the parent class, :class:`TrafficLights`.
"""
def __init__(self):
super(PiTraffic, self).__init__(9, 10, 11)
@@ -179,7 +243,18 @@ TrafficLightsBuzzerTuple = namedtuple('TrafficLightsBuzzerTuple', (
class TrafficLightsBuzzer(SourceMixin, CompositeDevice):
"""
A generic class for HATs with traffic lights, a button and a buzzer.
Extends :class:`CompositeDevice` and is a generic class for HATs with
traffic lights, a button and a buzzer.
:param TrafficLights lights:
An instance of :class:`TrafficLights` representing the traffic lights
of the HAT.
:param Buzzer buzzer:
An instance of :class:`Buzzer` representing the buzzer on the HAT.
:param Button button:
An instance of :class:`Button` representing the button on the HAT.
"""
def __init__(self, lights, buzzer, button):
super(TrafficLightsBuzzer, self).__init__()
@@ -201,7 +276,7 @@ class TrafficLightsBuzzer(SourceMixin, CompositeDevice):
def all(self):
"""
A tuple containing objects for all the items on the board (several
`LED` objects, a `Buzzer`, and a `Button`).
:class:`LED` objects, a :class:`Buzzer`, and a :class:`Button`).
"""
return self._all
@@ -250,19 +325,19 @@ class TrafficLightsBuzzer(SourceMixin, CompositeDevice):
"""
Make all the board's components turn on and off repeatedly.
on_time: `1`
Number of seconds to be on
:param float on_time:
Number of seconds on
off_time: `1`
Number of seconds to be off
:param float off_time:
Number of seconds off
n: `None`
Number of times to blink; None means forever
:param int n:
Number of times to blink; ``None`` means forever
background: `True`
If `True`, start a background thread to continue blinking and
return immediately. If `False`, only return when the blink is
finished (warning: the default value of `n` will result in this
:param bool background:
If ``True``, start a background thread to continue blinking and
return immediately. If ``False``, only return when the blink is
finished (warning: the default value of *n* will result in this
method never returning).
"""
# XXX This isn't going to work for background=False
@@ -272,7 +347,23 @@ class TrafficLightsBuzzer(SourceMixin, CompositeDevice):
class FishDish(TrafficLightsBuzzer):
"""
Pi Supply FishDish: traffic light LEDs, a button and a buzzer.
Extends :class:`TrafficLightsBuzzer` for the Pi Supply FishDish: traffic
light LEDs, a button and a buzzer.
The FishDish pins are fixed and therefore there's no need to specify them
when constructing this class. The following example waits for the button
to be pressed on the FishDish, then turns on all the LEDs::
from gpiozero import FishDish
fish = FishDish()
fish.button.wait_for_press()
fish.lights.on()
:param bool pwm:
If ``True``, construct :class:`PWMLED` instances to represent each
LED. If ``False`` (the default), construct regular :class:`LED`
instances.
"""
def __init__(self, pwm=False):
super(FishDish, self).__init__(
@@ -284,7 +375,23 @@ class FishDish(TrafficLightsBuzzer):
class TrafficHat(TrafficLightsBuzzer):
"""
Ryanteck Traffic HAT: traffic light LEDs, a button and a buzzer.
Extends :class:`TrafficLightsBuzzer` for the Ryanteck Traffic HAT: traffic
light LEDs, a button and a buzzer.
The Traffic HAT pins are fixed and therefore there's no need to specify
them when constructing this class. The following example waits for the
button to be pressed on the Traffic HAT, then turns on all the LEDs::
from gpiozero import TrafficHat
hat = TrafficHat()
hat.button.wait_for_press()
hat.lights.on()
:param bool pwm:
If ``True``, construct :class:`PWMLED` instances to represent each
LED. If ``False`` (the default), construct regular :class:`LED`
instances.
"""
def __init__(self, pwm=False):
super(TrafficHat, self).__init__(
@@ -299,7 +406,26 @@ RobotTuple = namedtuple('RobotTuple', ('left', 'right'))
class Robot(SourceMixin, CompositeDevice):
"""
Generic dual-motor Robot.
Extends :class:`CompositeDevice` to represent a generic dual-motor robot.
This class is constructed with two tuples representing the forward and
backward pins of the left and right controllers respectively. For example,
if the left motor's controller is connected to GPIOs 4 and 14, while the
right motor's controller is connected to GPIOs 17 and 18 then the following
example will turn the robot left::
from gpiozero import Robot
robot = Robot(left=(4, 14), right=(17, 18))
robot.left()
:param tuple left:
A tuple of two GPIO pins representing the forward and backward inputs
of the left motor's controller.
:param tuple right:
A tuple of two GPIO pins representing the forward and backward inputs
of the right motor's controller.
"""
def __init__(self, left=None, right=None):
if not all([left, right]):
@@ -349,8 +475,9 @@ class Robot(SourceMixin, CompositeDevice):
"""
Drive the robot forward by running both motors forward.
speed: `1`
Speed at which to drive the motors, 0 to 1.
:param float speed:
Speed at which to drive the motors, as a value between 0 (stopped)
and 1 (full speed). The default is 1.
"""
self._left.forward(speed)
self._right.forward(speed)
@@ -359,8 +486,9 @@ class Robot(SourceMixin, CompositeDevice):
"""
Drive the robot backward by running both motors backward.
speed: `1`
Speed at which to drive the motors, 0 to 1.
:param float speed:
Speed at which to drive the motors, as a value between 0 (stopped)
and 1 (full speed). The default is 1.
"""
self._left.backward(speed)
self._right.backward(speed)
@@ -370,8 +498,9 @@ class Robot(SourceMixin, CompositeDevice):
Make the robot turn left by running the right motor forward and left
motor backward.
speed: `1`
Speed at which to drive the motors, 0 to 1.
:param float speed:
Speed at which to drive the motors, as a value between 0 (stopped)
and 1 (full speed). The default is 1.
"""
self._right.forward(speed)
self._left.backward(speed)
@@ -381,8 +510,9 @@ class Robot(SourceMixin, CompositeDevice):
Make the robot turn right by running the left motor forward and right
motor backward.
speed: `1`
Speed at which to drive the motors, 0 to 1.
:param float speed:
Speed at which to drive the motors, as a value between 0 (stopped)
and 1 (full speed). The default is 1.
"""
self._left.forward(speed)
self._right.backward(speed)
@@ -407,7 +537,16 @@ class Robot(SourceMixin, CompositeDevice):
class RyanteckRobot(Robot):
"""
RTK MCB Robot. Generic robot controller with pre-configured pin numbers.
Extends :class:`Robot` for the Ryanteck MCB robot.
The Ryanteck MCB pins are fixed and therefore there's no need to specify
them when constructing this class. The following example turns the robot
left::
from gpiozero import RyanteckRobot
robot = RyanteckRobot()
robot.left()
"""
def __init__(self):
super(RyanteckRobot, self).__init__(left=(17, 18), right=(22, 23))

24
gpiozero/devices.py
View File

@@ -100,9 +100,9 @@ class GPIOBase(GPIOMeta(nstr('GPIOBase'), (), {})):
@property
def closed(self):
"""
Returns `True` if the device is closed (see the `close` method). Once a
device is closed you can no longer use any other methods or properties
to control or query the device.
Returns ``True`` if the device is closed (see the :meth:`close`
method). Once a device is closed you can no longer use any other
methods or properties to control or query the device.
"""
return False
@@ -182,12 +182,12 @@ class GPIODevice(ValuesMixin, GPIOBase):
This is the class at the root of the gpiozero class hierarchy. It handles
ensuring that two GPIO devices do not share the same pin, and provides
basic services applicable to all devices (specifically the `pin` property,
`is_active` property, and the `close` method).
basic services applicable to all devices (specifically the :attr:`pin`
property, :attr:`is_active` property, and the :attr:`close` method).
pin: `None`
:param int pin:
The GPIO pin (in BCM numbering) that the device is connected to. If
this is `None` a `GPIODeviceError` will be raised.
this is ``None`` a :exc:`GPIODeviceError` will be raised.
"""
def __init__(self, pin=None):
super(GPIODevice, self).__init__()
@@ -248,8 +248,8 @@ class GPIODevice(ValuesMixin, GPIOBase):
>>> led = LED(16)
>>> led.blink()
GPIODevice descendents can also be used as context managers using the
`with` statement. For example:
:class:`GPIODevice` descendents can also be used as context managers
using the :keyword:`with` statement. For example:
>>> from gpiozero import *
>>> with Buzzer(16) as bz:
@@ -276,14 +276,16 @@ class GPIODevice(ValuesMixin, GPIOBase):
def pin(self):
"""
The pin (in BCM numbering) that the device is connected to. This will
be `None` if the device has been closed (see the `close` method).
be ``None`` if the device has been closed (see the :meth:`close`
method).
"""
return self._pin
@property
def value(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._read()

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:

207
gpiozero/output_devices.py
View File

@@ -20,14 +20,18 @@ class OutputDevice(SourceMixin, GPIODevice):
"""
Represents a generic GPIO output device.
This class extends `GPIODevice` to add facilities common to GPIO output
devices: an `on` method to switch the device on, and a corresponding `off`
method.
This class extends :class:`GPIODevice` to add facilities common to GPIO
output devices: an :meth:`on` method to switch the device on, and a
corresponding :meth:`off` method.
active_high: `True`
If `True` (the default), the `on` method will set the GPIO to HIGH. If
`False`, the `on` method will set the GPIO to LOW (the `off` method
always does the opposite).
:param int pin:
The GPIO pin (in BCM numbering) that the device is connected to. If
this is ``None`` a :exc:`GPIODeviceError` will be raised.
:param bool active_high:
If ``True`` (the default), the :meth:`on` method will set the GPIO to
HIGH. If ``False``, the :meth:`on` method will set the GPIO to LOW (the
:meth:`off` method always does the opposite).
"""
def __init__(self, pin=None, active_high=True):
self._active_high = active_high
@@ -94,10 +98,10 @@ class DigitalOutputDevice(OutputDevice):
"""
Represents a generic output device with typical on/off behaviour.
This class extends `OutputDevice` with a `toggle` method to switch the
device between its on and off states, and a `blink` method which uses an
optional background thread to handle toggling the device state without
further interaction.
This class extends :class:`OutputDevice` with a :meth:`toggle` method to
switch the device between its on and off states, and a :meth:`blink` method
which uses an optional background thread to handle toggling the device
state without further interaction.
"""
def __init__(self, pin=None, active_high=True):
self._blink_thread = None
@@ -109,16 +113,10 @@ class DigitalOutputDevice(OutputDevice):
super(DigitalOutputDevice, self).close()
def on(self):
"""
Turns the device on.
"""
self._stop_blink()
self._write(self._active_state)
def off(self):
"""
Turns the device off.
"""
self._stop_blink()
self._write(self._inactive_state)
@@ -137,19 +135,19 @@ class DigitalOutputDevice(OutputDevice):
"""
Make the device turn on and off repeatedly.
on_time: `1`
:param float on_time:
Number of seconds on
off_time: `1`
:param float off_time:
Number of seconds off
n: `None`
Number of times to blink; `None` means forever
:param int n:
Number of times to blink; ``None`` means forever
background: `True`
If `True`, start a background thread to continue blinking and
return immediately. If `False`, only return when the blink is
finished (warning: the default value of n will result in this
:param bool background:
If ``True``, start a background thread to continue blinking and
return immediately. If ``False``, only return when the blink is
finished (warning: the default value of *n* will result in this
method never returning).
"""
self._stop_blink()
@@ -179,11 +177,28 @@ class DigitalOutputDevice(OutputDevice):
class LED(DigitalOutputDevice):
"""
An LED (Light Emmitting Diode) component.
Extends :class:`DigitalOutputDevice` and represents a light emitting diode
(LED).
A typical configuration of such a device is to connect a GPIO pin to the
anode (long leg) of the LED, and the cathode (short leg) to ground, with
an optional resistor to prevent the LED from burning out.
Connect the cathode (short leg, flat side) of the LED to a ground pin;
connect the anode (longer leg) to a limiting resistor; connect the other
side of the limiting resistor to a GPIO pin (the limiting resistor can be
placed either side of the LED).
The following example will light the LED::
from gpiozero import LED
led = LED(17)
led.on()
:param int pin:
The GPIO pin which the button is attached to. See :doc:`notes` for
valid pin numbers.
:param bool active_high:
If ``True`` (the default), then the LED will be lit when the GPIO port
is high.
"""
pass
@@ -192,10 +207,26 @@ LED.is_lit = LED.is_active
class Buzzer(DigitalOutputDevice):
"""
A digital Buzzer component.
Extends :class:`DigitalOutputDevice` and represents a digital buzzer
component.
A typical configuration of such a device is to connect a GPIO pin to the
anode (long leg) of the buzzer, and the cathode (short leg) to ground.
Connect the cathode (negative pin) of the buzzer to a ground pin; connect
the other side to any GPIO pin.
The following example will sound the buzzer::
from gpiozero import Buzzer
bz = Buzzer(3)
bz.on()
:param int pin:
The GPIO pin which the buzzer is attached to. See :doc:`notes` for
valid pin numbers.
:param bool active_high:
If ``True`` (the default), then the buzzer will sound when the GPIO
port is high.
"""
pass
@@ -204,7 +235,15 @@ Buzzer.beep = Buzzer.blink
class PWMOutputDevice(DigitalOutputDevice):
"""
Generic Output device configured for PWM (Pulse-Width Modulation).
Generic output device configured for pulse-width modulation (PWM).
:param int pin:
The GPIO pin which the device is attached to. See :doc:`notes` for
valid pin numbers.
:param int frequency:
The frequency (in Hz) of pulses emitted to drive the device. Defaults
to 100Hz.
"""
def __init__(self, pin=None, frequency=100):
self._pwm = None
@@ -259,16 +298,17 @@ class PWMOutputDevice(DigitalOutputDevice):
def toggle(self):
"""
Toggle the state of the device. If the device is currently off
(`value` is 0.0), this changes it to "fully" on (`value` is 1.0). If
the device has a duty cycle (`value`) of 0.1, this will toggle it to
0.9, and so on.
(:attr:`value` is 0.0), this changes it to "fully" on (:attr:`value` is
1.0). If the device has a duty cycle (:attr:`value`) of 0.1, this will
toggle it to 0.9, and so on.
"""
self.value = 1.0 - self.value
@property
def is_active(self):
"""
Returns `True` if the device is currently active and `False` otherwise.
Returns ``True`` if the device is currently active (:attr:`value` is
non-zero) and ``False`` otherwise.
"""
return self.value > 0.0
@@ -276,7 +316,7 @@ class PWMOutputDevice(DigitalOutputDevice):
def frequency(self):
"""
The frequency of the pulses used with the PWM device, in Hz. The
default is 100.
default is 100Hz.
"""
return self._frequency
@@ -288,11 +328,20 @@ class PWMOutputDevice(DigitalOutputDevice):
class PWMLED(PWMOutputDevice):
"""
An LED (Light Emmitting Diode) component with variable brightness.
Extends :class:`PWMOutputDevice` and represents a light emitting diode
(LED) with variable brightness.
A typical configuration of such a device is to connect a GPIO pin to the
anode (long leg) of the LED, and the cathode (short leg) to ground, with
an optional resistor to prevent the LED from burning out.
:param int pin:
The GPIO pin which the device is attached to. See :doc:`notes` for
valid pin numbers.
:param int frequency:
The frequency (in Hz) of pulses emitted to drive the device. Defaults
to 100Hz.
"""
pass
@@ -309,22 +358,35 @@ def _led_property(index, doc=None):
class RGBLED(SourceMixin, CompositeDevice):
"""
Single LED with individually controllable red, green and blue components.
Extends :class:`CompositeDevice` and represents a full color LED component
(composed of red, green, and blue LEDs).
red: `None`
Connect the common cathode (longest leg) to a ground pin; connect each of
the other legs (representing the red, green, and blue anodes) to any GPIO
pins. You can either use three limiting resistors (one per anode) or a
single limiting resistor on the cathode.
The following code will make the LED purple::
from gpiozero import RGBLED
led = RGBLED(2, 3, 4)
led.color = (1, 0, 1)
:param int red:
The GPIO pin that controls the red component of the RGB LED.
green: `None`
:param int green:
The GPIO pin that controls the green component of the RGB LED.
blue: `None`
:param int blue:
The GPIO pin that controls the blue component of the RGB LED.
"""
def __init__(self, red=None, green=None, blue=None):
if not all([red, green, blue]):
raise OutputDeviceError('red, green, and blue pins must be provided')
super(RGBLED, self).__init__()
self._leds = tuple(PWMOutputDevice(pin) for pin in (red, green, blue))
self._leds = tuple(PWMLED(pin) for pin in (red, green, blue))
red = _led_property(0)
green = _led_property(1)
@@ -333,11 +395,11 @@ class RGBLED(SourceMixin, CompositeDevice):
@property
def value(self):
"""
Represents the color of the LED as an RGB 3-tuple of `(red, green,
blue)` where each value is between 0 and 1.
Represents the color of the LED as an RGB 3-tuple of ``(red, green,
blue)`` where each value is between 0 and 1.
For example, purple would be `(1, 0, 1)` and yellow would be `(1, 1,
0)`, while orange would be `(1, 0.5, 0)`.
For example, purple would be ``(1, 0, 1)`` and yellow would be ``(1, 1,
0)``, while orange would be ``(1, 0.5, 0)``.
"""
return (self.red, self.green, self.blue)
@@ -348,7 +410,8 @@ class RGBLED(SourceMixin, CompositeDevice):
@property
def is_active(self):
"""
Returns `True` if the LED is currently active and `False` otherwise.
Returns ``True`` if the LED is currently active (not black) and
``False`` otherwise.
"""
return self.value != (0, 0, 0)
@@ -357,14 +420,14 @@ class RGBLED(SourceMixin, CompositeDevice):
def on(self):
"""
Turn the device on. This equivalent to setting the device color to
white `(1, 1, 1)`.
white ``(1, 1, 1)``.
"""
self.value = (1, 1, 1)
def off(self):
"""
Turn the device off. This is equivalent to setting the device color
to black `(0, 0, 0)`.
to black ``(0, 0, 0)``.
"""
self.value = (0, 0, 0)
@@ -375,7 +438,30 @@ class RGBLED(SourceMixin, CompositeDevice):
class Motor(SourceMixin, CompositeDevice):
"""
Generic bi-directional motor.
Extends :class:`CompositeDevice` and represents a generic motor connected
to a bi-directional motor driver circuit (i.e. an `H-bridge`_).
Attach an `H-bridge`_ motor controller to your Pi; connect a power source
(e.g. a battery pack or the 5V pin) to the controller; connect the outputs
of the controller board to the two terminals of the motor; connect the
inputs of the controller board to two GPIO pins.
.. _H-bridge: https://en.wikipedia.org/wiki/H_bridge
The following code will make the motor turn "forwards"::
from gpiozero import Motor
motor = Motor(17, 18)
motor.forward()
:param int forward:
The GPIO pin that the forward input of the motor driver chip is
connected to.
:param int backward:
The GPIO pin that the backward input of the motor driver chip is
connected to.
"""
def __init__(self, forward=None, backward=None):
if not all([forward, backward]):
@@ -432,20 +518,29 @@ class Motor(SourceMixin, CompositeDevice):
@property
def is_active(self):
"""
Returns `True` if the motor is currently active and `False` otherwise.
Returns ``True`` if the motor is currently running and ``False``
otherwise.
"""
return self.value != 0
def forward(self, speed=1):
"""
Drive the motor forwards
Drive the motor forwards.
:param float speed:
The speed at which the motor should turn. Can be any value between
0 (stopped) and the default 1 (maximum speed).
"""
self._backward.off()
self._forward.value = speed
def backward(self, speed=1):
"""
Drive the motor backwards
Drive the motor backwards.
:param float speed:
The speed at which the motor should turn. Can be any value between
0 (stopped) and the default 1 (maximum speed).
"""
self._forward.off()
self._backward.value = speed
@@ -460,7 +555,7 @@ class Motor(SourceMixin, CompositeDevice):
def stop(self):
"""
Stop the motor
Stop the motor.
"""
self._forward.off()
self._backward.off()