groveultrasonic: made a few changes to code, example and documentation

Signed-off-by: Mihai Tudor Panu <mihai.tudor.panu@intel.com>

examples/c++/groveultrasonic.cxx

@@ -32,13 +32,13 @@
 #include <sys/time.h>
 
 upm::GroveUltraSonic *sonar = NULL;
+bool running = true;
 
 void
 sig_handler(int signo)
 {
-    printf("got signal\n");
     if (signo == SIGINT) {
-      sonar->m_doWork = 1;
+      running = false;
     }
 }
 
@@ -49,10 +49,14 @@ main(int argc, char **argv)
 //! [Interesting]
   // upm::GroveUltraSonic *sonar = NULL;
   sonar = new upm::GroveUltraSonic(2);
-  printf("width = %d\n", sonar->getDistance());
-  delete sonar;
+  while(running) {
+    int width = sonar->getDistance();
+    printf("Echo width = %d\n", width);
+    printf("Distance inches = %f.2\n\n", width/148.0);
+    sleep(3);
+  }
 //! [Interesting]
   printf("exiting application\n");
-
+  delete sonar;
   return 0;
 }

src/groveultrasonic/groveultrasonic.cxx

@@ -69,15 +69,15 @@ GroveUltraSonic::getDistance () {
     mraa_gpio_write(m_pinCtx, LOW);
 
     // wait for the pulse,
-    m_doWork = 0;
+    m_doWork = true;
     m_InterruptCounter = 0;
     mraa_gpio_dir(m_pinCtx, MRAA_GPIO_IN);
 
     // though do not wait over 25 [ms].
     int timer = 0;
-    while (!m_doWork && timer++ < 5) {
+    while (m_doWork && timer++ < 5) {
         // in 25 [ms], sound travels 25000 / 29 / 2 = 431 [cm],
-        // which is more than 400 [cm], the max distance mesurable with this sensor.
+        // which is more than 400 [cm], the max distance measurable with this sensor.
         usleep(5 * 1000); // 5 [ms]
     }
 
@@ -97,7 +97,7 @@ void
 GroveUltraSonic::ackEdgeDetected () {
     if (++m_InterruptCounter % 2 == 0) {
         gettimeofday(&m_FallingTimeStamp, NULL);
-        m_doWork = 1;
+        m_doWork = false;
     } else {
         gettimeofday(&m_RisingTimeStamp, NULL);
     }

src/groveultrasonic/groveultrasonic.h

@@ -33,27 +33,36 @@
 #define HIGH                   1
 #define LOW                    0
 
-#define MAX_PERIOD             7968
-#define TRIGGER_PULSE          10
-
 namespace upm {
 
 /**
  * @brief Grove ultrasonic sensor library
  * @defgroup groveultrasonic libupm-groveultrasonic
+ * @ingroup grove gpio sound
  */
 
 /**
- * @brief C++ API for Grove ultrasonic ranging component
+ * @library groveultrasonic
+ * @sensor groveultrasonic
+ * @comname Grove Ultrasonic Ranger
+ * @type sound
+ * @man grove
+ * @con gpio
  *
- * This file defines the GroveUltraSonic C++ interface for libgroveultrasonic
+ * @brief API for Grove Ultrasonic Ranger
  *
- * @ingroup groveultrasonic gpio
+ * This Grove Ultrasonic sensor is a non-contact distance measurement module
+ * which is compatible with the Grove system. It is designed for easy modular
+ * project usage with industrial performance. Detection ranges from 3 cm (1.2")
+ * to 4 m (13'1.5") and works best when the object is within a 30 degree angle
+ * relative to the sensor.
+ *
+ * @snippet groveultrasonic.cxx Interesting
  */
 class GroveUltraSonic {
     public:
         /**
-         * Instanciates a GroveUltraSonic object
+         * Instantiates a GroveUltraSonic object
          *
          * @param pin pin for triggering the sensor for distance and for receiving pulse response
          */
@@ -65,7 +74,9 @@ class GroveUltraSonic {
         ~GroveUltraSonic ();
 
         /**
-         * Get the distance from the sensor.
+         * Returns the echo's pulse width from the sensor in microseconds.
+         * Divide by 58 to convert distance to centimetres. 
+         * Divide by 148 to convert distance to inches.
          */
         int getDistance ();
 
@@ -78,24 +89,26 @@ class GroveUltraSonic {
         }
 
         /**
-         * ISR for the pulse signal
+         * Returns true while the sensor is busy waiting for the echo pulse
          */
-        static void signalISR(void *ctx);
-
-        /**
-         * Flag to controll blocking function while waiting for falling edge interrupt
-         */
-        uint8_t m_doWork;
+        bool working()
+        {
+            return m_doWork;
+        }
 
     private:
+        bool m_doWork; /* Flag to control blocking function while waiting for falling edge interrupt */
         mraa_gpio_context m_pinCtx;
-
         uint8_t m_InterruptCounter;
         struct timeval m_RisingTimeStamp;
         struct timeval m_FallingTimeStamp;
-
         std::string m_name;
 
+        /**
+         * ISR for the pulse signal
+         */
+        static void signalISR(void *ctx);
+
         /**
          * On each interrupt this function will detect if the interrupt
          * was falling edge or rising.

src/groveultrasonic/javaupm_groveultrasonic.i

@@ -0,0 +1,10 @@
+%module javaupm_groveultrasonic
+%include "../upm.i"
+
+%ignore signalISR;
+
+%{
+    #include "groveultrasonic.h"
+%}
+
+%include "groveultrasonic.h"