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

Update docs for v0.8.0

Browse Source
This commit is contained in:
Ben Nuttall
2015-10-17 12:36:41 +01:00
parent fcc7c47fe3
commit b7cce51497
7 changed files with 256 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.rst
View File

@@ -10,7 +10,7 @@ other contributors.
Latest release
==============
The latest release is **v0.7.0 beta 2** released on 9th October 2015.
The latest release is **v0.8.0 beta 3** released on 16th October 2015.
About
=====
@@ -33,6 +33,10 @@ colour LEDs, robotics kits and more.
Install
=======
First, install the dependencies::
sudo apt-get install python-pip python3-pip python-w1thermsensor python3-w1thermsensor python-spidev python3-spidev
Install with pip::
sudo pip install gpiozero

6
docs/boards.md
View File

@@ -85,7 +85,7 @@ traffic = TrafficLights(2, 3, 4)
| Property | Description | Type |
| -------- | ----------- | ---- |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `red` | Direct access to the red light as a single `LED` object. | LED |
| `amber` | Direct access to the amber light as a single `LED` object. | LED |
| `green` | Direct access to the green light as a single `LED` object. | LED |
| `leds` | A collection of LEDs to access each one individually, or to iterate over them in sequence. | Tuple |
@@ -264,10 +264,10 @@ Create a `RyanteckRobot` object:
robot = RyanteckRobot()
```
The interface is identical to the generic `Robot` interface.
There's no need to configure the pins if you're using the default pins
`(17, 18)` for the left motor and `(22, 23)` for the right motor.
The interface is identical to the generic `Robot` interface.
To use the Ryanteck MCB on another set of pins, just use the generic `Robot`
interface.

82
docs/inputs.md
View File

@@ -48,18 +48,18 @@ button = Button(pin=2, pull_up=False)
| 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_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
| 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
@@ -89,11 +89,19 @@ pir = MotionSensor(4)
### 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
...
| 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 |
## Light Sensor
@@ -120,15 +128,23 @@ light = LightSensor(4)
### 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 |
## Temperature Sensor
Digital Temperature Sensor.
One-wire Digital Temperature Sensor.
### Wiring
@@ -148,14 +164,16 @@ Create a `TemperatureSensor` object:
temp = TemperatureSensor()
```
### Properties
...
### Methods
...
### Properties
| Property | Description | Type |
| -------- | ----------- | ---- |
| `value` | The current temperature reading in degrees Celsius. | Float |
## MCP3008 Analogue-to-Digital Converter
MCP3008 ADC (Analogue-to-Digital converter).
@@ -175,18 +193,38 @@ Ensure the `MCP3008` class is imported at the top of the file:
from gpiozero import MCP3008
```
Access an input value with the `MCP3008`'s context manager:
Create an `MCP3008` object:
```python
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.read())
print(pot.value)
```
It is possible to specify the `bus`, 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:
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:
```python
with MCP3008(bus=1, device=1, channel=4) as pot:
print(pot.read())
pot = MCP3008(device=1, channel=7)
```
## MCP3004 Analogue-to-Digital Converter
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`.

158
docs/notes.md
View File

