Raspberry Pi Learning Resources

# Ultrasonic distance sensor

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.

## Wiring

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:

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

2. In the shell, enter the following line to import `DistanceSensor` from the GPIO Zero library:

``from gpiozero import DistanceSensor``

After each line, press Enter and the command will be executed immediately.

3. Create an instance of `DistanceSensor` using your echo and trigger pins:

``ultrasonic = DistanceSensor(echo=17, trigger=4)``
4. See what distance it shows:

``ultrasonic.distance``

You should see a number: this is the distance to the nearest object, in metres.

5. Try using a loop to print the distance continuously, while waving your hand in front of the sensor to alter the distance reading:

``````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:

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

2. The default range threshold is 0.3m. This can be configured when the sensor is initiated:

``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:

``ultrasonic.threshold_distance = 0.5``
3. Try the previous loop again and observe the new range threshold.

4. 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:

``````def hello():
print("Hello")``````

Then set `ultrasonic.when_in_range` to the name of this function:

``ultrasonic.when_in_range = hello``
5. Add another function for when the sensor goes out of range:

``````def bye():
print("Bye")

ultrasonic.when_out_of_range = bye``````

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.

6. You may have noticed that the sensor distance stopped at 1 metre. This is the default maximum and can also be configured on setup:

``ultrasonic = DistanceSensor(echo=17, trigger=4, max_distance=2)``

Or after setup:

``ultrasonic.max_distance = 2``
7. Try different values of `max_distance` and `threshold_distance`.

## What next?

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
• Continue to the next worksheet on analogue inputs