Prototype a VL53L0X range decision in Wokwi

Exercise a VL53L0X firmware decision path with an explicit Wokwi range-input surrogate and compare it with one HC-SR04 line without claiming physical-sensor evidence.

Radio Remi: compare the two readings, then state exactly what the simulator did not test., your practice guide

Radio Remi: compare the two readings, then state exactly what the simulator did not test.
Predict the reading, then compare it with the measurement.

Wokwi ESP32

Third party Tool

Tier 1 · Web · No account

Version tested: Wokwi browser simulator and CLI 0.21.1; ESP32 core 3.3.11; Chromium 148.0.7778.96; captureSource playwright:wokwi; captured in the Wokwi web editor on 2026-09-10. Date: 2026-09-10.

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

740 bytes · Circuit connections

Download

sketch.ino

1,129 bytes · ESP32 program

Download

// Wokwi's supported-parts catalogue does not currently contain a VL53L0X.
// This potentiometer is an explicit range-input surrogate for the firmware
// decision path. Replace readTofMm() with the vendor driver on real hardware.
const int TOF_SURROGATE_PIN = 34;
const int TRIG_PIN = 18;
const int ECHO_PIN = 19;

float ultrasonicCm() {
  digitalWrite(TRIG_PIN, LOW); delayMicroseconds(2);
  digitalWrite(TRIG_PIN, HIGH); delayMicroseconds(10);
  digitalWrite(TRIG_PIN, LOW);
  unsigned long pulse = pulseIn(ECHO_PIN, HIGH, 30000);
  return pulse ? pulse / 58.0 : -1.0;
}

int readTofMm() {
  int raw = analogRead(TOF_SURROGATE_PIN);
  return map(raw, 0, 4095, 50, 2000);
}

void setup() {
  Serial.begin(115200);
  pinMode(TOF_SURROGATE_PIN, INPUT);
  pinMode(TRIG_PIN, OUTPUT);
  pinMode(ECHO_PIN, INPUT);
  Serial.println("RANGING READY: VL53L0X range-input surrogate; not a stopping-safety test");
}

void loop() {
  int tofMm = readTofMm();
  float soundCm = ultrasonicCm();
  Serial.printf("ToF surrogate=%d mm status=SIM | HC-SR04=%.1f cm (different beam and physics)\n",
                tofMm, soundCm);
  delay(800);
}

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

Steps

Screens captured against Wokwi ESP32 Wokwi browser simulator and CLI 0.21.1; ESP32 core 3.3.11; Chromium 148.0.7778.96; captureSource playwright:wokwi; captured in the Wokwi web editor on 2026-09-10 on 2026-09-10; the tool may have moved on — the text steps are the contract.

Step 1
Do
In Wokwi's diagram.json editor, identify the labelled optical-range surrogate and the HC-SR04 trigger and echo wiring.
You will see
Power: ToF surrogate target VCC connects to ESP32 3.3 V; GND returns to ground (diagram.json line 11). ToF surrogate signal connects to ESP32 GPIO34 (diagram.json line 12). Power: sonar VCC connects to ESP32 VIN; GND returns to ground (diagram.json line 13). Sonar trigger connects to ESP32 GPIO18 (diagram.json line 14). Sonar echo connects to ESP32 GPIO19 (diagram.json line 14).
Why it matters
GPIO34 is the controlled optical-range surrogate, while GPIO18 and GPIO19 are the separate ultrasonic trigger and echo paths. Later readings can be compared without presenting the surrogate as an actual VL53L0X.
Step 2
Do
In Wokwi's sketch.ino editor, find the surrogate boundary, millimetre conversion, and ultrasonic comparison line.
You will see
Enter the surrogate ToF reader: int readTofMm() { (sketch.ino line 16). Read the surrogate ADC pin: int raw = analogRead(TOF_SURROGATE_PIN); (sketch.ino line 17). Map 12-bit counts to 50–2000 mm: return map(raw, 0, 4095, 50, 2000); (sketch.ino line 18). The surrogate range maps ADC 0 to 50 mm and ADC 4095 to 2000 mm (sketch.ino lines 16–18).
Why it matters
The function labels an ADC-derived surrogate rather than a real optical sensor. Mapping 0–4095 into 50–2000 mm defines the simulated comparison range used later.
Step 3
Do
In the Simulation toolbar, start the run and read the Serial Monitor heading.
You will see
Input: supplied optical-range surrogate sketch. Observed: "RANGING READY: VL53L0X range-input surrogate; not a stopping-safety test". Observed: a ToF surrogate row follows the heading. Expected: the run states its simulation boundary.
Why it matters
The named range input is a surrogate. The heading explicitly rules out a stopping-safety test. The monitor identifies the running measurement model. This statement belongs with every reading from the lab.
Step 4
Do
In the Serial Monitor panel, leave the range input at its supplied setting.
You will see
Input: supplied surrogate setting and 100 cm ultrasonic target. Observed: "ToF surrogate=202 mm status=SIM | HC-SR04=101.4 cm (different beam and physics)". Observed: an earlier transient HC-SR04=-1.0 cm row also appeared. Expected: roughly 200 mm and 100 cm are reported separately.
Why it matters
The optical surrogate is reported in millimetres. The ultrasonic comparison is in centimetres. The valid later row is 202 mm and 101.4 cm. The serial label prevents treating the two devices as the same measurement.
Step 5
Do
In the range-input control panel, set the surrogate to the 500 mm fixture.
You will see
Input: move the labelled surrogate control to its 500 mm fixture. Observed: "ToF surrogate=500 mm status=SIM | HC-SR04=101.4 cm (different beam and physics)". Expected: surrogate changes while the ultrasonic target stays fixed. The preceding valid row was 202 mm and 101.4 cm.
Why it matters
The changed input moved the surrogate to 500 mm. The HC-SR04 comparison stayed at 101.4 cm. The status is still SIM. The two fields are separate simulated range paths.
Step 6
Do
In the Simulation toolbar, stop and restart; read the Serial Monitor safety boundary.
You will see
Input: restart the Wokwi simulation once. Observed: "RANGING READY: VL53L0X range-input surrogate; not a stopping-safety test". Observed after restart: "ToF surrogate=500 mm status=SIM | HC-SR04=101.4 cm (different beam and physics)". Expected: the declared safety limit remains visible after restart.
Why it matters
The heading appears again in the second simulation. The simulator retained the selected surrogate control. The status remains SIM. No physical stopping-safety claim follows from this test.

Chapter checks

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

Why should a ToF reading carry a status or confidence value?
Return to the chapter’s knowledge check
Which choice best fits one controlled, nearby optical zone?
Return to the chapter’s knowledge check

Return to Lidar and Optical Ranging for IoT · Browse Labs

Wokwi ESP32

Get the files

diagram.json

sketch.ino

Steps

1 Step 1

2 Step 2

3 Step 3

4 Step 4

5 Step 5

6 Step 6

Chapter checks

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6