pololu / qtr-sensors-arduino

Arduino library for the Pololu QTR reflectance sensors

Arduino library for the Pololu QTR Reflectance Sensors

Version: 4.0.0
Release date: 2019-03-15

www.pololu.com

Summary

This is a library for the Arduino IDE that helps interface with Pololu QTR reflectance sensors.

Supported platforms

This library is designed to work with the Arduino IDE versions 1.8.x or later; we have not tested it with earlier versions. This library should support any Arduino-compatible board, including the Pololu A-Star controllers.

Getting started

Hardware

The QTRSensors library supports Pololu's second-generation dimmable QTR and QTRX reflectance sensor boards, as well as older QTR sensors. Before continuing, careful reading of the QTR Reflectance Sensor Application Note is recommended.

This library also works with the reflectance sensors built into or designed for Pololu robots, such as the Zumo 32U4 Front Sensor Array. However, the dedicated libraries for those robots (e.g. the Zumo32U4 library) generally provide an interface that is specific to those sensors and is easier to use.

Software

You can use the Library Manager to install this library:

1. In the Arduino IDE, open the "Sketch" menu, select "Include Library", then "Manage Libraries...".
2. Search for "QTRSensors".
3. Click the QTRSensors entry in the list.
4. Click "Install".

If this does not work, you can manually install the library:

1. Download the latest release archive from GitHub and decompress it.
2. Rename the folder "qtr-sensors-arduino-xxxx" to "QTRSensors".
3. Drag the "QTRSensors" folder into the "libraries" directory inside your Arduino sketchbook directory. You can view your sketchbook location by opening the "File" menu and selecting "Preferences" in the Arduino IDE. If there is not already a "libraries" folder in that location, you should make the folder yourself.
4. After installing the library, restart the Arduino IDE.

Examples

Several example sketches are available that show how to use the library. You can access them from the Arduino IDE by opening the "File" menu, selecting "Examples", and then selecting "QTRSensors". If you cannot find these examples, the library was probably installed incorrectly and you should retry the installation instructions above.

Documentation

For complete documentation of this library, see the qtr-sensors-arduino documentation. If you are already on that page, see the QTRSensors class reference.

Version history

• 4.0.0 (2019-03-15): Major library rewrite: instead of a hierarchy of classes for different sensor types, the library now provides a single QTRSensors class, and instances of this class can be configured for a specific sensor type. Configuration of sensor pins and other settings is now done using more human-readable class methods instead of constructor parameters. Support for calibration using the odd/even read modes has been added.
• 3.1.0 (2018-08-08): Added support for dimmable QTR and QTRX sensors with separate control of odd/even emitter banks.
• 3.0.0 (2016-08-16): Updated library to work with the Arduino Library Manager.
• 2.1.2 (2015-12-03): Corrected readLine() behavior to work with multiple instances (thanks to Tandy Carmichael).
• 2.1.1 (2014-05-02): Minor improvements to read() behavior and whitespace cleanup.
• 2.1.0 (2013-04-18): Improved existing examples and added two new examples for printing raw values.
• 2.0.2 (2013-04-17): Made constructors initialize pointers to avoid possible problems.
• 2.0.1 (2012-09-13): Added a 200 us delay after emitter state changes to ensure sensors do not start being sampled before the LEDs turn on/off.
• 2.0.0 (2012-02-14): Initial release of library on GitHub (with Arduino 1.0 compatibility).

qtr-sensors-arduino's Issues

Question: Difference between the documented value and the value read by the sensor

On that line, the comment says that the returned value will be between 0 and 5000. It turns out that with a size 8 sensor, the reading should vary between 0 and 7000.

At least, that's the result I got with a properly calibrated size 8 sensor.

Issue reading white line on black background

I am having a issue where the readLineWhite() is not working properly. It keeps giving me values between 5000-6000 on a QTRX-13MD-RC, even though on a black line with readLineBlack() the readings are perfectly fine and gives me 0-12000.

readLineWhite() on a white line is causing issues.

Bug in QTRSensors::readLinePrivate()?

I think there might be a bug in the QTRSensors::readLinePrivate() method. The weighted average is calculated in this method by the following code:

  for (uint8_t i = 0; i < _sensorCount; i++)
  {
...
    // only average in values that are above a noise threshold
    if (value > 50)
    {
      avg += (uint32_t)value * (i * 1000);
      sum += value;
    }
  }
