NewPing Library Project Homepage
Background:
When I first received an ultrasonic sensor I was not happy with how poorly it performed. I soon realized the problem wasn't the sensor, it was the available ping and ultrasonic libraries causing the problem. The NewPing library totally fixes these problems, adds many new features, and breathes new life into these very affordable distance sensors.
Features:
- Works with many different ultrasonic sensor models: SR04, SRF05, SRF06, DYP-ME007 & Parallax PING)))™.
- Option to interface with all but the SRF06 sensor using only one Arduino pin.
- Doesn't lag for a full second if no ping echo is received like all other ultrasonic libraries.
- Ping sensors consistently and reliably at up to 30 times per second.
- Compatible with the entire Arduino line-up (and clones), Teensy family (including $19.80 96Mhz 32 bit Teensy 3.2) and non-AVR microcontrollers.
- Timer interrupt method for event-driven sketches.
- Built-in digital filter method ping_median() for easy error correction.
- Uses port registers when accessing pins for faster execution and smaller code size.
- Allows setting of a maximum distance where pings beyond that distance are read as no ping "clear".
- Ease of using multiple sensors (example sketch with 15 sensors).
- More accurate distance calculation (cm, inches & uS).
- Doesn't use pulseIn, which is slow and gives incorrect results with some ultrasonic sensor models.
- Actively developed with features being added and bugs/issues addressed.
New in version 1.8:
Added support for non-AVR microcontrollers. For non-AVR microcontrollers, advanced ping_timer() timer methods are disabled due to inconsistencies or no support at all between platforms. However, standard ping methods are all supported. Added new optional variable to ping(), ping_in(), ping_cm(), ping_median(), and ping_timer() methods which allows you to set a new maximum distance for each ping. Added support for the ATmega16, ATmega32 and ATmega8535 microcontrollers. Changed convert_cm() and convert_in() methods to static members. You can now call them without an object. For example: cm = NewPing::convert_cm(distance);
Download:
Download NewPing v1.8
Show Your Appreciation:
Help future development by making a small donation (the teckel@bex.net payee is correct).
Common Problem Help:
15 Sensors Example Sketch (Multiple Sensors) Help
"vector_7" Error on Compile Help
Example Sketch:
#include <NewPing.h>
#define TRIGGER_PIN 12 // Arduino pin tied to trigger pin on the ultrasonic sensor.
#define ECHO_PIN 11 // Arduino pin tied to echo pin on the ultrasonic sensor.
#define MAX_DISTANCE 200 // Maximum distance we want to ping for (in centimeters). Maximum sensor distance is rated at 400-500cm.
NewPing sonar(TRIGGER_PIN, ECHO_PIN, MAX_DISTANCE); // NewPing setup of pins and maximum distance.
void setup() {
Serial.begin(115200); // Open serial monitor at 115200 baud to see ping results.
}
void loop() {
delay(50); // Wait 50ms between pings (about 20 pings/sec). 29ms should be the shortest delay between pings.
unsigned int uS = sonar.ping(); // Send ping, get ping time in microseconds (uS).
Serial.print("Ping: ");
Serial.print(sonar.convert_cm(uS)); // Convert ping time to distance and print result (0 = outside set distance range, no ping echo)
Serial.println("cm");
}
New in version 1.7:
Removed support for the Arduino Due and Zero because they're both 3.3 volt boards and are not 5 volt tolerant while the HC-SR04 is a 5 volt sensor. Also, the Due and Zero don't support pin manipulation compatibility via port registers which can be done (see the Teensy 3.2).
New in version 1.6:
Corrected delay between pings when using ping_median() method. Added support for the URM37 sensor (must change URM37_ENABLED from false to true). Added support for Arduino microcontrollers like the $20 32 bit ARM Cortex-M4 based Teensy 3.2. Added automatic support for the Atmel ATtiny family of microcontrollers. Added timer support for the ATmega8 microcontroller. Rounding disabled by default, reduces compiled code size (can be turned on with ROUNDING_ENABLED switch). Added TIMER_ENABLED switch to get around compile-time "_vector_7" errors when using the Tone library, or you can use the toneAC, NewTone or TimerFreeTone libraries. Other speed and compiled size optimizations.
New in version 1.5:
Added ping_median() method which does a user specified number of pings (default=5) and returns the median ping in microseconds (out of range pings ignored). This is a very effective digital filter. Optimized for smaller compiled size (even smaller than sketches that don't use a library).
New in version 1.4:
You can now interface with all but the SRF06 sensor using only one Arduino pin. Added support for the Parallax PING)))™ sensor. You can also interface with the SRF06 using one pin if you install a 0.1uf capacitor on the trigger and echo pins of the sensor then tie the trigger pin to the Arduino pin (doesn't work with Teensy). To use the same Arduino pin for trigger and echo, specify the same pin for both values. Various bug fixes.
New in version 1.3:
Big feature addition, event-driven ping! Uses Timer2 interrupt, so be mindful of PWM or timing conflicts messing with Timer2 may cause (namely PWM on pins 3 & 11 on Arduino, PWM on pins 9 and 11 on ATmega, and Tone library). Simple to use timer interrupt functions you can use in your sketches totaly unrelated to ultrasonic sensors (don't use if you're also using NewPing's ping_timer because both use Timer2 interrupts). Loop counting ping method deleted in favor of timing ping method after inconsistant results kept surfacing with the loop timing ping method. Conversion to cm and inches now rounds to the nearest cm or inch. Code optimized to save program space and fixed a couple minor bugs here and there. Many new comments added as well as line spacing to group code sections for better source readability.
NOTE: For Teensy/Leonardo (ATmega32U4) the library uses Timer4 instead of Timer2. Also, only 16Mhz microcontrollers are supported with the timer methods, which means the ATmega8 and ATmega128 will not work with the timer methods. However, the standard ping method should work just fine on 8Mhz microcontrollers.
New in version 1.2:
Lots of code clean-up thanks to Adruino Forum members. Rebuilt the ping timing code from scratch, ditched the pulseIn code as it doesn't give correct results (at least with ping sensors). The NewPing library is now VERY accurate and the code was simplified as a bonus. Smaller and faster code as well. Fixed some issues with very close ping results when converting to inches. All functions now return 0 only when there's no ping echo (out of range) and a positive value for a successful ping. This can effectively be used to detect if something is out of range or in-range and at what distance. Now compatible with Arduino 0023.
New in version 1.1:
Changed all I/O functions to use low-level port registers for ultra-fast and lean code (saves from 174 to 394 bytes). Tested on both the Arduino Uno and Teensy 2.0 but should work on all Arduino-based platforms because it calls standard functions to retrieve port registers and bit masks. Also made a couple minor fixes to defines.
Tim