Activity 2.13: Ultrasonic Distance

Motion & Autonomy — Day 3 of 4

Activity 2.13

Ultrasonic Distance

Key Concepts

Timing a Pulse

Unit Conversion

Out-of-Range Values

Your Robot Moves. It Cannot See.

Last session it drove wherever you told it to, straight into whatever was there. Today it gets a way to find out.

Not with a camera. By shouting and timing the echo, exactly like a bat.

Send a Pulse, Time What Comes Back

One pin gives the sensor a brief nudge — ten microseconds is enough. The sensor emits a chirp too high to hear, then holds a second pin HIGH for exactly as long as the echo takes to return.

So the distance is not measured. It is timed.

You Have Timed Something Before

2.7:  ticks_ms()      milliseconds, for human reflexes
2.13: time_pulse_us() microseconds, for the speed of sound

A reaction time was a couple of hundred milliseconds. An echo from across the room takes about three thousand microseconds — a thousand times finer, so it needs a finer clock.

Microseconds Into Centimeters

sound travels 0.0343 cm every microsecond
the echo goes out AND back, so divide by 2

    cm = microseconds / 58

The same shape as Activity 2.9: a raw number that means nothing until you convert it. There the datasheet gave you the rule. Here physics does.

Sometimes Nothing Comes Back

duration = time_pulse_us(echo, 1, TIMEOUT_US)
if duration < 0:
    return -1          # nothing came back

Too far away, or angled so the echo bounces off sideways. The sensor simply never answers, and the timer gives up.

A negative sentinel again — the same trick as the false start in Activity 2.7, because a real distance is never negative.

Today's Objectives

Wiring the HC-SR04 and sending a trigger pulse
Timing the echo with time_pulse_us()
Converting a pulse duration into centimeters
Handling readings where nothing comes back

Key Terms

Ultrasonic: Sound above the range of human hearing — what the sensor emits.
Trigger and Echo: Two pins: one tells the sensor to chirp, the other reports how long the echo took.
Microsecond: A millionth of a second. A thousand of them make one millisecond.
Timeout: Giving up on a measurement that never arrives, rather than waiting forever.

'F' → Fullscreen

Build

Keep the motor driver wired — session 16 needs both. Create a new MicroPython script named 2-13-distance.

Task 1: Time the Echo

Wire the sensor: VCC to 3V3, GND to GND, Trig to GPIO 22, Echo to GPIO 20.
Send a 10-microsecond pulse on Trig, then time how long Echo stays HIGH.
Print the raw number of microseconds and move your hand towards and away from the sensor.

Power it from 3V3 rather than 5V. These GPIO pins expect 3.3V signals, and the Echo pin answers at whatever voltage the sensor runs on.

Hookup diagram for the HC-SR04 ultrasonic sensor showing VCC to 3V3, Trig to GPIO 22, Echo to GPIO 20, and GND to ground

[PHOTO PLACEHOLDER — Task 1: Ultrasonic Sensor Mounted Facing Forward]

1
from machine import Pin, time_pulse_us
2
import time
3

4
trigger = Pin(22, Pin.OUT)
5
echo = Pin(20, Pin.IN)
6

7
while True:
8
    trigger.value(0)
9
    time.sleep_us(2)
10
    trigger.value(1)
11
    time.sleep_us(10)
12
    trigger.value(0)
13
    duration = time_pulse_us(echo, 1, 30000)
14
    print("echo lasted", duration, "microseconds")
15
    time.sleep(0.5)

Task 2: Into Centimeters

Divide the duration by 58 and print centimeters instead.
Check it against a ruler. Hold something at 20cm and see what you get.

Work out where 58 comes from before you accept it. Sound covers 0.0343cm per microsecond, and the echo travels the distance twice.

1
from machine import Pin, time_pulse_us
2
import time
3

4
trigger = Pin(22, Pin.OUT)
5
echo = Pin(20, Pin.IN)
6

7
while True:
8
    trigger.value(0)
9
    time.sleep_us(2)
10
    trigger.value(1)
11
    time.sleep_us(10)
12
    trigger.value(0)
13
    duration = time_pulse_us(echo, 1, 30000)
