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

Merge pull request #274 from waveform80/doc-reorg

Browse Source 
Doc reorganization
This commit is contained in:
Dave Jones
2016-04-10 16:58:27 +01:00
parent 8f8dddd403 ecc8df8041
commit e2b8171bbb
38 changed files with 1250 additions and 371 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
gpiozero/devices.py
View File

@@ -264,7 +264,7 @@ class CompositeDevice(Device):
def __init__(self, *args, **kwargs):
self._all = ()
self._named = {}
self._tuple = None
self._namedtuple = None
self._order = kwargs.pop('_order', None)
if self._order is None:
self._order = sorted(kwargs.keys())
@@ -279,7 +279,7 @@ class CompositeDevice(Device):
if not isinstance(dev, Device):
raise CompositeDeviceBadDevice("%s doesn't inherit from Device" % dev)
self._named = kwargs
self._tuple = namedtuple('%sValue' % self.__class__.__name__, chain(
self._namedtuple = namedtuple('%sValue' % self.__class__.__name__, chain(
(str(i) for i in range(len(args))), self._order),
rename=True)
@@ -333,12 +333,12 @@ class CompositeDevice(Device):
return all(device.closed for device in self)
@property
def tuple(self):
return self._tuple
def namedtuple(self):
return self._namedtuple
@property
def value(self):
return self.tuple(*(device.value for device in self))
return self.namedtuple(*(device.value for device in self))
@property
def is_active(self):

17
gpiozero/input_devices.py
View File

@@ -66,10 +66,10 @@ class DigitalInputDevice(EventsMixin, InputDevice):
"""
Represents a generic input device with typical on/off behaviour.
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.
This class extends :class:`InputDevice` 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.
:param float bouncetime:
Specifies the length of time (in seconds) that the component will
@@ -94,11 +94,10 @@ class SmoothedInputDevice(EventsMixin, InputDevice):
Represents a generic input device which takes its value from the mean of a
queue of historical values.
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 extends :class:`InputDevice` 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.
.. note::

15
gpiozero/mixins.py
View File

@@ -29,7 +29,9 @@ from .exc import (
class ValuesMixin(object):
"""
Adds a :attr:`values` property to the class which returns an infinite
generator of readings from the :attr:`value` property.
generator of readings from the :attr:`value` property. There is rarely a
need to use this mixin directly as all base classes in GPIO Zero include
it.
.. note::
@@ -50,8 +52,10 @@ class ValuesMixin(object):
class SourceMixin(object):
"""
Adds a :attr:`source` property to the class which, given an iterable,
sets :attr:`value` to each member of that iterable until it is exhausted.
Adds a :attr:`source` property to the class which, given an iterable, sets
:attr:`value` to each member of that iterable until it is exhausted. This
mixin is generally included in novel output devices to allow their state to
be driven from another device.
.. note::
@@ -312,6 +316,11 @@ class EventsMixin(object):
class HoldMixin(EventsMixin):
"""
Extends :class:`EventsMixin` to add the :attr:`when_held` event and the
machinery to fire that event repeatedly (when :attr:`hold_repeat` is
``True``) at internals defined by :attr:`hold_time`.
"""
def __init__(self, *args, **kwargs):
super(HoldMixin, self).__init__(*args, **kwargs)
self._when_held = None

2
gpiozero/other_devices.py
View File

@@ -21,7 +21,7 @@ from .mixins import EventsMixin
class InternalDevice(EventsMixin, Device):
"""
Extends :class:`Device` to provide a basis for devices which have no
specific hardware representation. This are effectively pseudo-devices and
specific hardware representation. These are effectively pseudo-devices and
usually represent operating system services like the internal clock, file
systems or network facilities.
"""

2
gpiozero/spi_devices.py
View File

@@ -228,7 +228,7 @@ class MCP3001(MCP3xxx):
class MCP3002(MCP3xxx):
"""
The `MCP3002`_ is a 10-bit analog to digital converter with 2 channels
(0-3).
(0-1).
.. _MCP3002: http://www.farnell.com/datasheets/1599363.pdf
"""

114
gpiozero/tools.py
View File

@@ -28,7 +28,8 @@ def negated(values):
Returns the negation of the supplied values (``True`` becomes ``False``,
and ``False`` becomes ``True``). For example::
from gpiozero import Button, LED, negated
from gpiozero import Button, LED
from gpiozero.tools import negated
from signal import pause
led = LED(4)
@@ -45,7 +46,8 @@ def inverted(values):
Returns the inversion of the supplied values (1 becomes 0, 0 becomes 1,
0.1 becomes 0.9, etc.). For example::
from gpiozero import MCP3008, PWMLED, inverted
from gpiozero import MCP3008, PWMLED
from gpiozero.tools import inverted
from signal import pause
led = PWMLED(4)
@@ -57,36 +59,44 @@ def inverted(values):
yield 1 - v
def scaled(values, range_min, range_max, domain_min=0, domain_max=1):
def scaled(values, output_min, output_max, input_min=0, input_max=1):
"""
Returns *values* scaled from *range_min* to *range_max*, assuming that all
items in *values* lie between *domain_min* and *domain_max* (which default
to 0 and 1 respectively). For example, to control the direction of a motor
(which is represented as a value between -1 and 1) using a potentiometer
(which typically provides values between 0 and 1)::
Returns *values* scaled from *output_min* to *output_max*, assuming that
all items in *values* lie between *input_min* and *input_max* (which
default to 0 and 1 respectively). For example, to control the direction of
a motor (which is represented as a value between -1 and 1) using a
potentiometer (which typically provides values between 0 and 1)::
from gpiozero import Motor, MCP3008, scaled
from gpiozero import Motor, MCP3008
from gpiozero.tools import scaled
from signal import pause
motor = Motor(20, 21)
pot = MCP3008(channel=0)
motor.source = scaled(pot.values, -1, 1)
pause()
.. warning::
If *values* contains elements that lie outside *input_min* to
*input_max* (inclusive) then the function will not produce values that
lie within *output_min* to *output_max* (inclusive).
"""
domain_size = domain_max - domain_min
range_size = range_max - range_min
input_size = input_max - input_min
output_size = output_max - output_min
for v in values:
yield (((v - domain_min) / domain_size) * range_size) + range_min
yield (((v - input_min) / input_size) * output_size) + output_min
def clamped(values, range_min=0, range_max=1):
def clamped(values, output_min=0, output_max=1):
"""
Returns *values* clamped from *range_min* to *range_max*, i.e. any items
less than *range_min* will be returned as *range_min* and any items
larger than *range_max* will be returned as *range_max* (these default to
Returns *values* clamped from *output_min* to *output_max*, i.e. any items
less than *output_min* will be returned as *output_min* and any items
larger than *output_max* will be returned as *output_max* (these default to
0 and 1 respectively). For example::
from gpiozero import PWMLED, MCP3008, clamped
from gpiozero import PWMLED, MCP3008
from gpiozero.tools import clamped
from signal import pause
led = PWMLED(4)
@@ -95,19 +105,40 @@ def clamped(values, range_min=0, range_max=1):
pause()
"""
for v in values:
yield min(max(v, range_min), range_max)
yield min(max(v, output_min), output_max)
def quantized(values, steps, range_min=0, range_max=1):
def absoluted(values):
"""
Returns *values* with all negative elements negated (so that they're
positive). For example::
from gpiozero import PWMLED, Motor, MCP3008
from gpiozero.tools import absoluted, scaled
from signal import pause
led = PWMLED(4)
motor = Motor(22, 27)
pot = MCP3008(channel=0)
motor.source = scaled(pot.values, -1, 1)
led.source = absoluted(motor.values)
pause()
"""
for v in values:
yield abs(v)
def quantized(values, steps, output_min=0, output_max=1):
"""
Returns *values* quantized to *steps* increments. All items in *values* are
assumed to be between *range_min* and *range_max* (use :func:`scaled` to
assumed to be between *output_min* and *output_max* (use :func:`scaled` to
ensure this if necessary).
For example, to quantize values between 0 and 1 to 5 "steps" (0.0, 0.25,
0.5, 0.75, 1.0)::
from gpiozero import PWMLED, MCP3008, quantized
from gpiozero import PWMLED, MCP3008
from gpiozero.tools import quantized
from signal import pause
led = PWMLED(4)
@@ -115,25 +146,26 @@ def quantized(values, steps, range_min=0, range_max=1):
led.source = quantized(pot.values, 4)
pause()
"""
range_size = range_max - range_min
for v in scaled(values, 0, 1, range_min, range_max):
yield ((int(v * steps) / steps) * range_size) + range_min
output_size = output_max - output_min
for v in scaled(values, 0, 1, output_min, output_max):
yield ((int(v * steps) / steps) * output_size) + output_min
def conjunction(*values):
def all_values(*values):
"""
Returns the `logical conjunction`_ of all supplied values (the result is
only ``True`` if and only if all input values are simultaneously ``True``).
One or more *values* can be specified. For example, to light an
:class:`LED` only when *both* buttons are pressed::
from gpiozero import LED, Button, conjunction
from gpiozero import LED, Button
from gpiozero.tools import all_values
from signal import pause
led = LED(4)
btn1 = Button(20)
btn2 = Button(21)
led.source = conjunction(btn1.values, btn2.values)
led.source = all_values(btn1.values, btn2.values)
pause()
.. _logical conjunction: https://en.wikipedia.org/wiki/Logical_conjunction
@@ -142,20 +174,21 @@ def conjunction(*values):
yield all(v)
def disjunction(*values):
def any_values(*values):
"""
Returns the `logical disjunction`_ of all supplied values (the result is
``True`` if any of the input values are currently ``True``). One or more
*values* can be specified. For example, to light an :class:`LED` when
*any* button is pressed::
from gpiozero import LED, Button, conjunction
from gpiozero import LED, Button
from gpiozero.tools import any_values
from signal import pause
led = LED(4)
btn1 = Button(20)
btn2 = Button(21)
led.source = disjunction(btn1.values, btn2.values)
led.source = any_values(btn1.values, btn2.values)
pause()
.. _logical disjunction: https://en.wikipedia.org/wiki/Logical_disjunction
@@ -170,7 +203,8 @@ def averaged(*values):
specified. For example, to light a :class:`PWMLED` as the average of
several potentiometers connected to an :class:`MCP3008` ADC::
from gpiozero import MCP3008, PWMLED, averaged
from gpiozero import MCP3008, PWMLED
from gpiozero.tools import averaged
from signal import pause
pot1 = MCP3008(channel=0)
@@ -190,7 +224,8 @@ def queued(values, qsize):
determined by *qsize*) and begins yielding values only when the queue is
full. For example, to "cascade" values along a sequence of LEDs::
from gpiozero import LEDBoard, Button, queued
from gpiozero import LEDBoard, Button
from gpiozero.tools import queued
from signal import pause
leds = LEDBoard(5, 6, 13, 19, 26)
@@ -236,7 +271,8 @@ def random_values():
Provides an infinite source of random values between 0 and 1. For example,
to produce a "flickering candle" effect with an LED::
from gpiozero import PWMLED, random_values
from gpiozero import PWMLED
from gpiozero.tools import random_values
from signal import pause
led = PWMLED(4)
@@ -256,13 +292,14 @@ def sin_values():
that increments by one for each requested value. For example, to produce a
"siren" effect with a couple of LEDs::
from gpiozero import PWMLED, sin_values, scaled, inverted
from gpiozero import PWMLED
from gpiozero.tools import sin_values, scaled, inverted
from signal import pause
red = PWMLED(2)
blue = PWMLED(3)
red.source_delay = 0.1
blue.source_delay = 0.1
red.source_delay = 0.01
blue.source_delay = 0.01
red.source = scaled(sin_values(), 0, 1, -1, 1)
blue.source = inverted(red.values)
pause()
@@ -280,11 +317,14 @@ def cos_values():
counter that increments by one for each requested value. For example, to
produce a "siren" effect with a couple of LEDs::
from gpiozero import PWMLED, cos_values, scaled, inverted
from gpiozero import PWMLED
from gpiozero.tools import cos_values, scaled, inverted
from signal import pause
red = PWMLED(2)
blue = PWMLED(3)
red.source_delay = 0.01
blue.source_delay = 0.01
red.source = scaled(cos_values(), 0, 1, -1, 1)
blue.source = inverted(red.values)
pause()