From 0805579175ebc6588f175d202c65e2f3e40e4b84 Mon Sep 17 00:00:00 2001 From: Ben Nuttall Date: Sun, 18 Oct 2015 22:57:22 +0100 Subject: [PATCH] Add 'Initialisation options' to docs --- docs/boards.md | 61 ++++++++++++++++++++---- docs/inputs.md | 121 ++++++++++++++++++++++++++++++++++-------------- docs/notes.md | 63 ++++++++++++++++++++----- docs/outputs.md | 65 ++++++++++++++++++++++---- 4 files changed, 244 insertions(+), 66 deletions(-) diff --git a/docs/boards.md b/docs/boards.md index 9a89eb3..3c5b8d2 100644 --- a/docs/boards.md +++ b/docs/boards.md @@ -27,11 +27,21 @@ Create an `LEDBoard` object by passing in a list of the LED pin numbers: leds = LEDBoard([2, 3, 4, 5, 6]) ``` -### Methods +#### Initialisation options + +```python +LEDBoard(leds=None) +``` + +| Argument | Description | Values | Default | +| -------- | ----------- | ------ | ------- | +| `leds` | List of GPIO pins each LED is connected to, order preserved. | List | *Required* | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | -| `on()` | Turn all the LEDs on. | None | +| `on()` | Turn all the LEDs on. | None | | `off()` | Turn all the LEDs off. | None | | `toggle()` | Toggle all the LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None | | `blink()` | Make the LEDs turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. Default: `1` | @@ -39,7 +49,7 @@ leds = LEDBoard([2, 3, 4, 5, 6]) | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -69,7 +79,19 @@ or just in order (red, amber, green): traffic = TrafficLights(2, 3, 4) ``` -### Methods +#### Initialisation options + +```python +TrafficLights(red=None, amber=None, green=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* | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -81,7 +103,7 @@ traffic = TrafficLights(2, 3, 4) | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -108,7 +130,11 @@ Create a `PiLiter` object: lite = PiLiter() ``` -### Methods +#### Initialisation options + +None + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -120,7 +146,7 @@ lite = PiLiter() | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -168,7 +194,11 @@ Create a `FishDish` object: fish = FishDish() ``` -### Methods +#### Initialisation options + +None + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -187,7 +217,7 @@ fish = FishDish() | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -238,7 +268,18 @@ pairs for each motor: robot = Robot(left=(4, 14), right=(17, 18)) ``` -### Methods +#### Initialisation options + +```python +Robot(left=None, right=None)) +``` + +| Argument | Description | Values | Default | +| -------- | ----------- | ------ | ------- | +| `left` | The GPIO pins (forward and reverse) used by the left motor. | Tuple | *Required* | +| `right` | The GPIO pins (forward and reverse) used by the right motor. | Tuple | *Required* | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | diff --git a/docs/inputs.md b/docs/inputs.md index 0467b77..9f3386c 100644 --- a/docs/inputs.md +++ b/docs/inputs.md @@ -36,30 +36,34 @@ to: button = Button(2) ``` -The default behaviour is to set the *pull* state of the button to *up*. To -change this behaviour, set the `pull_up` argument to `False` when creating your -`Button` object. +#### Initialisation options ```python -button = Button(pin=2, pull_up=False) +Button(pin=None, pull_up=True, bounce_time=None) ``` -### Methods +| 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` | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | | `wait_for_press()` | Halt the program until the button is pressed. | `timeout` - The number of seconds to wait before proceeding if no event is detected. **Default: `None`** | | `wait_for_release()` | Halt the program until the button is released. | `timeout` - The number of seconds to wait before proceeding if no event is detected. **Default: `None`** | -### Properties +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | -| `pin` | The GPIO pin number the button is connected to. | Integer | -| `is_pressed` | The current state of the pin (`True` if pressed; otherwise `False`). | Boolean | -| `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 | +| `pin` | The GPIO pin number the button is connected to. | Integer | +| `is_pressed` | The current state of the pin (`True` if pressed; otherwise `False`). | Boolean | +| `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 | ## Motion Sensor @@ -87,21 +91,35 @@ connected to: pir = MotionSensor(4) ``` -### Methods +#### Initialisation options + +```python +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` | +| `threshold` | Proportion of sensor values required to determine motion state. | Float: `0` to `1` | `0.5` | +| `partial` | ??? | Boolean | `False` | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | | `wait_for_motion()` | Halt the program until motion is detected. | `timeout` - The number of seconds to wait before proceeding if no motion is detected. **Default: `None`** | | `wait_for_no_motion()` | Halt the program until no motion is detected. | `timeout` - The number of seconds to wait before proceeding if motion is still detected. **Default: `None`** | -### Properties +#### Properties | 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 | +| `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 | ## Light Sensor @@ -126,21 +144,36 @@ connected to: light = LightSensor(4) ``` -### Methods +#### Initialisation options + +```python +LightSensor(pin=None, queue_len=5, charge_time_limit=10, + threshold=0.1, partial=False) +``` + +| 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` | + +#### 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_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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | -| `pin` | The GPIO pin number the sensor is connected to. | Integer | -| `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 | +| `pin` | The GPIO pin number the sensor is connected to. | Integer | +| `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 | ## Temperature Sensor @@ -164,11 +197,15 @@ Create a `TemperatureSensor` object: temp = TemperatureSensor() ``` -### Methods +#### Initialisation options ... -### Properties +#### Methods + +... + +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -199,27 +236,40 @@ Create an `MCP3008` object: pot = MCP3008() ``` -Read the value of the device: - -```python -print(pot.value) -``` - Alternatively, access an input value with the `MCP3008`'s context manager: ```python with MCP3008() as pot: - print(pot.value) + # do something with pot ``` -It is possible to specify the `device` and the `channel` you wish to access. -The previous example used the default value of `0` for each of these. To -specify them, pass them in as arguments: +#### Initialisation options ```python -pot = MCP3008(device=1, channel=7) +MCP3008(device=0, channel=0) ``` +| Argument | Description | Values | Default | +| -------- | ----------- | ------ | ------- | +| `device` | Which of the two Chip Select SPI pins to access. | Integer: `0` or `1` | `0` | +| `channel` | Which of the 8 ADC channels to access. | Integer: `0` to `7` | `0` | + +#### 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_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 + +| Property | Description | Type | +| -------- | ----------- | ---- | +| `pin` | The GPIO pin number the sensor is connected to. | Integer | +| `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 | + ## MCP3004 Analogue-to-Digital Converter MCP3004 ADC (Analogue-to-Digital converter). @@ -227,4 +277,5 @@ MCP3004 ADC (Analogue-to-Digital converter). The MCP3004 chip provides access to up to 4 analogue inputs, such as potentiometers, and read their values in digital form. -The interface is identical to `MCP3008`. +The interface is identical to `MCP3008`, except that only channels `0` to `3` +are accessible. diff --git a/docs/notes.md b/docs/notes.md index 903d8b0..a2e1bce 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -155,11 +155,47 @@ which shows: gpiozero.Button ``` -Most classes in GPIO Zero require some parameters to create an object, for +### Initialisation options + +Most classes in GPIO Zero require some arguments to create an object, for example the `LED` and `Button` examples require the pin number the device is -attached to. Some classes require no parameters, others require multiple -parameters, usually with some being optional. When parameters are optional, -common default values are used. +attached to: + +```python +my_button = Button(2) +``` + +Some classes require no arguments due to the nature of the device: + +```python +temp = TemperatureSensor() +``` + +Others have multiple arguments, usually with some being optional: + +```python +temp = TemperatureSensor() +``` + +When arguments are optional, common default values are used. + +Arguments can be given unnamed, as long as they are in order: + +```python +my_button = Button(2, False) +``` + +though this may be confusing, so named is better in this case: + +```python +my_button = Button(pin=2, pull_up=False) +``` + +Alternatively, they can be given in any order, as long as they are named: + +```python +my_button = Button(pin=2, bounce_time=0.5, pull_up=False) +``` ### Method @@ -175,27 +211,32 @@ will call the `LED` class's `on()` function, relating to that instance of `LED`. If other `LED` objects have been created, they will not be affected by this action. -In many cases, no parameters are required to call the method (like -`my_led.on()`). In other cases, optional parameters are available. For example: +In many cases, no arguments are required to call the method (like +`my_led.on()`). In other cases, optional arguments are available. For example: ```python my_led.blink(2, 3) ``` -Here, the parameters `2` and `3` have been passed in as parameters. The `blink` +Here, the arguments `2` and `3` have been passed in as arguments. The `blink` method allows configuration of `on_time` and `off_time`. This example means the -LED will flash on for 2 seconds and stay off for 3. +LED will flash on for 2 seconds and stay off for 3. This example may benefit +from use of named arguments: -Parameters can also be passed in by name, which means order is irrelevant. For +```python +my_led.blink(on_time=2, off_time=3) +``` + +arguments can also be passed in by name, which means order is irrelevant. For example: ```python my_led.blink(off_time=3) ``` -Here, only the `off_time` parameter has been provided, and all other parameters +Here, only the `off_time` argument has been provided, and all other arguments will use their default values. Methods in GPIO Zero use sensible common default -values, but are configurable. +values, but are configurable when necessary. ### Property diff --git a/docs/outputs.md b/docs/outputs.md index d226fd9..0d5fcdf 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -36,7 +36,18 @@ Create an `LED` object by passing in the pin number the LED is connected to: led = LED(17) ``` -### Methods +#### Initialisation options + +```python +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` | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -48,7 +59,7 @@ led = LED(17) | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -81,7 +92,18 @@ to: buzzer = Buzzer(3) ``` -### Methods +#### Initialisation options + +```python +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` | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -93,7 +115,7 @@ buzzer = Buzzer(3) | | | `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 +#### Properties | Property | Description | Type | | -------- | ----------- | ---- | @@ -132,7 +154,19 @@ or just in order (red, green, blue): led = RGBLED(2, 3, 4) ``` -### Methods +#### Initialisation options + +```python +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* | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- | @@ -144,13 +178,13 @@ led = RGBLED(2, 3, 4) | | | `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 +#### Properties | 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 | +| `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 | ## Motor @@ -178,7 +212,18 @@ Create a `Motor` object by passing in the pin numbers the motor is connected to: motor = Motor(forward=17, back=18) ``` -### Methods +#### Initialisation options + +```python +Motor(forward=None, back=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* | + +#### Methods | Method | Description | Arguments | | ------ | ----------- | --------- |