o2: Added O2 sensor C source

Added the C source for the O2 sensor with necessary changes to cmake,
examples, docs.

    * Renamed all files with groveo2 to o2
    * Replaced all instances of groveo2 with o2
    * Added C source for o2 sensor
    * Updated all cmake files
    * Added C example for o2 sensor

Signed-off-by: Noel Eck <noel.eck@intel.com>

src/o2/CMakeLists.txt

@@ -0,0 +1,8 @@
+upm_mixed_module_init (NAME o2
+    DESCRIPTION "upm O2 oxygen concentration sensor module"
+    C_HDR o2.h
+    C_SRC o2.c
+    CPP_HDR o2.hpp
+    CPP_SRC o2.cxx
+    FTI_SRC o2_fti.c
+    REQUIRES mraa)

src/o2/javaupm_o2.i

@@ -0,0 +1,19 @@
+%module javaupm_o2
+%include "../upm.i"
+
+%{
+    #include "o2.hpp"
+%}
+
+%include "o2.hpp"
+
+%pragma(java) jniclasscode=%{
+    static {
+        try {
+            System.loadLibrary("javaupm_o2");
+        } catch (UnsatisfiedLinkError e) {
+            System.err.println("Native code library failed to load. \n" + e);
+            System.exit(1);
+        }
+    }
+%}

src/o2/jsupm_o2.i

@@ -0,0 +1,8 @@
+%module jsupm_o2
+%include "../upm.i"
+
+%{
+    #include "o2.hpp"
+%}
+
+%include "o2.hpp"

src/o2/o2.c

@@ -0,0 +1,131 @@
+/*
+ * Author:
+ * Copyright (c) 2015 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include <string.h>
+#include <stdlib.h>
+
+#include "o2.h"
+o2_context o2_init(int16_t pin)
+{
+    o2_context dev = (o2_context)malloc(sizeof(struct _o2_context));
+
+    if(dev == NULL) return NULL;
+
+    /* Init aio pin */
+    dev->aio = mraa_aio_init(pin);
+    if(dev->aio == NULL) {
+        free(dev);
+        return NULL;
+    }
+
+    /* Set defaults */
+    dev->m_aRef = 5.0;
+    dev->m_offset = 0.0;
+    dev->m_scale = 1.0;
+
+    return dev;
+}
+
+void o2_close(o2_context dev)
+{
+    mraa_aio_close(dev->aio);
+    free(dev);
+}
+
+upm_result_t o2_set_aref(const o2_context dev, float aref)
+{
+    dev->m_aRef = aref;
+    return UPM_SUCCESS;
+}
+
+float o2_get_aref(const o2_context dev)
+{
+    return dev->m_aRef;
+}
+
+upm_result_t o2_set_offset(const o2_context dev, float offset)
+{
+    dev->m_offset = offset;
+    return UPM_SUCCESS;
+}
+
+float o2_get_offset(const o2_context dev)
+{
+    return dev->m_offset;
+}
+
+upm_result_t o2_set_scale(const o2_context dev, float scale)
+{
+    dev->m_scale = scale;
+    return UPM_SUCCESS;
+}
+
+float o2_get_scale(const o2_context dev)
+{
+    return dev->m_scale;
+}
+
+upm_result_t o2_get_counts(const o2_context dev, int *value)
+{
+    /* Read counts */
+    *value = mraa_aio_read(dev->aio);
+    if (*value < 0) return UPM_ERROR_OPERATION_FAILED;
+    return UPM_SUCCESS;
+}
+
+upm_result_t o2_get_raw_volts(const o2_context dev, float *value)
+{
+    /* Read normalized adc value */
+    *value = mraa_aio_read_float(dev->aio);
+    if (*value < 0.0) return UPM_ERROR_OPERATION_FAILED;
+
+    /* Convert normalized value to voltage via aRef */
+    *value *= dev->m_aRef;
+
+    return UPM_SUCCESS;
+}
+
+upm_result_t o2_get_value(const o2_context dev, float *value)
+{
+    /* Read normalized value */
+    *value = mraa_aio_read_float(dev->aio);
+    if (*value < 0.0)
+        return UPM_ERROR_OPERATION_FAILED;
+
+    /* Apply raw scale */
+    *value *= dev->m_scale;
+
+    /* Convert to %oxygen
+       Datasheet for grove o2 shows a linear response for the sensor.  Assuming
+       20.5% oxygen @ 25 celsius, with an gain = 1 + 12k/100 = 121, a
+       dynamic range of 0->25% oxygen, and opamp rails of 0->3.3v (the grove o2
+       sensor uses a high-accuracy 3.3v regulator),
+     */
+    *value *= 25 * dev->m_aRef/3.3;
+
+    *value += dev->m_offset;
+
+    return UPM_SUCCESS;
+}
+

