Merge branch 'master' into motors

Author: bennuttall

analogue.md

@@ -0,0 +1,189 @@
+# Analogue Inputs
+
+The Raspberry Pi's GPIO pins are digital pins, so you can only set outputs to high or low, or read inputs as high or low. However, using an ADC chip (Analogue-to-Digital converter), you can read the value of analogue input devices such as potentiometers.
+
+## SPI
+
+The analogue values are communicated to the Pi using the SPI protocol. While this will work in GPIO Zero out of the box, you may get better results if you enable full SPI support.
+
+1. Open a terminal window and install the `spidev` package:
+
+    ```bash
+    sudo apt-get install python3-spidev python-spidev
+    ```
+
+1. Open the **Raspberry Pi Configuration** dialogue from the main menu and enable **SPI** in the **Interfaces** tab:
+
+    ![Enable SPI](images/rcgui.png)
+
+1. Click **OK** and reboot the Pi.
+
+## Wiring the ADC (MCP3008)
+
+The MCP3008 is an ADC providing eight input channels. The eight connectors on one side are connected to the Pi's GPIO pins, and the other eight are available to connect analogue input devices to read their values.
+
+Place the MCP3008 chip on a breadboard and carefully wire it up as shown in the following diagram:
+
+![MCP3008 wiring](images/mcp3008.png)
+
+Alternatively, you could use the [Analog Zero](http://rasp.io/analogzero/) board, which provides the MCP3008 chip on a handy add-on board to save you from the complicated wiring.
+
+## Add a potentiometer
+
+Now that the ADC is connected to the Pi, you can wire devices up to the input channels. A potentiometer is a good example of an analogue input device: it's simply a variable resistor, and the Pi reads the voltage (from 0V to 3.3V).
+
+![Potentiometer](images/potentiometer.jpg)
+
+A potentiometer's pins are ground, data, and 3V3. This means you connect it to ground and a supply of 3V3, and read the actual voltage from the middle pin.
+
+1. Place a potentiometer on the breadboard and wire one side to the ground rail, the other to the 3V3 rail, and the middle pin to the first input channel as shown:
+
+    ![Add a potentiometer](images/mcp3008-pot.png)
+
+## Code
+
+Now your potentiometer is connected and its value can be read from Python!
+
+1. Open **Python 3** from the main menu.
+
+1. In the shell, start by importing the `MCP3008` class from the GPIO Zero library:
+
+    ```python
+    from gpiozero import MCP3008
+    ```
+
+1. Create an object representing your analogue device:
+
+    ```python
+    pot = MCP3008(0)
+    ```
+
+    Note the `0` represents the ADC's channel 0. There are 8 channels (0 to 7), and you're using the first one.
+
+1. Try to read its value:
+
+    ```python
+    print(pot.value)
+    ```
+
+    You should see a number between 0 and 1. This represents how far the dial is turned.
+
+1. Now read the value in a loop:
+
+    ```python
+    while True:
+        print(pot.value)
+    ```
+
+    Try twisting the dial around to see the value change.
+
+## PWMLED
+
+Now you've tested you can read values from the potentiometer, you should connect it to another GPIO device.
+
+1. Add an LED to your breadboard and wire it to the Pi, connecting it to GPIO pin 21:
+
+    ![Add LED](images/mcp3008-pot-led.png)
+
+1. In your Python code, start by importing the `PWMLED` class:
+
+    ```python
+    from gpiozero import PWMLED
+    ```
+
+    The `PWMLED` class lets you control the brightness of an LED using PWM, or pulse-width modulation. 
+
+1. Create a `PWMLED` object on pin 21:
+
+    ```python
+    led = PWMLED(21)
+    ```
+
+1. Test you can control the LED manually:
+
+    ```python
+    led.on()  # the led should be lit
+    led.off()  # the led should go off
+    led.value = 0.5  # the led should be lit at half brightness
+    ```
+
+1. Now connect the LED to the potentiometer:
+
+    ```python
+    led.source = pot.values
+    ```
+
+1. Turn the dial to change the LED brightness!
+
+### Source and values
+
+GPIO Zero has a powerful feature: **source and values**. Every device has a `value` property (the current value) and a `values` property (a stream of the device's values at all times). Every output device has a `source` property which can be used to set what the device's value should be.
+
+- `pot.value` gives the potentiometer's current value (it's read only, as it's an input device)
+- `led.value` is the LED's current value (it's read/write: you can see what it is, and you can change it)
+- `pot.values` is a generator constantly yielding the potentiometer's current value
+- `led.source` is a way of setting where the LED gets its values from
+
+Rather than continuously setting the value of the LED to the value of the potentiometer in a loop, you can just pair the two devices. Therefore the line `led.source = pot.values` is equivalent to the following loop:
+
+```python
+while True:
+    led.value = pot.value
+```
+
+## Multiple potentiometers
+
+1. Add a second potentiometer to your breadboard and connect it to the ADC's channel 1:
+
+    ![Second potentiometer](images/mcp3008-2pots-led.png)
+
+1. Now create a second `MCP3008` object on channel 1:
+
+    ```python
+    pot2 = MCP3008(1)
+    ```
+
+1. Make the LED blink:
+
+    ```python
+    led.blink()
+    ```
+
+    The LED will blink continuously, one second on and one second off.
+
+1. Change the `on_time` and `off_time` parameters to make it blink faster or slower:
+
+    ```python
+    led.blink(on_time=2, off_time=2)
+    led.blink(on_time=0.5, off_time=0.1)
+    ```
+
+1. Now use a loop to change the blink times according to the potentiometer values:
+
+    ```python
+    while True:
+        print(pot.value, pot2.value)
+        led.blink(on_time=pot.value, off_time=pot2.value, n=1, background=False)
+    ```
+
+    Note you have to make it blink once in the foreground, so that each iteration gets time to finish before it updates the blink times.
+
+1. Rotate the dials to make it blink at different speeds!
+
+1. Also try changing `blink` to `pulse` and change `on_time` and `off_time` to `fade_in_time` and `fade_out_time` so that it fades in and out at different speeds, rather than just blinking on and off:
+
+    ```python
+    while True:
+        print(pot.value, pot2.value)
+        led.pulse(fade_in_time=pot.value, fade_out_time=pot2.value, n=1, background=False)
+    ```
+
+1. Rotate the dials to change the effect.
+
+## What next?
+
+- Use potentiometers to control other GPIO Zero output devices
+- Use potentiometers to control the speed of motors
+- Use potentiometers to control the visual settings of a Camera Module in real time
+- Find more analogue sensors that will work with the ADC
+- Use potentiometers to control a player in a [PyGame Zero](http://pygame-zero.readthedocs.io) game, or in [Minecraft](https://www.raspberrypi.org/learning/getting-started-with-minecraft-pi/)

code/example.py

@@ -1,54 +1,126 @@
 # Ultrasonic distance sensor
 
-In air, sound travels at a speed of 343ms<sup>-1</sup>. An ultrasonic distance sensor sends out pulses of ultrasound, which is inaudible to humans, and detects the echo that is sent back when the sound bounces off a nearby object.
+In air, sound travels at a speed of 343 metres per second. An ultrasonic distance sensor sends out pulses of ultrasound which are inaudible to humans, and detects the echo that is sent back when the sound bounces off a nearby object. It then uses the speed of sound to calculate the distance from the object.
 
-![usd](images/ultrasonic-distance-sensor.png)
+![Ultrasonic distance sensor](images/ultrasonic-distance-sensor.png)
 
-By knowing the speed of sound and the time taken for the ultrasound to be detected, an ultrasonic distance sensor can be used to detect how far away an object is.
+## Wiring
 
-## Wiring an ultrasonic distance sensor
-
-To wire up an ultrasonic distance sensor, you'll need to use a pair of resistors as a potential divider. Use the diagram below as a guide.
+The circuit connects to two GPIO pins (one for echo, one for trigger), the ground pin, and a 5V pin. You'll need to use a pair of resistors (330Ω and 470Ω) as a potential divider:
 
 ![wiring](images/wiring-uds.png)
 
-## Detecting distance
+## Code
+
+To use the ultrasonic distance sensor in Python, you need to know which GPIO pins the echo and trigger are connected to.
+
+1. Open Python 3.
+
+1. In the shell, enter the following line to import `DistanceSensor` from the GPIO Zero library:
+
+    ```python
+    from gpiozero import DistanceSensor
+    ```
+
+    After each line, press **Enter** and the command will be executed immediately.
+
+1. Create an instance of `DistanceSensor` using your echo and trigger pins:
+
+    ```python
+    ultrasonic = DistanceSensor(echo=17, trigger=4)
+    ```
+
+1. See what distance it shows:
+
+    ```python
+    ultrasonic.distance
+    ```
+
+    You should see a number: this is the distance to the nearest object, in metres.
+
+1. Try using a loop to print the distance continuously, while waving your hand in front of the sensor to alter the distance reading:
+
+    ```python
+    while True:
+        print(ultrasonic.distance)
+    ```
+
+    The value should get smaller the closer your hand is to the sensor. Press **Ctrl + C** to exit the loop.
+
+## Ranges
+
+As well as being able to see the distance value, you can also get the sensor to do things when the object is in or out of a certain range.
+
+1. Use a loop to print different messages when the sensor is in range or out of range:
+
+    ```python
+    while True:
+        ultrasonic.wait_for_in_range()
+        print("In range")
+        ultrasonic.wait_for_out_of_range()
+        print("Out of range")
+    ```
+
+    Now wave your hand in front of the sensor; it should switch between showing the message "In range" and "Out of range" as your hand gets closer and further away from the sensor. See if you can work out the point at which it changes.
+
+1. The default range threshold is 0.3m. This can be configured when the sensor is initiated:
+
+    ```python
+    ultrasonic = DistanceSensor(echo=17, trigger=4, threshold_distance=0.5)
+    ```
+
+    Alternatively, this can be changed after the sensor is created, by setting the `threshold_distance` property:
+
+    ```python
+    ultrasonic.threshold_distance = 0.5
+    ```
+
+1. Try the previous loop again and observe the new range threshold.
+
+1. The `wait_for` functions are **blocking**, which means they halt the program until they are triggered. Another way of doing something when the sensor goes in and out of range is to use `when` properties, which can be used to trigger actions in the background while other things are happening in the code.
+
+    First, you need to create a function for what you want to happen when the sensor is in range:
+
+    ```python
+    def hello():
+        print("Hello")
+    ```
+
+    Then set `ultrasonic.when_in_range` to the name of this function:
 
-The ultrasonic distance sensor has not yet been included in the GPIO Zero library, but it will be soon. Until then, you can use a generic input and output device to detect the distance of an object.
+    ```python
+    ultrasonic.when_in_range = hello
+    ```
 
+1. Add another function for when the sensor goes out of range:
 
-```python
-from gpiozero import InputDevice, OutputDevice
-from time import sleep, time
+    ```python
+    def bye():
+        print("Bye")
 
-trig = OutputDevice(4)
-echo = InputDevice(17)
+    ultrasonic.when_out_of_range = bye
+    ```
 
-sleep(2)
+    Now these triggers are set up, you'll see "hello" printed when your hand is in range, and "bye" when it's out of range.
 
-def get_pulse_time():
-    trig.on()
-   	sleep(0.00001)
-	trig.off()
+1. You may have noticed that the sensor distance stopped at 1 metre. This is the default maximum and can also be configured on setup:
 
-	while echo.is_active == False:
-		pulse_start = time()
+    ```python
+    ultrasonic = DistanceSensor(echo=17, trigger=4, max_distance=2)
+    ```
 
-	while echo.is_active == True:
-		pulse_end = time()
+    Or after setup:
 
-	sleep(0.06)
+    ```python
+    ultrasonic.max_distance = 2
+    ```
 
-	return pulse_end - pulse_start
+1. Try different values of `max_distance` and `threshold_distance`.
 
-def calculate_distance(duration):
-	speed = 343
-	distance = speed * duration / 2
-	return distance
+## What next?
 
-while True:
-	duration = get_pulse_time()
-	distance = calculate_distance(duration)
-	print(distance)
-```
+Now you've learned to use an ultrasonic distance sensor, you could:
 
+- Build a proximity sensor alert using a buzzer or a sound file
+- Build a Pi camera photo booth which is activated when a person is close enough to the camera
+- Build a robot with a distance sensor to stop it bumping into other objects