Ultrasonic: HC-SR04 distance in one line
Erick Simoes鈥檚 Ultrasonic library is the shortest way to read an HC-SR04: create the sensor with its trigger and echo pins, call read(), and you have centimeters. Behind that one call the library sends a 10 microsecond trigger pulse, times the echo with pulseIn() and divides by 58 microseconds per centimeter, the time sound takes to get there and back.
Built in on Mokxi: #include <Ultrasonic.h> and it builds, with nothing to install. Free, and no account needed.
What Ultrasonic does
It also handles the three-pin sensors from Seeed and Parallax, which trigger and listen on the same pin: give the constructor one pin instead of two. read(INC) gives inches instead of centimeters.
An echo that never comes back, because nothing is in front of the sensor or the target absorbs sound, does not return zero here. The read waits until the timeout and reports the distance that timeout stands for, about 3.4 m at the default 20 ms, so a reading near the top of the range usually means nothing was seen.
| Library Manager name | Ultrasonic |
|---|---|
| Author | Erick Simoes |
| Include | #include <Ultrasonic.h> |
| Boards | every board Mokxi compiles for |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Ultrasonic ranger |
Install it
It builds on every board Mokxi compiles for.
In Mokxi it is built in: #include <Ultrasonic.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Ultrasonic" by Erick Simoes from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add Ultrasonic to lib_deps in PlatformIO. Mokxi follows the calls of release 3.0.0, so a sketch written here builds there too.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 ATtiny85 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
Ultrasonic ultrasonic(12, 13)
Creates a sensor with trigger on pin 12 and echo on pin 13.
Ultrasonic ultrasonic(7)
Creates a three-pin sensor (Seeed Grove or Parallax PING) that uses pin 7 for both.
ultrasonic.read()
Distance in whole centimeters. read(INC) gives inches.
Serial.print("Distance in CM: ");
Serial.println(ultrasonic.read());
delay(100);ultrasonic.setTimeout(40000UL)
How long to wait for an echo, in microseconds. Longer reaches farther; shorter keeps a busy loop responsive.
ultrasonic.setMaxDistance(200)
Sets the timeout from a distance in centimeters instead.
Example: Distance in centimeters
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <Ultrasonic.h>
Ultrasonic ultrasonic(12, 11); // trig, echo
void setup() {
Serial.begin(9600);
}
void loop() {
Serial.print("Distance in CM: ");
Serial.println(ultrasonic.read());
delay(200);
}Wiring
- Arduino Uno R3 12 to Ultrasonic ranger TRIG
- Arduino Uno R3 11 to Ultrasonic ranger ECHO
- Arduino Uno R3 5V to Ultrasonic ranger VCC
- Arduino Uno R3 GND to Ultrasonic ranger GND
Common errors and how to fix them
Every reading is 357 or another large constant
No echo came back before the timeout, so the library reports the timeout鈥檚 distance. Check the echo wire, point the sensor at a flat hard surface within range, and keep it away from soft fabric.
Readings jump around when two sensors are used
Each sensor hears the other鈥檚 ping. Read them one after another with a short delay between them, so the first echo has died away before the second sensor fires.
The echo pin damages a 3.3 V board
The HC-SR04 runs on 5 V and its echo pin outputs 5 V. On an ESP32, Pico or other 3.3 V board, put a voltage divider (for example 1 k and 2 k) on the echo line, or use an HC-SR04 sold for 3.3 V.
Try Ultrasonic without installing anything
Open the example, change the sketch, and keep your version in a free account.