Ultrasonic — Python Reference

HC-SR04 Ultrasonic Distance Sensor

Wiring:

HC-SR04 Pin	Connect To
VCC	5V (some modules work on 3.3V — check yours)
GND	GND
TRIG	GPIO 5
ECHO	GPIO 4 (via voltage divider if module outputs 5V)

{: .important } Voltage divider on ECHO: Some HC-SR04 modules output 5V on the ECHO pin, which could damage the ESP32-S3's 3.3V GPIO. Add a voltage divider: ECHO → 1kΩ → junction → GPIO, and junction → 2kΩ → GND. HC-SR04P variants run natively at 3.3V and don't need this.

How it works: Send a 10µs pulse on TRIG. The sensor emits 8 ultrasonic pulses and raises ECHO HIGH until they return. Measure ECHO duration → calculate distance.

Distance (cm) = echo_duration_µs / 58.2

Code:

from machine import Pin
import time

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

def get_distance():
    """Measure distance in cm. Returns -1 if no reading."""
    trig.off()
    time.sleep_us(2)
    trig.on()
    time.sleep_us(10)
    trig.off()

    timeout = time.ticks_us() + 30000   # 30ms timeout
    while echo.value() == 0:
        if time.ticks_us() > timeout:
            return -1

    start = time.ticks_us()
    timeout = start + 30000
    while echo.value() == 1:
        if time.ticks_us() > timeout:
            return -1

    duration = time.ticks_diff(time.ticks_us(), start)
    return round(duration / 58.2, 1)

while True:
    dist = get_distance()
    if dist != -1:
        print(f"Distance: {dist} cm")
    time.sleep(0.5)

{: .highlight } Did you know? This sensor uses the same principle as bat echolocation — emit a sound, measure how long it takes to bounce back.