Ultrasonic sensor¶

HC-SR04 is the go-to sensor for "how far is the object in front of me?". You find it in obstacle-avoiding robots, parking systems, and presence alarms. Here we wire it to the ESP32 and read the distance in MicroPython using machine.time_pulse_us.

Description¶

The HC-SR04 has 4 pins: VCC, Trig, Echo, GND. The principle is the same as bats use:

1. The ESP32 pulses Trig HIGH for 10 microseconds.
2. The sensor emits 8 cycles of ultrasound at 40 kHz (inaudible to humans).
3. When the ultrasound hits an obstacle it bounces back as an echo.
4. The Echo pin stays HIGH for exactly as long as the sound's round-trip takes.
5. The ESP32 times the pulse with time_pulse_us and computes the distance.

Distance math¶

Sound travels through air at ~343 m/s = 0.0343 cm/µs. Since the measured time is the round trip, we divide by 2:

distance [cm] = duration [µs] × 0.0343 / 2

Or equivalently: duration / 58.3.

Useful range: 2 cm – 400 cm, ~3 mm accuracy.

Components¶

Wiring¶

Voltage divider on Echo (classic HC-SR04)¶

   Echo (5 V) ──[ 1 kΩ ]──┬── GPIO 18 (3.3 V)
                           │
                          [ 2 kΩ ]
                           │
                          GND

V_out = V_in × 2 / (1 + 2) = 5 × 2/3 ≈ 3.3 V — exactly the ESP32 threshold.

Full schematic¶

    ESP32                   HC-SR04
    Vin / 5V ────────── VCC
    GND ────────────── GND
    GPIO 5 ──────────── Trig
    GPIO 18 ◄─[1 kΩ]─── Echo
                    └──[2 kΩ]──── GND

Code¶

from machine import Pin, time_pulse_us
import time

# --- Setup ---

trig = Pin(5, Pin.OUT)
echo = Pin(18, Pin.IN)


def measure_distance_cm(timeout_us=30_000):
    """Return the distance in cm or None if no echo came back."""
    # Make sure Trig starts LOW
    trig.value(0)
    time.sleep_us(2)

    # 10 µs pulse on Trig
    trig.value(1)
    time.sleep_us(10)
    trig.value(0)

    # Wait for the HIGH pulse on Echo and measure its duration in µs
    duration_us = time_pulse_us(echo, 1, timeout_us)

    if duration_us < 0:
        return None   # timeout — no echo

    return duration_us * 0.0343 / 2


print("HC-SR04 readings. Ctrl+C to stop.\n")

while True:
    try:
        d = measure_distance_cm()
        if d is None:
            print("Out of range")
        else:
            print(f"Distance: {d:6.2f} cm")
        time.sleep_ms(200)
    except KeyboardInterrupt:
        print("\nStop.")
        break

Run the script¶

1. Plug the ESP32 into USB and assemble the circuit (mind the voltage divider).
2. In Thonny paste the code and press Run (F5).
3. Wave your hand in front of the sensor. The console shows values like:

HC-SR04 readings. Ctrl+C to stop.

Distance:  37.42 cm
Distance:  22.18 cm
Distance:   8.74 cm
Distance:   3.12 cm
Out of range

For a stable reading, average several measurements (see example below).

Example: median filter¶

The sensor occasionally returns outliers (echoes bouncing off multiple surfaces). A simple filter — the median of 5 readings — kills most of them:

def measure_smoothed(samples=5):
    """Median of `samples` readings — robust to outliers."""
    readings = []
    for _ in range(samples):
        d = measure_distance_cm()
        if d is not None:
            readings.append(d)
        time.sleep_ms(40)   # >= 60 ms is ideal
    if not readings:
        return None
    readings.sort()
    return readings[len(readings) // 2]

Example: proximity LED alarm¶

Light the onboard LED (GPIO 2) when something gets closer than 15 cm:

from machine import Pin, time_pulse_us
import time

trig = Pin(5, Pin.OUT)
echo = Pin(18, Pin.IN)
led = Pin(2, Pin.OUT)

THRESHOLD_CM = 15

def distance_cm():
    trig.value(0); time.sleep_us(2)
    trig.value(1); time.sleep_us(10); trig.value(0)
    d = time_pulse_us(echo, 1, 30_000)
    return None if d < 0 else d * 0.0343 / 2

while True:
    d = distance_cm()
    led.value(1 if d is not None and d < THRESHOLD_CM else 0)
    time.sleep_ms(100)

Troubleshooting¶

Extension ideas¶

• Parking system: a passive buzzer that beeps faster as you get closer — combine with a PWM pin (see Servo) which sets the tone frequency.
• 180° radar: mount the HC-SR04 on a servo and sweep — show readings on an LCD or stream them to the PC.
• Water-level indicator: measure the distance to the water surface in a tank.
• Wireless telemetry: ESP-NOW can ship the distance to a master board that logs the data.

References¶

• MicroPython — machine.time_pulse_us
• HC-SR04 datasheet (Cytron)
• Random Nerd Tutorials — ESP32 Ultrasonic Sensor (MicroPython)