src/o2/o2.cxx

@@ -0,0 +1,56 @@
+/*
+ * Author: Zion Orent <zorent@ics.com>
+ * Copyright (c) 2015 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include <iostream>
+#include <string>
+#include <stdexcept>
+
+#include "o2.hpp"
+
+using namespace upm;
+using namespace std;
+
+O2::O2(int pin)
+{
+    if ( !(m_aio = mraa_aio_init(pin)) )
+    {
+      throw std::invalid_argument(std::string(__FUNCTION__) +
+                                  ": mraa_aio_init() failed, invalid pin?");
+      return;
+    }
+}
+
+O2::~O2()
+{
+  mraa_aio_close(m_aio);
+}
+
+float O2::voltageValue()
+{
+	int val = mraa_aio_read(m_aio);
+	if (val == -1) return -1.0f;
+	float sensorVoltage = (val/1024.0) * 5.0;
+	sensorVoltage = (sensorVoltage/201.0) * 10000.0;
+	return sensorVoltage;
+}

src/o2/o2.h

@@ -0,0 +1,135 @@
+/*
+ * Author:
+ * Copyright (c) 2015 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#pragma once
+
+#include "upm.h"
+#include "mraa/aio.h"
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * device context
+ */
+typedef struct _o2_context {
+    /* mraa aio pin context */
+    mraa_aio_context aio;
+    /* Analog voltage reference */
+    float m_aRef;
+    /* Scale */
+    float m_scale;
+    /* Offset in sensor units */
+    float m_offset;
+} *o2_context;
+
+/**
+ * Initialize analog sensor
+ * @param pin is Analog pin
+ * @return sensor context as void pointer
+ */
+o2_context o2_init(int16_t pin);
+
+/**
+ * Analog sensor destructor
+ * @param sensor context pointer deallocate memory
+ */
+void o2_close(o2_context dev);
+
+/**
+ * Set sensor adc vref.
+ * @param dev sensor context pointer
+ * @param aref Voltage reference routed to ADC ref pin
+ * @return Function result code
+ */
+upm_result_t o2_set_aref(const o2_context dev, float aref);
+
+/**
+ * Get sensor adc vref
+ * @param dev sensor context pointer
+ * @return Current adc vref
+ */
+float o2_get_aref(const o2_context dev);
+
+/**
+ * Set sensor offset.  This offset is applied to the return value:
+ *     counts = counts * scale + offset * scale
+ * @param dev sensor context pointer
+ * @param offset count offset value used
+ * @return Function result code
+ */
+upm_result_t o2_set_offset(const o2_context dev, float offset);
+
+/**
+ * Get sensor offset
+ * @param dev sensor context pointer
+ * @return Current sensor offset
+ */
+float o2_get_offset(const o2_context dev);
+
+/**
+ * Set sensor scale.  This scale is applied to the return value:
+ *     counts = counts * scale + offset * scale
+ * @param dev sensor context pointer
+ * @param scale count scale value used
+ * @return Function result code
+ */
+upm_result_t o2_set_scale(const o2_context dev, float scale);
+
+/**
+ * Get sensor scale
+ * @param dev sensor context pointer
+ * @return Current sensor scale
+ */
+float o2_get_scale(const o2_context dev);
+
+/**
+ * Read raw adc counts from sensor
+ * @param dev sensor context pointer
+ * @param *value Raw adc value
+ * @return Function result code
+ */
+upm_result_t o2_get_counts(const o2_context dev, int *value);
+
+/**
+ * Read voltage from sensor
+ * @param dev sensor context pointer
+ * @param *value Voltage (v)
+ * @return Function result code
+ */
+upm_result_t o2_get_raw_volts(const o2_context dev, float *value);
+
+/**
+ * Read value from sensor
+ * @param dev sensor context pointer
+ * @param *value O2 percentage
+ * @return Function result code
+ */
+upm_result_t o2_get_value(const o2_context dev, float *value);
+
+#ifdef __cplusplus
+}
+#endif

src/o2/o2.hpp

