Arduino Libs Wiki

Arduino Libraries

Brought to you by: perrotti

HcsrArray

Authors:

Class HcsrArray

Implements a dynamic array of Hcsr sensors.

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

Public declaration:

#define hc_TimeOut 18000    // microseconds
#define hcErr_Timeout     -1
#define hcErr_Hardware    -2
#define hcErr_ArrayIsFull -3
#define hcErr_NoMemory    -4

typedef enum{centimeter=0, inch} DistUnit;

class HcsrArray
{
public:
  HcsrArray(){}
  ~HcsrArray();

  boolean begin(byte maxSensors, DistUnit unit= centimeter);
  int addHcSensor(byte triggerPin, byte echoPin);
  void patrolModeOn(uint milliseconds);
  void patrolModeOff();
  boolean run();

  int readHcDist(byte hcID, byte tries=1);
  int readHcArray(byte tries=1);
  int getLastDist();
  int getLastDist(byte hcID);
  byte lastHcID();
  byte hcCount();
  boolean isPatrolDone();
  int getMinDist();
  int getMaxDist();

protected:   
  // Override to capture
  virtual void onNextHcRead(byte hcID, int dist){}
  virtual void onPatrolDone(){}
};

How to use

Call begin() informing how many sensors you want in array and the distance unit (centimeters or inchs).
Check begin() return to make sure that the array was successfully allocated.
Add sensors to array calling addHcSensor() informing pins for trigger and echo.
To start the patrol, call patrolModeOn(). In this mode, the class will read the sensors in sequence using the time informed in milliseconds param as the interval between each read. patrolModeOff() disable patrol mode.
Call run() at least once per loop to class check the time and read a sensor if needed. Check the run() return to see if a new read has been made. If yes, the read value can be obtained calling getLastDist().

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.

boolean begin(byte maxSensors, DistUnit unit= centimeter)

Call before any other method. This method alloc the array, check the return to make sure that the array was successfully allocated.

maxSensors: How many sensors in the array.
unit: Distance unit for readings (centimeter or inch).
return: true if array was successfully allocated, false if not.

byte addHcSensor(byte triggerPin, byte echoPin)

Add sensor on array. 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.
return: The sensor's ID or negative value if any error occurred.

void patrolModeOn(uint milliseconds)

Start patrol mode. The sensors are read in sequence, the milliseconds parameter inform the interval between readings.
Whenever a reading is made in patrol mode, the event onNextHcRead() is triggered. When a round is completed the class triggers the event onPatrolDone()

milliseconds: interval between readings.

void patrolModeOff()

Stop patrol mode.

boolean run()

Call once per loop. On patrol mode this method check the time and make new read if needed. Also trigger the events onNextHcRead() and onPatrolDone().

return: true if a new read was made, false if not.

int readHcDist(byte hcID, byte tries=1)

Read the sensor indicate by hcID and return the distance. This method dont trigger events.

hcID: ID of sensor
tries: Number of tries if read fails.
return: Distance readed or negative value if read fails.

int readHcArray(byte tries=1)

Read all the sensors in array. This method dont trigger events.

tries: Number of tries if read fails.
return: Number of sensors readed successfully.

int getLastDist()

Return the last distance readed.

return: last distance readed.

int getLastDist(byte hcID)

Return the last distance readed from sensor indicated by hcID.

hcID: ID of sensor
return: last distance readed from sensor indicated.

byte lastHcID()

Return the ID of last sensor readed.

return: ID of last sensor readed.

byte hcCount()

Return the number of sensors in array.

return: number of sensors in array.

boolean isPatrolDone()

Call to check if a patrol round has been completed.

return: true if a patrol round has been completed, false if not.

int getMinDist()

Returns the shortest distance read. This method does not re-read sensors, uses readings previously made. To get the sensor ID with the shortest distance, use the method lastHcID().

return: the shortest distance read.

int getMaxDist()

Returns the largest distance read. This method does not re-read sensors, uses readings previously made. To get the sensor ID with the largest distance, use the method lastHcID().

return: the largest distance read.

Wiki: Hcsr04
Wiki: HcsrAuto
Wiki: Home