PyRaspBeta

HC-SR04 distance sensor

The HC-SR04 is an ultrasonic ranger for $3: a 40 kHz ping leaves one can, bounces off an object and returns to the other, and the length of the echo pulse tells you the distance. It measures 2–400 cm to within a few millimetres. Two details matter on a Pi: the module runs from 5 V, and its ECHO output is a 5 V signal, so it must go through a divider before it reaches a GPIO. The distance module kit is this sensor with the 1 kΩ / 2 kΩ divider already fitted.

HC-SR04 distance sensor

Pins

PinWhat it isType
VCCSupply 5 Vpower
TRIGTrigger input (≥ 10 µs high pulse)io
ECHOEcho output — 5 V logic!io
GNDGroundground

In circuit.py:

TRIG is an input: a high pulse of at least 10 µs starts the ping. ECHO goes high when the burst leaves and low when the reflection returns — 5 V high, hence the divider.

Wiring it in circuit.py

circuit.py
from wiring import *

pi = Pi()

sonar = HCSR04()

pi.V5 >> sonar.vcc
sonar.gnd >> pi.GND
pi.GPIO23 >> sonar.trig                 # any GPIO
sonar.echo >> Resistor(1000) >> pi.GPIO24   # 5 V echo → 3.3 V at the tap
pi.GPIO24 >> Resistor(2000) >> pi.GND

The divider drops the echo's 5 V to 5 × 2 kΩ / (1 kΩ + 2 kΩ) ≈ 3.3 V — right at the top of the safe range. Wired straight to a GPIO, the simulator raises an overvoltage warning and the judge's damage check fails it, exactly as the real pin would eventually damage the SoC. The kit hides all of this behind echo, trig, vcc and gnd.

Driving it in main.py

main.py
from gpiozero import DistanceSensor
from time import sleep

sensor = DistanceSensor(echo=24, trigger=23, max_distance=4)

while True:
    print(f"{sensor.distance * 100:.1f} cm")
    sleep(0.5)

gpiozero.DistanceSensor handles the 10 µs trigger and times the echo for you. sensor.distance is in metres; max_distance=4 matches the sensor's range so a lost echo reads as "nothing there" rather than garbage. Give it at least 60 ms between pings, or the previous echo can still be in flight — gpiozero's built-in queue and sensor.wait_for_in_range() make that automatic, and the half-second loop above stays well clear of the limit.

Electrical notes

  • Supply is 4.5–5.5 V from the 5 V rail; working current is about 15 mA, mostly during the ping.
  • The ECHO output swings to 5 V — divide it with the 1 kΩ / 2 kΩ pair. TRIG is a 3.3 V-safe input.
  • A trigger pulse shorter than 10 µs is ignored; the module replies after a 200 µs burst and times out at 38 ms (roughly 4 m). Keep 60 ms between pings.
  • Distance is echo time × speed of sound ÷ 2. Sound is about 1.8 % faster at 30 °C than at 0 °C; the model uses the zone's temperature.
  • Soft or angled surfaces may not echo at all; the simulator models that as a missedEchoPct knob that makes the echo time out.

Simulator vs real hardware

  • The range comes from the distanceCm feed: a slider by default, or a wave for something swinging past, or events for someone walking by. The canvas draws a ping animation while the module is busy.
  • Ten triggers during one ping are ignored: the module is busy until the echo falls or times out, like the real one.
  • The echo's duration is computed from the speed of sound at the ambient temperature, with 0.3 cm resolution and a little noise — but there is no cross-talk, no double-bounce and no minimum-distance dead zone.
  • If the echo is wired to a GPIO without a divider the simulation reports an overvoltage warning; there is no slow degradation to model.

Going deeper

Further reading