HcsrAuto

Class HcsrAuto

Driver for ultrasonic distance sensors compatibles with HCSR-04 module.
Automatically reads sensor in indicated time lapse.
Returns the distance in centimeters or inches.
Allows to operate the sensor with a single pin in arduino.

• File: pHcsr04.h
• Dependences: pGlobals.h
• See too: [Hcsr04], [HcsrArray]
• Wiki em português: Classe HcsrAuto
• Sobre o módulo HC-SR04

Public declarations:

#define hc_TimeOut 18000  // microseconds
#define hcErr_Timeout     -1
#define hcErr_Hardware    -2

typedef enum{centimeter=0, inch} DistUnit;

class HcsrAuto: public Hcsr04{
public:
  int lastDist;

  HcsrAuto():Hcsr04(){}

  void begin(byte triggerPin, byte echoPin, DistUnit unit= centimeter);
  void hcStart(uint milliseconds);
  void hcStop();
  boolean run();

  // From Hcsr04
  int hcDist(byte tries=1);
  long ultraSonicRead();

protected:
  virtual void onHcRead(int dist){}
};

---

How to use

Call begin() informing pins for trigger and echo and selecting the distance unit (centimeters or inchs).
It is possible to indicate the same arduino pin for trigger and echo, so it is necessary to install a pulldown resistor between the pin and GND.
To start the readings, call hcStart() informing the time lapse between reads. Its possible read sensor at any time by calling hcDist().
Call run() at least once per loop to check the time and read the sensor if needed. Check the run() return to see if a new read has been made. If yes, the read value can be obtained from the lastDist public field.
hcStop() stop's the automatic readings.
Whenever an automatic reading is made, the onHcRead() event is triggered. You can capture this event through a descending class of HcsrAuto.
TimeOut
If the echo does not return within the time set by hc_TimeOut define, the reading fails. In practice this value establishes the maximum distance that will be measured by the sensor. Manufacturers promise that the sensor is capable of measuring up to 4 meters, but this is rarely possible, especially in small robots. Usually the sensor is close to the ground which in itself limits the maximum distance. Therefore, it is better to set the timeout to the value that can actually be read, so the reading function returns faster and the program flows better.

---

void begin(byte triggerPin, byte echoPin, DistUnit unit= centimeter);

Sensor params. Call before any other method. You can use the same Arduino pin for trigger and echo. For this you need to install a pull-down resistor between arduino pin and GND. 100 Kohms is a good value. The class suport this situation and performs the necessary processing. Just indicate the same pin for triggerPin and echoPin params.

• triggerPin: Trigger pin.
• echoPin: Echo pin.
• unit: Distance unit for hcDist() method readings (centimeter or inch)

---

void hcStart(uint milliseconds);

Start automatic readings.

• milliseconds: time lapse between readings

---

void hcStop();

Stop automatic readings.

---

boolean run();

Call once per loop. Check the time and read sensor if needed. Trigg onHcRead() event when a new read is available.
Also update lastDist public field.

• return: true if a new read is available, false if not.

---

virtual void onHcRead(int dist){}

Event triggered when a new read is available. You can capture this event in descendent class.

• dist: distance or negative value if read fails.