From ff2ff5d008f33dd00a8e417e58712f3d7743fec7 Mon Sep 17 00:00:00 2001
From: Hauke Petersen <hauke.petersen@fu-berlin.de>
Date: Fri, 12 Feb 2016 17:23:06 +0100
Subject: [PATCH] drivers/srf02: expose trigger and read to API

---
 drivers/include/srf02.h | 36 ++++++++++++++++++++++++++++++++++--
 drivers/srf02/srf02.c   | 25 +++++++++++++++----------
 2 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/drivers/include/srf02.h b/drivers/include/srf02.h
index 275ac48637..055f855be4 100644
--- a/drivers/include/srf02.h
+++ b/drivers/include/srf02.h
@@ -34,7 +34,12 @@ extern "C" {
 /**
  * @brief   Default I2C address of SRF02 sensors
  */
-#define SRF02_DEFAULT_ADDR                  (0xe0)
+#define SRF02_DEFAULT_ADDR      (0xe0)      /* 224 decimal */
+
+/**
+ * @brief   The datasheet tells us, that ranging takes 70ms
+ */
+#define SRF02_RANGE_DELAY       (70000U)
 
 /**
  * @brief   Device descriptor for SRF02 sensors
@@ -69,11 +74,38 @@ typedef enum {
 int srf02_init(srf02_t *dev, i2c_t i2c, uint8_t addr);
 
 /**
- * @brief   Get the distance measured from the SRF02 ultrasonic sensor
+ * @brief   Trigger a new measurement
+ *
+ * This function triggers a new ranging operation. After triggering this
+ * operation, you have to wait at least 70ms for the result to be ready.
  *
  * The result of the ranging operation is returned in inches, centimeters or
  * microseconds - depending on the given @p mode parameter.
  *
+ * @param[in] dev           device to trigger
+ * @param[in] mode          there are three real ranging modes, which return
+ *                          the result in inches, centimeters or microseconds.
+ *                          Another set of three fake ranging modes do the same
+ *                          but without transmitting the burst
+ */
+void srf02_trigger(srf02_t *dev, srf02_mode_t mode);
+
+/**
+ * @brief    Read the results of the last ranging operation
+ *
+ * @param[in] dev           device to read from
+ *
+ * @return  result of the last ranging operation, meaning depends on the mode
+ *          parameter given to the srf02_trigger function
+ */
+uint16_t srf02_read(srf02_t *dev);
+
+/**
+ * @brief   Get the distance measured from the SRF02 ultrasonic sensor
+ *
+ * This function combines the srf02_trigger and the srf02_read functions for
+ * simplified usage in simple (single sensor) setups.
+ *
  * @param[in] dev           device descriptor of an SRF02 sensor
  * @param[in] mode          there are three real ranging modes, which return
  *                          the result in inches, centimeters or microseconds.
diff --git a/drivers/srf02/srf02.c b/drivers/srf02/srf02.c
index d357851e0f..66e1f1a950 100644
--- a/drivers/srf02/srf02.c
+++ b/drivers/srf02/srf02.c
@@ -31,11 +31,6 @@
 #define ENABLE_DEBUG        (0)
 #include "debug.h"
 
-/**
- * @brief   The datasheet tells us, that ranging takes 70ms
- */
-#define RANGE_DELAY         (70000U)
-
 /**
  * @brief   Per default use normal speed on the I2C bus
  */
@@ -90,18 +85,18 @@ int srf02_init(srf02_t *dev, i2c_t i2c, uint8_t addr)
     return 0;
 }
 
-uint16_t srf02_get_distance(srf02_t *dev, srf02_mode_t mode)
+void srf02_trigger(srf02_t *dev, srf02_mode_t mode)
 {
-    char res[2];
-
     /* trigger a new measurement by writing the mode to the CMD register */
     DEBUG("[srf02] trigger new reading\n");
     i2c_acquire(dev->i2c);
     i2c_write_reg(dev->i2c, dev->addr, REG_CMD, mode);
     i2c_release(dev->i2c);
+}
 
-    /* give the sensor the required time for sampling */
-    xtimer_usleep(RANGE_DELAY);
+uint16_t srf02_read(srf02_t *dev)
+{
+    char res[2];
 
     /* read the results */
     i2c_acquire(dev->i2c);
@@ -113,6 +108,16 @@ uint16_t srf02_get_distance(srf02_t *dev, srf02_mode_t mode)
     return ((((uint16_t)res[0]) << 8) | (res[1] & 0xff));
 }
 
+uint16_t srf02_get_distance(srf02_t *dev, srf02_mode_t mode)
+{
+    /* trigger a new reading */
+    srf02_trigger(dev, mode);
+    /* give the sensor the required time for sampling */
+    xtimer_usleep(SRF02_RANGE_DELAY);
+    /* get the results */
+    return srf02_read(dev);
+}
+
 void srf02_set_addr(srf02_t *dev, uint8_t new_addr)
 {
     /* get access to the bus */