Synchronous and asynchronous library for ultrasonic distance measurement for the device HC-SR04 with error handling functionality (out of range detection, HW error detection). Main features: "echo" puls duration measurement, distance measurement from "echo" pulse duration, detection of "echo" signal malfunction, timeout detection, detection of measured values outside reliable limits (min, max)
Diff: Distance_HC_SR04.h
- Revision:
- 12:5bf5a7e62c5d
- Parent:
- 6:5beda7c318d5
--- a/Distance_HC_SR04.h Fri Mar 23 10:03:36 2018 +0000 +++ b/Distance_HC_SR04.h Fri Apr 13 13:42:47 2018 +0000 @@ -1,3 +1,13 @@ +/** + * @file Distance_HC_SR04.h + * @author Jan Tetour + * @date 21. Dec 2015 + * @brief Library for distance measurement with device HC-SR04 and similar. + * + * Synchronous and asynchronous library for ultrasonic distance measurement for the device HC-SR04 with error handling functionality (out of range detection, HW error detection). Main features: "echo" puls duration measurement, distance measurement from "echo" pulse duration, detection of "echo" signal malfunction, timeout detection, detection of measured values outside reliable limits (min, max) + * + * @see https://os.mbed.com/users/dzoni/code/Distance_HC_SR04/ + */ #ifndef MBED_DISTANCE_HC_SR04_H #define MBED_DISTANCE_HC_SR04_H @@ -9,17 +19,21 @@ #define TICKS_RANGE_MIN (150) // Minimum reliable measurement - echo pulse width in microseconds #define TRIG_PULSE_US (50) // Width of trigger pulse in microseconds -/** Definition of measurement FSM states. +/** + * @brief Definition of measurement FSM states. + * + * Measurement FSM (Finite State Machine) states definition. * - * IDLE: No activity. Ready to start measurement with trigger(). This is state after reset(). - * STARTED: Measurement started and in progress. This is state after trigger(). - * COMPLETED: Measurement succesfuly completed by falling edge of echo signal. Measured values in range. - * TIMEOUT: It was not possible to complete echo pulse width measurement in given time. Measurement cancelled. - * OUT_OF_RANGE_MIN: Measurement completed. Measured distance under reliable range. - * OUT_OF_RANGE_MAX: Measurement completed. Measured distance over reliable range. - * ERROR_SIG: Faulty value of echo signal just after trigger pulse (echo != 0). Possible HW fault. */ -typedef enum { IDLE, STARTED, COMPLETED, TIMEOUT, OUT_OF_RANGE_MIN, OUT_OF_RANGE_MAX, ERROR_SIG } Distance_HC_SR04_state; +typedef enum { + IDLE, /**< No activity. Ready to start measurement with trigger(). This is state after reset(). */ + STARTED, /**< Measurement started and in progress. This is state after trigger(). */ + COMPLETED, /**< Measurement succesfuly completed by falling edge of echo signal. Measured values in range. */ + TIMEOUT, /**< It was not possible to complete echo pulse width measurement in given time. Measurement cancelled. */ + OUT_OF_RANGE_MIN, /**< Measurement completed. Measured distance under reliable range. */ + OUT_OF_RANGE_MAX, /**< Measurement completed. Measured distance over reliable range. */ + ERROR_SIG /**< Faulty value of echo signal just after trigger pulse (echo != 0). Possible HW fault. */ +} Distance_HC_SR04_state; /** Distance_HC_SR04 class. * @@ -43,8 +57,142 @@ float getDistance(void); float getCoeff(void); void setCoeff(float coeff); + + /** + * @brief Measure (synchronous) distance of the object by reflected ultrasonic signal. + * + * Measure the distance from the object by reflected ultrasonic signal in synchronous + * (blocking) mode. In case of any error, returns 0. Error information can be retrieved via getState() method. + * + * Example of usage: + * @code + * Distance_HC_SR04 dist(PIN_TRIG, PIN_ECHO); + * float distance; + * + * while (true) { + * distance = dist.getDistance(); + * lcd.cls(); + * + * switch (dist.getState()) { + * case COMPLETED: + * lcd.printf("Dist.: %.3f", dist); + * lcd.locate(0, 1); + * lcd.printf("COMPLETED"); + * + * break; + + * case TIMEOUT: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("TIMEOUR"); + + * break; + * case ERROR_SIG: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("ERROR_SIG"); + + * break; + + * case OUT_OF_RANGE_MIN: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OUT_OF_RANGE_MIN"); + + * break; + + * case OUT_OF_RANGE_MAX: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OUT_OF_RANGE_MAX"); + + * break; + + * default: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OTHER"); + + * break; + * } + * wait_ms(100); + * } + * @endcode + * @param - + * @return Object distance in milimeters. 0 in case of error. + * @see - + * @note - Calculation can be influenced by changing _coeff via setCoeff() or Distance_HC_SR04(). + * @warning - + */ float measureDistance(void); - uint32_t measureTicks(void); + + /** + * @brief Measure (synchronous) ultrasonic signal travel time. + * + * Measure the ultrasonic signal travel time in microseconds in synchronous + * (blocking) mode. In case of any error, returns 0. Error information can be retrieved via getState() method. + * + * Example of usage: + * @code + * Distance_HC_SR04 dist(PIN_TRIG, PIN_ECHO); + * uint32_t ticks_us; + * + * while (true) { + * ticks_us = dist.measureTicks(); + * lcd.cls(); + * + * switch (dist.getState()) { + * case COMPLETED: + * lcd.printf("Dist.: %u", ticks_us); + * lcd.locate(0, 1); + * lcd.printf("COMPLETED"); + * + * break; + + * case TIMEOUT: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("TIMEOUR"); + + * break; + * case ERROR_SIG: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("ERROR_SIG"); + + * break; + + * case OUT_OF_RANGE_MIN: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OUT_OF_RANGE_MIN"); + + * break; + + * case OUT_OF_RANGE_MAX: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OUT_OF_RANGE_MAX"); + + * break; + + * default: + * lcd.printf("Dist.: ---"); + * lcd.locate(0, 1); + * lcd.printf("OTHER"); + + * break; + * } + * wait_ms(100); + * } + * @endcode + * @param - + * @return Ultrasonic signal total travel time (including reflected signal) in microseconds. 0 in case of error. + * @see - + * @note - + * @warning - + */ + uint32_t measureTicks(void); private: void _tout(void);