Source: https://mokxi.com/libraries/ultrasonic Updated: 2026-11-02 Libraries / Sensors Arduino library · Sensors # Ultrasonic: HC-SR04 distance in one line Erick Simoes’s 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. Open the example in the editor See the calls Built in on Mokxi: #include 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 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 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’s 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. ### 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. sketch.ino · Arduino Uno R3 ### 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 ### Every reading is 357 or another large constant No echo came back before the timeout, so the library reports the timeout’s 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’s 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. ## Keep going ### Learn - Arduino Ultrasonic Sensor (HC-SR04) Tutorial ### Parts - Ultrasonic ranger ### More sensors libraries - DHT sensor library - DHT20 - VL53L0X - Adafruit_VL53L0X - HX711 Arduino Library - MPU6050 - Adafruit MPU6050 - BME280 Every built-in library · Open the editor ## Try Ultrasonic without installing anything Open the example, change the sketch, and keep your version in a free account. Start building free Open the editor