@@ -78,7 +78,163 @@ devices, the program needs to be running for the events to be detected:
from gpiozero import Button
from signal import pause
def hello():
print("Hello")
button = Button(2)
button.when_pressed = lambda: print("Button was pressed!")
button.when_pressed = hello
pause()
```
## Importing from GPIO Zero
In Python, libraries and functions used in a script must be imported by name at
the top of the file, with the exception of the functions built in to Python by
default.
For example, to use the `Button` interface from the GPIO Zero library, it
should be explicitly imported:
```python
from gpiozero import Button
```
Now `Button` is available directly in the script:
```python
button = Button(2)
```
Alternatively, the whole GPIO Zero library can be imported:
```python
import gpiozero
```
In this case, all references to interfaces within GPIO Zero must be prefixed:
```python
button = gpiozero.Button(2)
```
## Programming terms
The following terms are used in the documentation.
### Class
A class is the blueprint for a data type. A class defines the way an instance
of its own can behave, and has specific functionality relating to the kinds of
things a user would expect to be able to do with it.
An example of a class in GPIO Zero is `Button`. Note class names are given with
each word capitalised.
### Object
An object is an instance of a class. Any variable in Python is an object of a
given type (e.g. Integer, String, Float), and comprises the functionality
defined by its class.
To create an object, you must assign a variable name to an instance of a class:
```python
my_button = Button(2)
```
Now the variable `my_button` is an instance of the class `Button`. Check its
type with Python's `type()` function:
```python
print(type(my_button))
```
which shows:
```
gpiozero.Button
```
Most classes in GPIO Zero require some parameters 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.
### Method
A method is a function defined within a class. With an object of a given type,
you can call a method on that object. For example if `my_led` is a `LED`
object:
```python
my_led.on()
```
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:
```python
my_led.blink(2, 3)
```
Here, the parameters `2` and `3` have been passed in as parameters. 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.
Parameters 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
will use their default values. Methods in GPIO Zero use sensible common default
values, but are configurable.
### Property
A property is an attribute relating to the state of an object. For example:
```python
my_led.is_active
```
This will return `True` or `False` depending on whether or not the LED is
currently on.
Some properties allow you to change their value. For example an `RGBLED` object:
```python
rgb_led.green = 0.5
```
or:
```python
rgb_led.color = (0.2, 0.3, 0.7)
```
### Context manager
A context manager is an alternative interface provided by classes which require
"closing" the object when it's finished with. The following example (using a
context manager):
```python
with MCP3008() as pot:
print(pot.value)
```
is identical to:
```python
pot = MCP3008()
print(pot.value)
pot.close()
```

50
docs/outputs.md
View File

@@ -40,20 +40,20 @@ led = LED(17)
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn the LED on. | None |
| `off()` | Turn the LED off. | None |
| `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` |
| `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_active` | The current state of the pin (`True` if on; `False` if off). | Boolean |
| `is_active` | The current state of the LED (`True` if on; `False` if off). | Boolean |
## Buzzer
@@ -85,20 +85,20 @@ buzzer = Buzzer(3)
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn the buzzer on. | None |
| `off()` | Turn the buzzer off. | None |
| `on()` | Turn the buzzer on. | None |
| `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 |
| `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` |
| `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 buzzer is connected to. | Integer |
| `is_active` | The current state of the pin (`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 |
## RGB LED
@@ -136,18 +136,22 @@ led = RGBLED(2, 3, 4)
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `on()` | Turn all the LEDs on (makes white light). | None |
| `off()` | Turn all the LEDs off. | None |
| `on()` | Turn all the LEDs on (makes white light). | None |
| `off()` | Turn all the LEDs off. | None |
| `toggle()` | Toggle the LED. If it's on (at all), 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 |
| -------- | ----------- | ---- |
| `red` | The brightness value of the red LED (0 to 255). | Integer |
| `green` | The brightness value of the green LED (0 to 255). | Integer |
| `blue` | The brightness value of the blue LED (0 to 255). | Integer |
| `rgb` | The brightness values of the three LEDs (0 to 255). | Tuple |
| `red` | The brightness value of the red LED (0 to 1). | Integer |
| `green` | The brightness value of the green LED (0 to 1). | Integer |
| `blue` | The brightness value of the blue LED (0 to 1). | Integer |
| `color` | The brightness values of the three LEDs (0 to 1). | Tuple |
## Motor
@@ -178,6 +182,6 @@ motor = Motor(forward=17, back=18)
| Method | Description | Arguments |
| ------ | ----------- | --------- |
| `forward()` | Drive the motor forwards. | `speed` - Speed at which to drive the motor, `0` to `1`. Default: `1` |
| `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 |
| `stop()` | Stop the motor. | None |

2
gpiozero/input_devices.py
View File

@@ -576,5 +576,3 @@ class MCP3004(MCP3008):
# channel number must be 0 (effectively restricting it to 4 channels)
if not 0 <= channel < 4:
raise InputDeviceError('channel must be between 0 and 3')

6
gpiozero/output_devices.py
View File

@@ -224,7 +224,8 @@ class PWMOutputDevice(DigitalOutputDevice):
value = property(_get_value, _set_value, doc="""\
The duty cycle of the PWM device. 0.0 is off, 1.0 is fully on. Values
in between may be specified for varying levels of power in the device.
""")
"""
)
@property
def is_active(self):
@@ -240,7 +241,8 @@ class PWMOutputDevice(DigitalOutputDevice):
frequency = property(_get_frequency, _set_frequency, doc="""\
The frequency of the pulses used with the PWM device, in Hz. The
default is 100.
""")
"""
)
def _led_property(index, doc=None):