= HC-SR04 Ultrasonic Sensor Library =

This library can be used to read data from the HC-SR04 ultrasonic sensor.

{{{#!wiki red/solid
I am in the process of releasing a version 2.0 of this library. The accuracy has been greatly improved. And now has an additional method to connect it to a temperature sensor. I am also toying with the idea of making it work in an interrupt instead of being polled. I would like to get this into the code before version 2.0 is released. Version 2.0 will NOT be downwards compatible with the currently released version.
}}}


== Features ==

There are five methods in the Ultrasonic class.

 1. {{{Ultrasonic::CM}}} and {{{Ultrasonic::IN}}} are static const class member objects on the {{{Ultrasonic}}} class.
 1. {{{long timing()}}} This method reads data from the sensor. The return value is used for the {{{microsec}}} argument to the next method described below.
 1. {{{long convert(long microsec, int metric)}}} This method converts the microsecond output of {{{timing()}}} passed to {{{microsec}}} to either centimeters or inches. The {{{metric}}} argument can be either of the two member object discribed in number one above.
 1. {{{void setDivisor(float value, int metric)}}} This method permits the changing of the ''cm'' and ''in'' divisor so the accuracy of the sensor can be adjusted for distance. The {{{value}}} argument is taken from the table below and the {{{metric}}} argument is either of the two member objects from number one above.
 1. {{{bool sampleCreate(size_t size, ...)}}} This method sets up the buffer(s) needed to derive the standard deviation. The {{{size}}} argument is the number of buffers that you will need. For each buffer, you need to pass an additional argument indicating the length of that buffer. ex. {{{bool success = sampleCreate(3, 10, 15, 8)}}} This indicates that there will be three buffers each with lengths of 10, 15, 8 respectively. You should check the return value for {{{true}}} before proceeding with calling the two following methods.
 1. {{{void sampleClear()}}} This method resets all the buffers to zero.
 1. {{{float unbiasedStdDev(long value, size_t bufNum)}}} This method generates the standard deviation. The {{{value}}} argument can be the return value of either {{{timing()}}} or {{{convert()}}}. The {{{bufNum}}} argument is the ordinal number of the buffer meaning {{{0 - n}}}. If you have defined three buffers the numbers would be {{{0, 1, 2}}}.

== Divisor Chart ==

=== Inches ===
|| Distance || Divisor                 || Default ||
||   6.25   || 68.3333 || ||
||  18.25   || 70.1633 || (./) ||
||  36.25   || 71.6152 || ||
||  54.25   || 72.3182 || ||
||  72.25   || 72.5384 || ||
||  90.25   || 72.6277 || ||
|| 108.25   || 72.9473 || ||

=== Centimeters ===

|| Distance || Divisor                 || Default ||
||  15.875  || 26.9029 || ||
||  46.355  || 27.6233 || (./) ||
||  92.075  || 28.1949 || ||
|| 137.795  || 28.4717 || ||
|| 183.515  || 28.5584 || ||
|| 229.235  || 28.5936 || ||
|| 274.955  || 28.7194 || ||

'''
Notes:''
  1. The extra 0.25 inch is the distance between the outside of the emitter case to the emitter itself.
  1. Centimeters are conversions from inches.
'''''

== Python Serial Terminal ==

Also available is a serial terminal specifically written for gathering data for this project. It is a read only terminal and can create CSV files of the incoming data. It could be used with the standard deviation example sketch.

{{{
Usage: readSerial.py [h] -d <device> -c <CSV File> -s <Raw data dump file>

Options:
  -h, --help            show this help message and exit
  -d DEVICE, --device=DEVICE
                        Serial device
  -c CSVFILE, --csv=CSVFILE
                        CSV output filename
  -s STREAM, --stream=STREAM
                        Raw stream filename
}}}

The script can be found below:

[[attachment:readSerial.py|Python Serial Terminal]]

== Download ==

{{{#!wiki yellow/solid
'''NOTE: The latest version supports changing the ''cm'' and ''in'' divisor. Changing these divisors will make the distance more accurate between different distances from the sensor. The documented divisor 29 for ''cm'' and 74 for ''in'' seem to work well only at the maximum range of the sensors, 15 feet. Where the current default of ''27.6233'' for ''cm'' and ''70.1633'' for ''in'' work better at the ''46''/''18'' ''cm''/''in'' distances.'''
}}}

[[http://tetrasys.homelinux.org/cgi-bin/viewvc.cgi/HCSR04Ultrasonic/?root=Arduino|SVN Repository]] This is off site and may not be accessible at all times.

=== Latest Version: 1.1.2 ===

[[http://tetrasys-design.net/download/HCSR04Ultrasonic/HCSR04Ultrasonic-1.1.2.tar.gz|Download Tarball]]

[[http://tetrasys-design.net/download/HCSR04Ultrasonic/HCSR04Ultrasonic-1.1.2.zip|Download ZIP]]

{{{#!wiki red/solid
'''WARNING:''' '''''If you downloaded any of these packages before 1:00 PM EST on Sep 17, 2011 there was a very big bug in the !UltrasonicDemo.pde. Please download the latest package.'''''
}}}

== Links ==

[[http://www.micropik.com/PDF/HCSR04.pdf|HC-SR04 Specs]]

[[http://tushev.org/articles/electronics/42-how-it-works-ds18b20-and-arduino|DS18B20 and Arduino]]

[[http://www.pjrc.com/teensy/td_libs_OneWire.html|One Wire Library]]

[[http://arduino.cc/blog/2011/10/20/hc-sr04-ultrasonic-arduino-library/|Arduino citing of my library]]