Open the editorEditor
Arduino library · Sensors

HCSR04 libraries: measureDistanceCm() and dist()

Two unrelated Arduino libraries are called HCSR04 and both are included as HCSR04.h, which is why tutorials that use it look so different. Martin Sosic’s has a class named UltraSonicDistanceSensor with measureDistanceCm(); gamegine’s has a class named HCSR04 with dist(). In Mokxi both classes live in the one header, so either tutorial compiles as written.

Open the example in the editorSee the calls

Built in on Mokxi: #include <HCSR04.h> and it builds, with nothing to install. Free, and no account needed.

What HCSR04 (Martin Sosic, and gamegine) does

Under the hood they do the same job. A 10 µs pulse on TRIG makes the module send its burst of ultrasound, ECHO stays high until the echo comes back, and half that time multiplied by the speed of sound is the distance. Sosic’s version can take the air temperature, since sound travels about 0.6 m/s faster for each degree Celsius, and returns -1 when nothing echoes within 4 meters or the maximum you set.

Next to NewPing and the Ultrasonic library, which have pages of their own, these two are the plainest: no median filter and no timers, just one blocking measurement per call. The example reads a decimal distance every 200 ms with TRIG on pin 12 and ECHO on pin 11 of an Uno; drag the hcsr04 part’s slider to move the target.

Library Manager nameHCSR04 (Martin Sosic, and gamegine)
AuthorMartin Sosic; gamegine
Include#include <HCSR04.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesUltrasonic ranger

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <HCSR04.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "HCSR04 (Martin Sosic, and gamegine)" by Martin Sosic; gamegine from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add HCSR04 (Martin Sosic, and gamegine) to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.0 and 1.1.0, so a sketch written here builds there too.

What to know in the simulator: Two libraries share this header name, so both classes are in it.

The calls you will use

In the order a sketch meets them.

UltraSonicDistanceSensor distanceSensor(12, 11)

Sosic’s class: trigger pin, then echo pin. A third number sets the maximum distance in cm (400 by default) and a fourth a timeout in microseconds.

distanceSensor.measureDistanceCm()

The distance in centimeters as a double, or -1 when nothing echoed in range. It assumes an air temperature of about 19.3 °C.

distanceSensor.measureDistanceCm(25.0)

The same with the speed of sound corrected for a temperature in Celsius, from a thermometer such as a DHT22.

double cm = distanceSensor.measureDistanceCm(25.0);
if (cm < 0) {
  Serial.println("out of range");
}

HCSR04 hc(2, 3)

gamegine’s class: trigger pin, then echo pin.

hc.dist()

The distance in centimeters as a float, or 0 when no echo returned.

HCSR04 hc(2, echoPins, 3)

One trigger shared by several sensors, with their echo pins in a uint8_t array; dist(0), dist(1) and dist(2) read each one.

Example: Distance as a decimal

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include <HCSR04.h>

UltraSonicDistanceSensor distanceSensor(12, 11);  // trig, echo

void setup() {
  Serial.begin(9600);
}

void loop() {
  double cm = distanceSensor.measureDistanceCm();
  Serial.print("cm: ");
  Serial.println(cm, 0);
  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

Open it in the editor, wired and ready to run

Common errors and how to fix them

measureDistanceCm() always returns -1

No echo arrived in the time allowed. Make sure TRIG and ECHO are not swapped, the module has 5 V, and the target is inside the maximum distance and facing the sensor; soft or slanted surfaces scatter the sound away.

dist() always returns 0

In gamegine’s library 0 means a timeout, so it is the same problem as above. Also leave around 60 ms between readings so a late echo from the last ping does not land in the next one.

'UltraSonicDistanceSensor' was not declared in this scope

On a real board the other HCSR04 library is installed. The class name tells which one a tutorial expects: Sosic’s for UltraSonicDistanceSensor, gamegine’s for HCSR04. Mokxi has both, so there the cause is a spelling mistake.

Questions and answers

Which HCSR04 library is the tutorial I found using?

Look at the class name. UltraSonicDistanceSensor with measureDistanceCm() is Martin Sosic’s; HCSR04 with dist() is gamegine’s. Both compile in Mokxi with #include <HCSR04.h>.

How long does one reading block the sketch?

For a target in range, about the echo time, a few milliseconds. With nothing in range Sosic’s call waits for the time sound needs to cover twice the maximum distance before giving up.

Keep going

Learn

Parts

More sensors libraries

Every built-in library · Open the editor

Try HCSR04 (Martin Sosic, and gamegine) without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free
Open the editor