From 4975e9c8fbf5b950daefc4a2170207897b631046 Mon Sep 17 00:00:00 2001 From: Ben Nuttall Date: Sun, 15 Nov 2015 17:18:10 +0000 Subject: [PATCH] Update docs: add PWMLED and include value, values and source properties --- docs/index.md | 23 ++++++- docs/inputs.md | 40 +++++++----- docs/notes.md | 4 +- docs/outputs.md | 127 +++++++++++++++++++++++++++++-------- docs/recipes.md | 17 +++++ gpiozero/output_devices.py | 4 +- 6 files changed, 168 insertions(+), 47 deletions(-) diff --git a/docs/index.md b/docs/index.md index 321f6b3..0c8554d 100644 --- a/docs/index.md +++ b/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 -components together: +Component interfaces are provided to allow a frictionless way to get started +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 diff --git a/docs/inputs.md b/docs/inputs.md index 7c1cb5d..e8cd124 100644 --- a/docs/inputs.md +++ b/docs/inputs.md @@ -44,9 +44,9 @@ 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* | -| `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` | +| `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` | #### Methods @@ -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,11 +101,11 @@ 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* | -| `queue_len` | ??? | Integer | `1` | -| `sample_rate` | ??? | Integer | `10` | +| `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` | -| `partial` | ??? | Boolean | `False` | +| `partial` | ??? | Boolean | `False` | #### Methods @@ -116,10 +118,12 @@ MotionSensor(pin=None, queue_len=1, sample_rate=10, threshold=0.5, partial=False | Property | Description | Type | | -------- | ----------- | ---- | -| `pin` | The GPIO pin number the sensor is connected to. | Integer | -| `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 | +| `pin` | The GPIO pin number the sensor is connected to. | Integer | +| `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,17 +157,17 @@ 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* | -| `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` | -| `partial` | ??? | Boolean | `False` | +| `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` | +| `partial` | ??? | Boolean | `False` | #### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | -| `wait_for_light()` | Halt the program until light is detected. | `timeout` - The number of seconds to wait before proceeding if light is not detected. **Default: `None`** | +| `wait_for_light()` | Halt the program until light is detected. | `timeout` - The number of seconds to wait before proceeding if light is not detected. **Default: `None`** | | `wait_for_dark()` | Halt the program until darkness is detected. | `timeout` - The number of seconds to wait before proceeding if darkness is not detected. **Default: `None`** | #### Properties @@ -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 diff --git a/docs/notes.md b/docs/notes.md index e2a3969..d9862d4 100644 --- a/docs/notes.md +++ b/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: diff --git a/docs/outputs.md b/docs/outputs.md index b73d153..f7ee708 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -44,8 +44,8 @@ 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* | -| `active_high` | Whether high or low voltage turns the LED on. | Boolean | `True` | +| `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 @@ -63,8 +63,69 @@ 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 | +| `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 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,8 +161,8 @@ 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* | -| `active_high` | Whether high or low voltage turns the buzzer on. | Boolean | `True` | +| `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 @@ -111,16 +172,19 @@ Buzzer(pin=None, active_high=True) | `off()` | Turn the buzzer off. | None | | `toggle()` | Toggle the buzzer. If it's on, turn it off; if it's off, turn it on. | None | | `beep()` | Make the buzzer turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the buzzer to be on each iteration. **Default: `1`** | -| | | `off_time` - The amount of time (in seconds) for the buzzer 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 beeping 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`** | +| | | `off_time` - The amount of time (in seconds) for the buzzer 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 beeping 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 buzzer is connected to. | Integer | -| `is_active` | The current state of the buzzer (`True` if on; `False` if off). | Boolean | +| `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* | -| `green` | The GPIO pin number the green LED is connected to. | Integer: `0` to `25` | *Required* | -| `blue` | The GPIO pin number the blue 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 | *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 | -| `green` | The brightness value of the green LED (`0` to `1`). | Integer or Float | -| `blue` | The brightness value of the blue LED (`0` to `1`). | Integer or Float | -| `color` | The brightness values of the three LEDs `(0, 0, 0)` to `(1, 1, 1)`. | Tuple | +| `red` | The brightness value of the red LED (`0` to `1`). | Float | +| `green` | The brightness value of the green LED (`0` to `1`). | 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,24 +276,34 @@ 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* | -| `back` | The GPIO pin number the reverse 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* | +| `backward` | The GPIO pin number the reverse gear of the motor is connected to. | Integer | *Required* | #### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | -| `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 | +| `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 | diff --git a/docs/recipes.md b/docs/recipes.md index 9a386a7..cd3520c 100644 --- a/docs/recipes.md +++ b/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 +``` diff --git a/gpiozero/output_devices.py b/gpiozero/output_devices.py index 920298a..c826da5 100644 --- a/gpiozero/output_devices.py +++ b/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)