Add RGBLED using new PWMOutputDevice

docs/outputs.md

@@ -82,6 +82,50 @@ buzzer = Buzzer(3)
 | `pin`    | The GPIO pin number the buzzer is connected to. | Integer |
 | `is_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
 
+## RGB LED
+
+A full colour LED component (made up of Red, Green and Blue LEDs).
+
+### Wiring
+
+...
+
+### Code
+
+Ensure the `RGBLED` class is imported at the top of the file:
+
+```python
+from gpiozero import RGBLED
+```
+
+Create a `RGBLED` object by passing in the LED pin numbers by name:
+
+```python
+led = RGBLED(red=2, green=3, blue=4)
+```
+
+or just in order (red, green, blue):
+
+```python
+led = RGBLED(2, 3, 4)
+```
+
+### Methods
+
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `on()` | Turn all the LEDs on (makes white light). | None |
+| `off()` | Turn all the LEDs off. | None |
+
+### Properties
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `red`    | The brightness value of the red LED (0 to 100).     | Integer |
+| `green`  | The brightness value of the green LED (0 to 100).   | Integer |
+| `blue`   | The brightness value of the blue LED (0 to 100).    | Integer |
+| `rgb`    | The brightness values of the three LEDs (0 to 100). | Tuple   |
+
 ## Motor
 
 Generic single-direction motor.

docs/recipes.md

@@ -254,6 +254,34 @@ button.when_pressed = things_on
 button.when_released = things_off
 ```
 
+## RGB LED
+
+Making colours with an RGB LED:
+
+```python
+from gpiozero import RGBLED
+from time import sleep
+
+led = RGBLED(red=9, green=10, blue=11)
+
+led.red = 100  # full red
+led.red = 50  # half red
+
+led.rgb = (0, 100, 0)  # full green
+
+led.rgb = (100, 0, 100)  # magenta
+led.rgb = (100, 100, 0)  # yellow
+led.rgb = (0, 100, 100)  # cyan
+led.rgb = (100, 100, 100)  # white
+
+led.rgb = (0, 0, 0)  # off
+
+# slowly increase intensity of blue
+for n in range(100):
+    led.blue += 1
+    sleep(0.1)
+```
+
 ## Motion Sensor
 
 Light an LED when motion is detected:

gpiozero/__init__.py

@@ -19,10 +19,12 @@ from .input_devices import (
 )
 from .output_devices import (
     OutputDevice,
+    PWMOutputDevice,
     LED,
     Buzzer,
     Motor,
     Robot,
+    RGBLED,
 )
 from .boards import (
     LEDBoard,

gpiozero/input_devices.py

@@ -31,7 +31,8 @@ class InputDevice(GPIODevice):
         if pin in (2, 3) and not pull_up:
             raise InputDeviceError(
                 'GPIO pins 2 and 3 are fitted with physical pull up '
-                    'resistors; you cannot initialize them with pull_up=False')
+                'resistors; you cannot initialize them with pull_up=False'
+            )
         super(InputDevice, self).__init__(pin)
         self._pull_up = pull_up
         self._active_edge = GPIO.FALLING if pull_up else GPIO.RISING

gpiozero/output_devices.py

@@ -28,7 +28,8 @@ class OutputDevice(GPIODevice):
             if warning.category != RuntimeWarning or pin not in (2, 3):
                 warnings.showwarning(
                     warning.message, warning.category, warning.filename,
-                        warning.lineno, warning.file, warning.line)
+                    warning.lineno, warning.file, warning.line
+                )
 
     def on(self):
         """
@@ -135,6 +136,113 @@ class Buzzer(DigitalOutputDevice):
     pass
 
 
+class PWMOutputDevice(DigitalOutputDevice):
+    """
+    Generic Output device configured for PWM (Pulse-Width Modulation).
+    """
+    def __init__(self, pin):
+        super(PWMOutputDevice, self).__init__(pin)
+        self._frequency = 100
+        self._pwm = GPIO.PWM(self._pin, self._frequency)
+        self._pwm.start(0)
+        self.value = 0
+
+    def on(self):
+        """
+        Turn the device on
+        """
+        self.value = 100
+
+    def off(self):
+        """
+        Turn the device off
+        """
+        self.value = 0
+
+    def toggle(self):
+        """
+        Reverse the state of the device.
+        If it's on (a value greater than 0), turn it off; if it's off, turn it
+        on.
+        """
+        self.value = 100 if self.value == 0 else 0
+
+    @property
+    def value(self):
+        return self._value
+
+    @value.setter
+    def value(self, n):
+        self._pwm.ChangeDutyCycle(n)
+        self._value = n
+
+
+class RGBLED(object):
+    """
+    Single LED with individually controllable Red, Green and Blue components.
+    """
+    def __init__(self, red=None, green=None, blue=None):
+        if not all([red, green, blue]):
+            raise GPIODeviceError('Red, Green and Blue pins must be provided')
+
+        self._red = PWMOutputDevice(red)
+        self._green = PWMOutputDevice(green)
+        self._blue = PWMOutputDevice(blue)
+        self._leds = (self._red, self._green, self._blue)
+
+    def on(self):
+        """
+        Turn the device on
+        """
+        for led in self._leds:
+            led.on()
+
+    def off(self):
+        """
+        Turn the device off
+        """
+        for led in self._leds:
+            led.off()
+
+    @property
+    def red(self):
+        return self._red.value
+
+    @red.setter
+    def red(self, value):
+        self._red.value = value
+
+    @property
+    def green(self):
+        return self._green.value
+
+    @green.setter
+    def green(self, value):
+        self._green.value = value
+
+    @property
+    def blue(self):
+        return self._blue.value
+
+    @blue.setter
+    def blue(self, value):
+        self._blue.value = value
+
+    @property
+    def rgb(self):
+        r = self._red.value
+        g = self._green.value
+        b = self._blue.value
+        return (r, g, b)
+
+    @rgb.setter
+    def rgb(self, values):
+        r, g, b = values
+        self._red.value = r
+        self._green.value = g
+        self._blue.value = b
+
+
 class Motor(OutputDevice):
     """
     Generic single-direction motor.