Revision 12:5bf5a7e62c5d, committed 2018-04-13

Comitter:

dzoni

Date:

Fri Apr 13 13:42:47 2018 +0000

Parent:

11:12f9cb7d88f3

Commit message:

Documentation improvement (including code examples).

Changed in this revision

--- 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);