UltraPing Arduino Library

A simple, timer-safe ultrasonic sensor library for Arduino, heavily inspired by the API of the popular NewPing library.

Overview

UltraPing is designed to provide a straightforward way to interface with common ultrasonic distance sensors like the HC-SR04. Its primary design goal is timer safety. Unlike more advanced libraries that use hardware timer interrupts for non-blocking operations, UltraPing exclusively uses blocking functions (delayMicroseconds, pulseIn).

This means UltraPing will not conflict with other libraries that require specific hardware timers, such as the standard Arduino tone() function (which often uses Timer2 on AVR boards).

Why Use UltraPing?

• Timer-Safe: The main reason. Use it when you need both an ultrasonic sensor and another library that monopolizes a hardware timer (like tone(), some PWM or servo libraries).
• Simple API: The public interface is modeled after NewPing, making it familiar to many users.
• Lightweight: With a focus on core functionality, the library is small and easy to understand.
• Built-in Filtering: Includes a ping_median() method to easily discard outlier readings and reduce noise.
• One-Pin Mode: Automatically supports one-pin operation if the same pin is specified for trigger and echo.

Why Not Just Use NewPing?

NewPing is a fantastic, feature-rich library. However, its advanced event-driven features (ping_timer(), timer_us(), etc.) rely on hardware timer interrupts. If your project requires these non-blocking features, NewPing is the superior choice.

UltraPing was created for the specific niche where NewPing's timer usage creates a conflict. It provides only the core, blocking functionality, ensuring maximum compatibility with other libraries.

Installation

1. Download the latest release from the repository page.
2. In the Arduino IDE, go to Sketch > Include Library > Add .ZIP Library....
3. Select the downloaded ZIP file.
4. The library will now be available in the Sketch > Include Library menu.

API Reference

Constructor

UltraPing sonar(triggerPin, echoPin, [maxCmDistance])

• triggerPin: The Arduino pin connected to the sensor's TRIGGER pin.
• echoPin: The Arduino pin connected to the sensor's ECHO pin.
  • For one-pin mode, use the same pin for both arguments.
• maxCmDistance (optional): The maximum distance in cm you want to sense. Defaults to 400.

---

Core Methods

unsigned int ping([maxCmDistance])

• Sends a ping and returns the round-trip travel time in microseconds (µs).
• Returns 0 (defined as NO_ECHO) if no echo is received within the timeout.
• This is a blocking function.

unsigned int ping_cm([maxCmDistance])

• Same as ping(), but returns the distance in whole centimeters.

unsigned int ping_in([maxCmDistance])

• Same as ping(), but returns the distance in whole inches.

unsigned int ping_median(iterations, [maxCmDistance])

• Performs a number of pings (iterations, default 5) and returns the median result in microseconds (µs). Excellent for filtering out noise.
• Returns 0 (NO_ECHO) if no valid pings are received.

---

Static Conversion Methods

These can be called without creating an UltraPing object.

UltraPing::convert_cm(echoTime)

• Converts a time in microseconds to a distance in centimeters.

UltraPing::convert_in(echoTime)

• Converts a time in microseconds to a distance in inches.

Example Usage

#include <UltraPing.h>

// --- Pin Definitions ---
#define TRIGGER_PIN  7  // Arduino pin connected to trigger
#define ECHO_PIN     8  // Arduino pin connected to echo

// --- Constants ---
#define MAX_DISTANCE 200 // Maximum distance to ping (in cm)

// Initialize the UltraPing library
UltraPing sonar(TRIGGER_PIN, ECHO_PIN, MAX_DISTANCE);

void setup() {
  Serial.begin(115200);
  Serial.println("UltraPing Example");
}

void loop() {
  // Wait 50ms between pings
  delay(50);
  
  // Get distance in centimeters.
  // ping_cm() returns 0 if no echo is received.
  unsigned int distance = sonar.ping_cm();

  Serial.print("Distance: ");
  if (distance == NO_ECHO) {
    Serial.println("Out of range");
  } else {
    Serial.print(distance);
    Serial.println(" cm");
  }
}