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

Add 'Initialisation options' to docs

Browse Source
This commit is contained in:
Ben Nuttall
2015-10-18 22:57:22 +01:00
parent d61f0ff5ec
commit 0805579175
4 changed files with 244 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/boards.md
View File

@@ -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 |
| ------ | ----------- | --------- |

121
docs/inputs.md
View File

@@ -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.

63
docs/notes.md
View File

@@ -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

65
docs/outputs.md
View File

@@ -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 |
| ------ | ----------- | --------- |