[tutorial] SharpIRLib


The SharpIRLib project concerns the handling of Sharp IR range finders that fall into the category of proximity sensors.

The project consists of two parts. The first one involves a process for performing a curve fitting on the sensors, or in other words, it's about finding the exact responses of the sensors along with functions that describe them. The other one is an Arduino library with the name IRRanger. IRRanger is a library for interfacing Sharp IR rangers. It allows for the update of the sensors' models, provides methods for getting the sensors' output in several forms, and has a number of other features that you can make use for a quick and easy way of getting your project started.

Curve Fitting

SharpIRLib Curve Fitting Tutorial from codebender on Vimeo.

It seems that not every Sharp IR ranger has the same exact response characteristic, and a model originating from the datasheet could be less appropriate for you. So, it might be the case that you want to improve the accuracy of your sensor, if this is critical for your application.

The thing to notice is that there might be a slight deviation between the actual response of your sensor and the one indicated on its datasheet. So, what we are going to do is evaluate that response, find a model for it, and then use that model from there on for your sensor.

Things you are going to need is your computer, a USB cable, an Arduino, a Sharp IR sensor, an object of some kind with a flat surface that you are going to cover with white paper, and a ruler to measure the distance of the object from the sensor. You will find a template for the ruler, along with all the necessary code on github.

Make the following connections.


Upload the CurveFitting sketch to your Arduino.

After you have downloaded the repository from github, extract the contents of the zip file and navigate to the curve fitting folder. There, you will find the ruler template that you will print, the data_acquisition python script that you will use to gather data from the sensor, and then there are 2 curve fitting scripts for fitting a model on those data... you can use whichever one is more convenient for you... one is a Python script, the other is a MATLAB script.

Next, take your printed ruler template, cut and stitch the pages, and place them on your desk. Position your sensor at level 0 and have the obstacle ready for the measurements.

Open the terminal, and change directory to where you have the scripts. You are going to execute the data_acquisition Python script.
Type the following command python data_acquisition.py /dev/ttyACM0 GP2D120XJ00F 1 40. /dev/ttyACM0 is the serial port of the Arduino (you will have to find yours). GP2D120XJ00F is the type of the sensor (substitute the type of your own sensor). Then, it's the size of the step between successive distances of the object (we chose it 1 cm). And the last argument is the number of measurements that will be taken per distance of the object (we chose it 60x). After the script has finished, a file datapoints.csv will have been created in your current directory.

And finally you are going to fit a model on these datapoints. Change directory to where the datapoints.csv file is.

For Python, type the following command, python curve_fitting.py GP2D120XJ00F datapoints.csv.

For MATLAB, type the following command, curve_fitting('GP2D120XJ00F','datapoints.csv').

In both cases, substitute the GP2D120XJ00F is the type of your own sensor.

Run one of the above scripts. Immediately, the parameters of your model will appear, along with a plot of the data, the model from the datasheet, and the estimated model.

But before you commit to the new model, it's a good idea to evaluate its performance first. The final choice of the model will depend on your application.

Keep reading to learn how to apply the parameters of your estimated model to your sketches.

IRRanger library

SharpIRLib IRRanger Tutorial from codebender on Vimeo.

Now we are going to introduce the IRRanger library which is an Arduino library that hides away all the details of setting up the model for your proximity sensor and provides you with a simple interface to use.

For this part, there are 2 examples, DistancefromObject and StayAway, that expose some of the functionality of the library.


Let's look at the code.

At the beginning, we include the library. Then we create an instance of the IRRanger class. We do this by providing as arguments the part code of the sensor, the pin to which we have connected the sensor's output, and optionally a value that we'll explain later.

Next, if we have calculated earlier a new model for our sensor, we have to make sure to update the model that our instance utilizes. An IRRanger instance, by default makes use of the corresponding model derived from the datasheets. So, if we want the instance to use our model instead, we can call the setModel method, with arguments, the type of our model, either a sum of exponentials or a fifth degree polynomial, and the parameters of the model.

Following that we can set the voltage reference of the A/D converter to an external voltage on the AREF pin by calling setARef with the voltage we want to use, and we can reset it to the internally generated voltage with the resetAref method. But before we mess with the voltage references, we better read the warning on this page.

Due to the nature of the sensor, its output is bound to fluctuate, and one thing we can do to cancel that variation out, is to take multiple measurements whenever we need to measure a distance. We can accomplish this by calling setRepeat with the number of measurements to be averaged. But caution here, we have to wait 50 ms for every additional measurement.

Earlier, at the point we called the constructor of the class, there was a third optional argument that we didn't comment. This value represents the position of the sensor with respect to some point of reference, and it's going to be added on every measurement. Now, why would you need that? Perhaps you have a robot and you want to get the distances of objects in front of it, not from the sensor, but rather from the center of the robot.


So, if you need to do something like that, you can provide the distance in cm of the sensor from the point of reference, either on the constructor as a third argument or you can call setPRef later.

Remember here that the library adds this value to the output of the sensor only when we are requesting a distance in some unit of length, and not when we are asking for the value of the A/D converter or the output voltage of the sensor.

Now everything is set up, and we can use our sensor.

We can call getCM to get a distance in cm, and getIN to get a distance in inches. We can ask for the sensor's output in volts, with getV, or the raw value of the A/D converter, with getRaw.

Then, there are the raw2CM and raw2IN methods that can be used in conjunction with getRaw to avoid adding the position reference of the sensor from the point of reference... if we have set that value earlier.


The library can also operate the sensor in discrete mode and have it report whether an object is far or close. The methods we can use here are three, setThreshold, isClose, and isFar.

setThreshold sets the corner distance that will designate an object as distant or nearby.

isClose returns true if a measurement is less than or equal to the threshold, and false otherwise.

isFar is the complement of isClose, namely it returns true if a measurement is greater than the threshold.

That's all folks. We hope you enjoy this project, and if you have any comments or suggestions you can contact us at girder [at] codebender [dot] cc

Sounds are from freesound.org. Schematics were based on Fritzing.