Measure ultrasonic distance with an ESP32

Convert an echo pulse duration into a distance.

Physics Phoebe, your practice guide

Physics Phoebe
Predict the reading, then compare it with the measurement.

Wokwi ESP32

Third party Tool

Tier 2 · Web · paste-in setup · Account needed to save a project

Version tested: Compiled with arduino-cli 1.5.2-rc.1 for esp32 core 3.3.11; booted headlessly with wokwi-cli 0.26.1 on 2026-09-07; serial line 'Echo=5883 us, distance=101.4 cm' seen at 3.823 s (wall time from CLI start; scenario timeout 20 s simulated time); captured in the Wokwi web editor on 2026-09-09. Date: 2026-09-06.

Open the ESP32 editor, paste diagram.json, then paste sketch.ino.

Open Wokwi to paste in the files (new tab)

Get the files

Use both prepared files. This is a paste-in setup; saving a project requires a Wokwi account.

diagram.json

906 bytes · Circuit connections

Download

sketch.ino

395 bytes · ESP32 program

Download

  1. Use the launch button above to open the ESP32 editor in Wokwi.
  2. Select the editor’s diagram.json tab and replace all its text with the supplied diagram.json.
  3. Select the sketch.ino tab, replace all its text with the supplied sketch.ino, then click Start Simulation.

Steps

Screens captured against Wokwi ESP32 Compiled with arduino-cli 1.5.2-rc.1 for esp32 core 3.3.11; booted headlessly with wokwi-cli 0.26.1 on 2026-09-07; serial line 'Echo=5883 us, distance=101.4 cm' seen at 3.823 s (wall time from CLI start; scenario timeout 20 s simulated time); captured in the Wokwi web editor on 2026-09-09 on 2026-09-06; the tool may have moved on — the text steps are the contract.

  1. Step 1

    Do
    In the Simulation panel, inspect the HC-SR04 wiring after pasting both supplied files.
    You will see
    Power: ultrasonic sensor VCC connects to ESP32 VIN (diagram.json line 25). Ground: ultrasonic sensor GND connects to ESP32 ground (diagram.json line 34). Trigger input connects to ESP32 GPIO18 (diagram.json line 43). Echo output connects to ESP32 GPIO19 (diagram.json line 49).
    Why it matters
    GPIO18 triggers the pulse and GPIO19 times its echo in later distance readings. VIN and ground power the simulated HC-SR04.

  2. Step 2

    Do
    In the sketch.ino editor tab, find pulseIn(19,HIGH,30000) and the distance conversion us/58.0.
    You will see
    Measure the echo pulse with a 30 ms timeout: unsigned long us=pulseIn(19,HIGH,30000); (sketch.ino line 4). Report a missing echo: if(!us) Serial.println("No echo: out of range or wiring fault"); (sketch.ino line 5). Convert pulse duration to distance in cm: else Serial.printf("Echo=%lu us, distance=%.1f cm\n",us,us/58.0); (sketch.ino line 6). Wait between readings: delay(500); (sketch.ino line 7).
    Why it matters
    The 30 ms pulse timeout bounds a missing echo. The later serial line distinguishes no echo from a valid microsecond measurement converted to centimetres by division by 58.

  3. Step 3

    Do
    In the Simulation toolbar, click play and read the first Serial Monitor echo line.
    You will see
    Input: supplied HC-SR04 target at 100 cm. Observed: "Echo=5883 us, distance=101.4 cm". Observed: the monitor repeats distance rows while running. Expected: echo time and converted distance appear together.
    Why it matters
    The run exposes raw pulse duration. The conversion prints distance in centimetres. The simulator reports about 101.4 cm. A live row is available before changing the target.

  4. Step 4

    Do
    In the Serial Monitor panel, compare the reported distance with the 100 cm control.
    You will see
    Input: HC-SR04 control at 100 cm. Observed: "Echo=5883 us, distance=101.4 cm". Expected: a reading near the simulator target. Difference: 1.4 cm above the control setting.
    Why it matters
    The echo duration is 5883 microseconds. The sketch reports 101.4 cm. The control is set to 100 cm. This compares model output with a simulator fixture.

  5. Step 5

    Do
    In the HC-SR04 control panel, set distance to 50 cm and read Serial Monitor.
    You will see
    Input: HC-SR04 distance control 50 cm. Observed: "Echo=2942 us, distance=50.7 cm". Expected: a shorter pulse and distance than baseline. The initial row was 5883 us and 101.4 cm.
    Why it matters
    The pulse duration roughly halves. The displayed distance falls to 50.7 cm. The change follows the control direction. This is a second simulated range fixture.

  6. Step 6

    Do
    In the HC-SR04 control panel, set distance to 200 cm and read Serial Monitor.
    You will see
    Input: HC-SR04 distance control 200 cm. Observed: "Echo=11759 us, distance=202.7 cm". Expected: a longer pulse and larger distance. The previous 50 cm row was 2942 us and 50.7 cm.
    Why it matters
    The echo pulse grows to 11759 microseconds. The displayed distance grows to 202.7 cm. The two controlled targets exercise both directions. The model result still needs a real-world reference for hardware accuracy.

  7. Step 7

    Do
    In Wokwi's diagram.json editor, temporarily remove the sensor:ECHO to esp:D19 connection and start the simulation; inspect the missing-echo branch in sketch.ino and its result in Serial Monitor. Restore the supplied diagram for normal measurements.
    You will see
    Input: run the supplied sketch with the ECHO connection temporarily absent in Wokwi. Observed: "No echo: out of range or wiring fault". Observed: no distance number appears in the failure line. Expected: the if(!us) branch reports a missing pulse.
    Why it matters
    The simulated sensor cannot return a pulse to GPIO19 without ECHO wiring. The 30 ms pulseIn timeout returns zero in this run. The code prints a failure state instead of a distance. The temporary wiring change is a fault fixture, not the supplied circuit.

Chapter checks

These questions refer to the chapter’s examples. Use the return links to review their answers.

  1. A distance sensor works on a flat white target in the lab but fails when installed over angled dark material. What is the best under-the-hood response?

    Return to the chapter’s knowledge check

  2. A wearable activity prototype uses an accelerometer successfully on a desk, then moves to wrist-worn use. What evidence should the practitioner add?

    Return to the chapter’s knowledge check

Return to Common Sensors and MEMS · Browse Labs