Update docs: add PWMLED and include value, values and source properties

docs/index.md

@@ -12,17 +12,36 @@ The latest release is **v0.9.0 beta 4** released on 25th October 2015.
 
 ## About
 
-With very little code, you can quickly get going connecting your physical
+Component interfaces are provided to allow a frictionless way to get started
-components together:
+with physical computing:
+
+```python
+from gpiozero import LED
+from time import sleep
+
+led = LED(2)
+
+while True:
+    led.on()
+    sleep(1)
+    led.off()
+    sleep(1)
+```
+
+With very little code, you can quickly get going connecting your components
+together:
 
 ```python
 from gpiozero import LED, Button
+from signal import pause
 
 led = LED(2)
 button = Button(3)
 
 button.when_pressed = led.on
 button.when_released = led.off
+
+pause()
 ```
 
 The library includes interfaces to many simple everyday components, as well as

docs/inputs.md

@@ -44,7 +44,7 @@ Button(pin=None, pull_up=True, bounce_time=None)
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `pin`         | The GPIO pin number the button is connected to. | Integer: `0` to `25` | *Required* |
+| `pin`         | The GPIO pin number the button is connected to.                                                                    | Integer          | *Required* |
 | `pull_up`     | The pull state of the pin. `True` means pull up, `False` means pull down.                                          | Boolean          | `True`     |
 | `bounce_time` | Specifies the length of time (in seconds) that the component will ignore changes in state after an initial change. | Integer or Float | `None`     |
 
@@ -64,6 +64,8 @@ Button(pin=None, pull_up=True, bounce_time=None)
 | `pull_up`       | The pull state of the pin (`True` if pulled up; `False` if pulled down). | Boolean            |
 | `when_pressed`  | A reference to the function to be called when the button is pressed.     | `None` or Function |
 | `when_released` | A reference to the function to be called when the button is released.    | `None` or Function |
+| `value`         | The current value of the button. 0 if off; 1 if on.                      | Float              |
+| `values`        | A generator continuously yielding the button's current value.            | Generator          |
 
 ## Motion Sensor
 