@@ -0,0 +1,73 @@
+/*
+ * Author: Zion Orent <zorent@ics.com>
+ * Copyright (c) 2015 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#pragma once
+
+#include <string>
+#include <mraa/aio.h>
+
+namespace upm {
+  /**
+   * @brief Grove O2 Oxygen Gas Sensor library
+   * @defgroup o2 libupm-o2
+   * @ingroup seeed analog gaseous
+   */
+
+  /**
+   * @library o2
+   * @sensor o2
+   * @comname Grove O2 Sensor
+   * @type gaseous
+   * @man seeed
+   * @con analog
+   *
+   * @brief API for the Grove O2 Oxygen Gas Sensor
+   *
+   * The Grove O2 Oxygen Gas sensor measures the oxygen concentration in the air
+   *
+   * @image html o2.jpg    
+   * @snippet o2.cxx Interesting
+   */
+  class O2 {
+  public:
+    /**
+     * Grove O2 Oxygen Gas sensor constructor
+     *
+     * @param pin Analog pin to use
+     */
+    O2(int pin);
+    /**
+     * O2 destructor
+     */
+    ~O2();
+    /**
+     * Measures O2 from the sensor
+     *
+     * @return Oxygen concentration as voltage
+     */
+    float voltageValue();
+
+  private:
+    mraa_aio_context m_aio;
+  };
+}

src/o2/o2_fti.c

@@ -0,0 +1,116 @@
+/*
+ * Author:
+ * Copyright (c) 2015 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#include "o2.h"
+#include "upm_fti.h"
+#include "fti/upm_sensor.h"
+#include "fti/upm_raw.h"
+
+/** 
+ * This file implements the Function Table Interface (FTI) for this sensor
+ */
+
+const char upm_o2_name[] = "O2";
+const char upm_o2_description[] = "Analog oxygen sensor";
+const upm_protocol_t upm_o2_protocol[] = {UPM_ANALOG};
+const upm_sensor_t upm_o2_category[] = {UPM_RAW};
+
+// forward declarations
+const void* upm_o2_get_ft(upm_sensor_t sensor_type);
+void* upm_o2_init_str(const char* protocol, const char* params);
+void upm_o2_close(void* dev);
+const upm_sensor_descriptor_t upm_o2_get_descriptor();
+upm_result_t upm_o2_set_offset(const void* dev, float offset);
+upm_result_t upm_o2_set_scale(const void* dev, float scale);
+upm_result_t upm_o2_get_value(const void* dev, float *value);
+
+/* This sensor implementes 2 function tables */
+/* 1. Generic base function table */
+static const upm_sensor_ft ft_gen =
+{
+    .upm_sensor_init_name = &upm_o2_init_str,
+    .upm_sensor_close = &upm_o2_close,
+    .upm_sensor_get_descriptor = &upm_o2_get_descriptor
+};
+
+/* 2. RAW function table */
+static const upm_raw_ft ft_raw =
+{
+    .upm_raw_set_offset = &upm_o2_set_offset,
+    .upm_raw_set_scale = &upm_o2_set_scale,
+    .upm_raw_get_value = &upm_o2_get_value
+};
+
+const void* upm_o2_get_ft(upm_sensor_t sensor_type)
+{
+    switch(sensor_type)
+    {
+        case UPM_SENSOR:
+            return &ft_gen;
+        case UPM_RAW:
+            return &ft_raw;
+        default:
+            return NULL;
+    }
+}
+
+void* upm_o2_init_str(const char* protocol, const char* params)
+{
+    fprintf(stderr, "String initialization - not implemented, using ain0: %s\n", __FILE__);
+    return o2_init(0);
+}
+
+void upm_o2_close(void* dev)
+{
+    o2_close((o2_context)dev);
+}
+
+const upm_sensor_descriptor_t upm_o2_get_descriptor()
+{
+    /* Fill in the descriptor */
+    upm_sensor_descriptor_t usd;
+    usd.name = upm_o2_name;
+    usd.description = upm_o2_description;
+    usd.protocol_size = 1;
+    usd.protocol = upm_o2_protocol;
+    usd.category_size = 1;
+    usd.category = upm_o2_category;
+
+    return usd;
+}
+
+upm_result_t upm_o2_set_offset(const void* dev, float offset)
+{
+    return o2_set_offset((o2_context)dev, offset);
+}
+
+upm_result_t upm_o2_set_scale(const void* dev, float scale)
+{
+    return o2_set_scale((o2_context)dev, scale);
+}
+
+upm_result_t upm_o2_get_value(const void* dev, float *value)
+{
+    return o2_get_value((o2_context)dev, value);
+}

src/o2/pyupm_o2.i

@@ -0,0 +1,11 @@
+// Include doxygen-generated documentation
+%include "pyupm_doxy2swig.i"
+%module pyupm_o2
+%include "../upm.i"
+
+%feature("autodoc", "3");
+
+%include "o2.hpp"
+%{
+    #include "o2.hpp"
+%}