...
  _lastPosition = avg / sum;

The i variable starts at 0 and that 0th element will always contribute a value of 0 to avg.

Maybe something like this would work better?

  for (uint8_t i = 0; i < _sensorCount; i++)
  {
...
    // only average in values that are above a noise threshold
    if (value > 50)
    {
      avg += (uint32_t)value * ((i+1) * 1000);
      sum += value;
    }
  }
...
  _lastPosition = avg / sum - 1000;

It should still result in the same final range I think but the 0th element will always contribute to avg.

Thoughts?

Should be using virtual methods?

While looking over the code, I found this peculiar piece of code:

if (_type == QTR_RC)
{
    ((QTRSensorsRC*)this)->readPrivate(sensor_values);
    emittersOff();
    if(readMode == QTR_EMITTERS_ON_AND_OFF)
        ((QTRSensorsRC*)this)->readPrivate(off_values);
}
else
{
    ((QTRSensorsAnalog*)this)->readPrivate(sensor_values);
    emittersOff();
    if(readMode == QTR_EMITTERS_ON_AND_OFF)
        ((QTRSensorsAnalog*)this)->readPrivate(off_values);
}

It seems that the QTRSensors object keeps a _type variable to tell the code
which subclass it is, and then based on that calls either the
QTRSensorsAnalog or QTRSensorsRC version of the readPrivate method.

This kind of thing is what C++ has virtual methods for. By declaring
readPrivate as a (pure) virtual method in QTRSensors and then implementing
it in the subclasses, you can just call this->readPrivate() and the compiler
will (generate code to) find out which subclass is being used at runtime.

Or is there some reason that using virtual methods is not an option here?

Gr.

Matthijs

Suggestion for all Pololu arduino libraries

Hi @kevin-pololu,
I have a suggestion to improve your arduino library.
The new arduino IDE includes a auto update of the libraries but for that it need’s a file called “library.properties” inside the library folder. I think that it would be good to add that file to all your libraries so that users can get always the newer versions automatically. I will attach a file the I made for the QTRSensors library base on an Adafruit library, I’m not sure if it works….

name=QTRSensors
version=2.1.2
author=Pololu
maintainer= Pololu <www.pololu.com>
sentence=Driver for Pololu QTR-XX line Sensors
paragraph=Driver for Pololu QTR-XX line Sensors
category=Sensors
url=hhttps://github.com/pololu/qtr-sensors-arduino
architectures=*

Invalid library

Hello, I use Arduino 1.6.7 after adding the library QTR, this message appears : Invalid library found in Arduino \ libraries \ QT

QTRSensors::calibrateOnOrOff Min/Max Value Storage

Hi,

I was looking through your library, and I can't seem to figure out why you store the maximum value found during calibration into calibratedMinimum, and the minimum value into calibratedMaximum:

for(i=0;i<_numSensors;i++)
{
    if(min_sensor_values[i] > (*calibratedMaximum)[i])
        (*calibratedMaximum)[i] = min_sensor_values[i];
    if(max_sensor_values[i] < (*calibratedMinimum)[i])
        (*calibratedMinimum)[i] = max_sensor_values[i];
}

I keep trying to go through a step by step of how this would work, but I always end up with calibratedMinimum being larger than calibratedMaximum. Should it be:

for(i=0;i<_numSensors;i++)
{
    if(max_sensor_values[i] > (*calibratedMaximum)[i])
        (*calibratedMaximum)[i] = max_sensor_values[i];
    if(min_sensor_values[i] < (*calibratedMinimum)[i])
        (*calibratedMinimum)[i] = min_sensor_values[i];
}

This is contained in line 230 to 236 of QTRSensors.cpp.

Thanks,
Farzad

problem withe the "=" operator

Hello,
when i using this code

unsigned char pins[] = {A8,A9,A10,A11,A12,A13,A14,A15};
QTRSensorsAnalog sensors;
void setup() {
 QTRSensorsAnalog sensors = QTRSensorsAnalog(pins, 8);
 sensors.calibrate();
}

the calibraition of the Sensors wont work because the Sensor lost the value of the pins in the QTRSensor implementation.

Read and set calibration value

Feature: provide default RC timeout as a constant

It would be nice if the library provided a constant for 2500, the default RC timeout.

it does not running one function

'QTRSensorsRC' does not name a type; did you mean 'QTRSensors'?