14
    print(duration // 58, "cm")
15
    time.sleep(0.5)

Task 3: When Nothing Comes Back

Point the sensor at the ceiling. The reading will be nonsense or the program will stall.
Move the whole measurement into read_distance(), and return -1 when the timer gives up.
Print a readable message instead of a meaningless number.

1
from machine import Pin, time_pulse_us
2
import time
3

4
trigger = Pin(22, Pin.OUT)
5
echo = Pin(20, Pin.IN)
6

7
TIMEOUT_US = 30000
8

9

10
def read_distance():
11
    trigger.value(0)
12
    time.sleep_us(2)
13
    trigger.value(1)
14
    time.sleep_us(10)
15
    trigger.value(0)
16
    duration = time_pulse_us(echo, 1, TIMEOUT_US)
17
    if duration < 0:
18
        return -1
19
    return duration // 58
20

21

22
while True:
23
    cm = read_distance()
24
    if cm < 0:
25
        print("nothing in range")
26
    else:
27
        print(cm, "cm")
28
    time.sleep(0.5)

Task 4: Steady the Reading

Write read_average_distance(samples) that takes several readings and averages the good ones.
Skip the failures rather than letting a -1 drag the average down.
Return -1 only if every reading failed.

Same idea as the temperature sensor in 2.9, with one new wrinkle: here some readings are not merely noisy but entirely absent, so you have to count how many were usable.

1
from machine import Pin, time_pulse_us
2
import time
3

4
trigger = Pin(22, Pin.OUT)
5
echo = Pin(20, Pin.IN)
6

7
TIMEOUT_US = 30000
8

9

10
def read_distance():
11
    trigger.value(0)
12
    time.sleep_us(2)
13
    trigger.value(1)
14
    time.sleep_us(10)
15
    trigger.value(0)
16
    duration = time_pulse_us(echo, 1, TIMEOUT_US)
17
    if duration < 0:
18
        return -1
19
    return duration // 58
20

21

22
def read_average_distance(samples):
23
    total = 0
24
    good = 0
25
    for i in range(samples):
26
        cm = read_distance()
27
        if cm > 0:
28
            total = total + cm
29
            good = good + 1
30
        time.sleep(0.02)
31
    if good == 0:
32
        return -1
33
    return total // good
34

35

36
while True:
37
    cm = read_average_distance(5)
38
    if cm < 0:
39
        print("nothing in range")
40
    else:
41
        print(cm, "cm")
42
    time.sleep(0.3)

Task 5: Put It on the Screen

Bring the OLED and show() back from Activity 2.11.
Display the distance on the glass so you can read it while walking around with the robot.

1
from machine import Pin, time_pulse_us
2
import qwiic_large_oled
3
import time
4

5
trigger = Pin(22, Pin.OUT)
6
echo = Pin(20, Pin.IN)
7

8
TIMEOUT_US = 30000
9

10
oled = qwiic_large_oled.QwiicLargeOled()
11
oled.begin()
12

13

14
def read_distance():
15
    trigger.value(0)
16
    time.sleep_us(2)
17
    trigger.value(1)
18
    time.sleep_us(10)
19
    trigger.value(0)
20
    duration = time_pulse_us(echo, 1, TIMEOUT_US)
21
    if duration < 0:
22
        return -1
23
    return duration // 58
24

25

26
def read_average_distance(samples):
27
    total = 0
28
    good = 0
29
    for i in range(samples):
30
        cm = read_distance()
31
        if cm > 0:
32
            total = total + cm
33
            good = good + 1
34
        time.sleep(0.02)
35
    if good == 0:
36
        return -1
37
    return total // good
38

39

40
def show(oled, line1, line2):
41
    oled.clear(oled.PAGE)
42
    oled.print(line1)
43
    oled.print(line2)
44
    oled.display()
45

46

47
while True:
48
    cm = read_average_distance(5)
49
    if cm < 0:
50
        show(oled, "Distance", "out of range")
51
    else:
52
        show(oled, "Distance", str(cm) + " cm")
53
    time.sleep(0.3)

[PHOTO PLACEHOLDER — Task 5: OLED Showing a Live Distance Reading]

Challenge (Optional): Find the Blind Spots

Work out the closest and furthest distances your sensor reports reliably.
Try a soft object like a jumper, and a hard flat one like a book. Try holding the book at an angle.
Write down what fools it. The Final Project will thank you.

Checkpoint

Moving your hand towards and away from the sensor should print something like:

24 cm
23 cm
nothing in range
41 cm

A book held at 20cm reads within a couple of centimeters of 20
Moving your hand closer makes the number fall smoothly
Pointing at the ceiling reports out of range rather than a wild number
The program never stalls, whatever you point it at

Reflection

Answer the following questions before submitting your work.

Explain where the number 58 comes from, using the speed of sound and the path the echo takes.
Activity 2.7 timed a reaction in milliseconds; this activity times an echo in microseconds. Explain why the finer unit is necessary here and was not there.
read_average_distance() counts how many readings were usable instead of just dividing by samples. Explain what would go wrong with the simpler version.

Submit

Submit the required files to the appropriate dropbox.