diff --git a/README.rst b/README.rst index 9540161..7f05958 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/docs/boards.md b/docs/boards.md index 251ba00..9a89eb3 100644 --- a/docs/boards.md +++ b/docs/boards.md @@ -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. diff --git a/docs/inputs.md b/docs/inputs.md index 4938c0d..7db1b03 100644 --- a/docs/inputs.md +++ b/docs/inputs.md @@ -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`. diff --git a/docs/notes.md b/docs/notes.md index 2d5675b..903d8b0 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -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() +``` diff --git a/docs/outputs.md b/docs/outputs.md index c412c5c..02b56b3 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -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 | diff --git a/gpiozero/input_devices.py b/gpiozero/input_devices.py index a2cb254..b81be04 100644 --- a/gpiozero/input_devices.py +++ b/gpiozero/input_devices.py @@ -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') - - diff --git a/gpiozero/output_devices.py b/gpiozero/output_devices.py index 078876c..02673bc 100644 --- a/gpiozero/output_devices.py +++ b/gpiozero/output_devices.py @@ -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):