@@ -99,7 +101,7 @@ MotionSensor(pin=None, queue_len=1, sample_rate=10, threshold=0.5, partial=False
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `pin`         | The GPIO pin number the sensor is connected to. | Integer: `0` to `25` | *Required* |
+| `pin`         | The GPIO pin number the sensor is connected to.                 | Integer           | *Required* |
 | `queue_len`   | ???                                                             | Integer           | `1`        |
 | `sample_rate` | ???                                                             | Integer           | `10`       |
 | `threshold`   | Proportion of sensor values required to determine motion state. | Float: `0` to `1` | `0.5` |
@@ -120,6 +122,8 @@ MotionSensor(pin=None, queue_len=1, sample_rate=10, threshold=0.5, partial=False
 | `motion_detected` | The current state of the sensor (`True` if motion is detected; otherwise `False`). | Boolean            |
 | `when_motion`     | A reference to the function to be called when motion is detected.                  | `None` or Function |
 | `when_no_motion`  | A reference to the function to be called when no motion is detected.               | `None` or Function |
+| `value`           | The current value of the sensor. 0 if still; 1 if motion.                          | Float              |
+| `values`          | A generator continuously yielding the sensor's current value.                      | Generator          |
 
 ## Light Sensor
 
@@ -153,7 +157,7 @@ LightSensor(pin=None, queue_len=5, charge_time_limit=10,
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `pin`         | The GPIO pin number the sensor is connected to. | Integer: `0` to `25` | *Required* |
+| `pin`               | The GPIO pin number the sensor is connected to.                | Integer           | *Required* |
 | `queue_len`         | ???                                                            | Integer           | `5`        |
 | `charge_time_limit` | Maximum amount of time allowed to determine darkness.          | Integer           | `10`       |
 | `threshold`         | Proportion of sensor values required to determine light level. | Float: `0` to `1` | `0.1`      |
@@ -174,6 +178,8 @@ LightSensor(pin=None, queue_len=5, charge_time_limit=10,
 | `light_detected` | The current state of the sensor (`True` if light; otherwise `False`). | Boolean            |
 | `when_light`     | A reference to the function to be called when light is detected.      | `None` or Function |
 | `when_dark`      | A reference to the function to be called when darkness is detected.   | `None` or Function |
+| `value`          | The current value of the sensor. 0 if dark; 1 if light.               | Float              |
+| `values`         | A generator continuously yielding the sensor's current value.         | Generator          |
 
 ## MCP3008 Analogue-to-Digital Converter
 

docs/notes.md

@@ -244,11 +244,11 @@ values, but are configurable when necessary.
 A property is an attribute relating to the state of an object. For example:
 
 ```python
-my_led.is_active
+my_led.is_lit
 ```
 
 This will return `True` or `False` depending on whether or not the LED is
-currently on.
+currently lit.
 
 Some properties allow you to change their value. For example an `RGBLED` object:
 

docs/outputs.md

@@ -44,7 +44,7 @@ LED(pin=None, active_high=True)
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `pin` | The GPIO pin number the LED is connected to. | Integer: `0` to `25` | *Required* |
+| `pin`         | The GPIO pin number the LED is connected to.  | Integer | *Required* |
 | `active_high` | Whether high or low voltage turns the LED on. | Boolean | `True`     |
 
 #### Methods
@@ -64,7 +64,68 @@ LED(pin=None, active_high=True)
 | Property | Description | Type |
 | -------- | ----------- | ---- |
 | `pin`    | The GPIO pin number the LED is connected to.                       | Integer             |
-| `is_active` | The current state of the LED (`True` if on; `False` if off). | Boolean |
+| `is_lit` | The current state of the LED (`True` if on; `False` if off).       | Boolean             |
+| `value`  | The current state of the LED (`True` if on; `False` if off).       | Boolean             |
+| `values` | A generator continuously yielding the LED's current value.         | Generator           |
+| `source` | A generator which can be used to continuously set the LED's value. | `None` or Generator |
+
+## PWMLED
+
+An LED (Light emitting diode) component with the ability to set brightness.
+
+*Note this interface does not require a special LED component. Any regular LED
+can be used in this way.*
+
+### Wiring
+
+A PWMLED is wired the same as a regular LED.
+
+### Code
+
+Ensure the `PWMLED` class is imported at the top of the file:
+
+```python
+from gpiozero import PWMLED
+```
+
+Create an `LED` object by passing in the pin number the LED is connected to:
+
+```python
+led = PWMLED(17)
+```
+
+#### Initialisation options
+
+```python
+PWMLED(pin=None, active_high=True)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin`         | The GPIO pin number the LED is connected to.  | Integer | *Required* |
+| `active_high` | Whether high or low voltage turns the LED on. | Boolean | `True`     |
+
+#### Methods
+
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `on()`     | Turn the LED on.  | None |
+| `off()`    | Turn the LED off. | None |
+| `toggle()` | Toggle the LED. If it's on, turn it off; if it's off, turn it on. | None |
+| `blink()`  | Make the LED turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. **Default: `1`** |
+|            |                                          | `off_time` - The amount of time (in seconds) for the LED to be off each iteration. **Default: `1`** |
+|            |                                          | `n` - The number of iterations. `None` means infinite. **Default: `None`** |
+|            |                                          | `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). **Default: `True`** |
+
+#### Properties
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `pin`    | The GPIO pin number the LED is connected to.                       | Integer             |
+| `is_lit` | The current state of the LED (`True` if on; `False` if off).       | Boolean             |
+| `value`  | The current brightness of the LED `0` to `1`.                      | Float               |
+| `values` | A generator continuously yielding the LED's current value.         | Generator           |
+| `source` | A generator which can be used to continuously set the LED's value. | `None` or Generator |
 
 ## Buzzer
 
@@ -100,7 +161,7 @@ Buzzer(pin=None, active_high=True)
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `pin`         | The GPIO pin number the buzzer is connected to.  | Integer: `0` to `25` | *Required* |
+| `pin`         | The GPIO pin number the buzzer is connected to.  | Integer | *Required* |
 | `active_high` | Whether high or low voltage turns the buzzer on. | Boolean | `True`     |
 
 #### Methods
@@ -121,6 +182,9 @@ Buzzer(pin=None, active_high=True)
 | -------- | ----------- | ---- |
 | `pin`       | The GPIO pin number the buzzer is connected to.                       | Integer             |
 | `is_active` | The current state of the buzzer (`True` if on; `False` if off).       | Boolean             |
+| `value`     | The current state of the buzzer (`True` if on; `False` if off).       | Boolean             |
+| `values`    | A generator continuously yielding the buzzer's current value.         | Generator           |
+| `source`    | A generator which can be used to continuously set the buzzer's value. | `None` or Generator |
 
 ## RGB LED
 
@@ -162,9 +226,9 @@ RGBLED(red=None, green=None, blue=None)
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `red`   | The GPIO pin number the red LED is connected to.   | Integer: `0` to `25` | *Required* |
+| `red`   | The GPIO pin number the red LED is connected to.   | Integer | *Required* |
-| `green` | The GPIO pin number the green LED is connected to. | Integer: `0` to `25` | *Required* |
+| `green` | The GPIO pin number the green LED is connected to. | Integer | *Required* |
-| `blue`  | The GPIO pin number the blue LED is connected to.  | Integer: `0` to `25` | *Required* |
+| `blue`  | The GPIO pin number the blue LED is connected to.  | Integer | *Required* |
 
 #### Methods
 
@@ -182,10 +246,13 @@ RGBLED(red=None, green=None, blue=None)
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| `red`   | The brightness value of the red LED (`0` to `1`).                   | Integer or Float |
+| `red`    | The brightness value of the red LED (`0` to `1`).                     | Float               |
-| `green` | The brightness value of the green LED (`0` to `1`).                 | Integer or Float |
+| `green`  | The brightness value of the green LED (`0` to `1`).                   | Float               |
-| `blue`  | The brightness value of the blue LED (`0` to `1`).                  | Integer or Float |
+| `blue`   | The brightness value of the blue LED (`0` to `1`).                    | Float               |
 | `color`  | The brightness values of the three LEDs `(0, 0, 0)` to `(1, 1, 1)`.   | Tuple               |
+| `value`  | The brightness values of the three LEDs `(0, 0, 0)` to `(1, 1, 1)`.   | Tuple               |
+| `values` | A generator continuously yielding the LED's current values.           | Generator           |
+| `source` | A generator which can be used to continuously set the LED's values.   | `None` or Generator |
 
 ## Motor
 
@@ -209,19 +276,19 @@ from gpiozero import Motor
 Create a `Motor` object by passing in the pin numbers the motor is connected to:
 
 ```python
-motor = Motor(forward=17, back=18)
+motor = Motor(forward=17, backward=18)
 ```
 
 #### Initialisation options
 
 ```python
-Motor(forward=None, back=None)
+Motor(forward=None, backward=None)
 ```
 
 | Argument | Description | Values | Default |
 | -------- | ----------- | ------ | ------- |
-| `forward` | The GPIO pin number the forward gear of the motor is connected to. | Integer: `0` to `25` | *Required* |
+| `forward`     | The GPIO pin number the forward gear of the motor is connected to. | Integer | *Required* |
-| `back`    | The GPIO pin number the reverse gear of the motor is connected to. | Integer: `0` to `25` | *Required* |
+| `backward`    | The GPIO pin number the reverse gear of the motor is connected to. | Integer | *Required* |
 
 #### Methods
 
@@ -230,3 +297,13 @@ Motor(forward=None, back=None)
 | `forward()`  | Drive the motor forwards.       | `speed` - Speed at which to drive the motor, `0` to `1`. **Default: `1`** |
 | `backward()` | Drive the motor backwards.      | `speed` - Speed at which to drive the motor, `0` to `1`. **Default: `1`** |
 | `stop()`     | Stop the motor.                 | None |
+| `reverse()`  | Reverse direction of the motor. | None |
+
+#### Properties
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `is_active` | The current state of the motor. `True` if moving, otherwise `False`.                                                      | Boolean             |
+| `value`     | The current speed and direction of the motor. `-1.0` if full speed backward, `0.0` if still, `1.0` if full speed forward. | Float               |
+| `values`    | A generator continuously yielding the motor's current value.                                                              | Generator           |
+| `source`    | A generator which can be used to continuously set the motor's value.                                                      | `None` or Generator |

docs/recipes.md

@@ -494,3 +494,20 @@ while True:
     led.green = green_pot.value
     led.blue = blue_pot.value
 ```
+
+Alternatively, the following example is identical and uses the `source` property
+rather than a `while` loop:
+
+```python
+from gpiozero import RGBLED, MCP3008
+from signal import pause
+
+led = RGBLED(red=2, green=3, blue=4)
+red_pot = MCP3008(channel=0)
+green_pot = MCP3008(channel=1)
+blue_pot = MCP3008(channel=2)
+
+led.red.source = red_pot.values
+led.green.source = green_pot.values
+led.blue.source = blue_pot.values
+```

gpiozero/output_devices.py

@@ -380,7 +380,9 @@ class Motor(SourceMixin, CompositeDevice):
     """
     def __init__(self, forward=None, backward=None):
         if not all([forward, backward]):
-            raise OutputDeviceError('forward and back pins must be provided')
+            raise OutputDeviceError(
+                'forward and backward pins must be provided'
+            )
         super(Motor, self).__init__()
         self._forward = PWMOutputDevice(forward)
         self._backward = PWMOutputDevice(backward)