Merge pull request #43 from NET-BYU/dev

Dev

lib/Adafruit_Sensor/README.md

@@ -0,0 +1,221 @@
+# Adafruit Unified Sensor Driver #
+
+Many small embedded systems exist to collect data from sensors, analyse the data, and either take an appropriate action or send that sensor data to another system for processing.
+
+One of the many challenges of embedded systems design is the fact that parts you used today may be out of production tomorrow, or system requirements may change and you may need to choose a different sensor down the road.
+
+Creating new drivers is a relatively easy task, but integrating them into existing systems is both error prone and time consuming since sensors rarely use the exact same units of measurement.
+
+By reducing all data to a single **sensors\_event\_t** 'type' and settling on specific, **standardised SI units** for each sensor family the same sensor types return values that are comparable with any other similar sensor.  This enables you to switch sensor models with very little impact on the rest of the system, which can help mitigate some of the risks and problems of sensor availability and code reuse.
+
+The unified sensor abstraction layer is also useful for data-logging and data-transmission since you only have one well-known type to log or transmit over the air or wire.
+
+## Unified Sensor Drivers ##
+
+The following drivers are based on the Adafruit Unified Sensor Driver:
+
+**Accelerometers**
+  - [Adafruit\_ADXL345](https://github.com/adafruit/Adafruit_ADXL345)
+  - [Adafruit\_LSM303DLHC](https://github.com/adafruit/Adafruit_LSM303DLHC)
+  - [Adafruit\_MMA8451\_Library](https://github.com/adafruit/Adafruit_MMA8451_Library)
+
+**Gyroscope**
+  - [Adafruit\_L3GD20\_U](https://github.com/adafruit/Adafruit_L3GD20_U)
+
+**Light**
+  - [Adafruit\_TSL2561](https://github.com/adafruit/Adafruit_TSL2561)
+  - [Adafruit\_TSL2591\_Library](https://github.com/adafruit/Adafruit_TSL2591_Library)
+
+**Magnetometers**
+  - [Adafruit\_LSM303DLHC](https://github.com/adafruit/Adafruit_LSM303DLHC)
+  - [Adafruit\_HMC5883\_Unified](https://github.com/adafruit/Adafruit_HMC5883_Unified)
+
+**Barometric Pressure**
+  - [Adafruit\_BMP085\_Unified](https://github.com/adafruit/Adafruit_BMP085_Unified)
+  - [Adafruit\_BMP183\_Unified\_Library](https://github.com/adafruit/Adafruit_BMP183_Unified_Library)
+
+**Humidity & Temperature**
+  - [DHT-sensor-library](https://github.com/adafruit/DHT-sensor-library)
+
+**Orientation**
+ - [Adafruit_BNO055](https://github.com/adafruit/Adafruit_BNO055)
+
+## How Does it Work? ##
+
+Any driver that supports the Adafruit unified sensor abstraction layer will implement the Adafruit\_Sensor base class.  There are two main typedefs and one enum defined in Adafruit_Sensor.h that are used to 'abstract' away the sensor details and values:
+
+**Sensor Types (sensors\_type\_t)**
+
+These pre-defined sensor types are used to properly handle the two related typedefs below, and allows us determine what types of units the sensor uses, etc.
+
+```
+/** Sensor types */
+typedef enum
+{
+  SENSOR_TYPE_ACCELEROMETER         = (1),
+  SENSOR_TYPE_MAGNETIC_FIELD        = (2),
+  SENSOR_TYPE_ORIENTATION           = (3),
+  SENSOR_TYPE_GYROSCOPE             = (4),
+  SENSOR_TYPE_LIGHT                 = (5),
+  SENSOR_TYPE_PRESSURE              = (6),
+  SENSOR_TYPE_PROXIMITY             = (8),
+  SENSOR_TYPE_GRAVITY               = (9),
+  SENSOR_TYPE_LINEAR_ACCELERATION   = (10),
+  SENSOR_TYPE_ROTATION_VECTOR       = (11),
+  SENSOR_TYPE_RELATIVE_HUMIDITY     = (12),
+  SENSOR_TYPE_AMBIENT_TEMPERATURE   = (13),
+  SENSOR_TYPE_VOLTAGE               = (15),
+  SENSOR_TYPE_CURRENT               = (16),
+  SENSOR_TYPE_COLOR                 = (17)
+} sensors_type_t;
+```
+
+**Sensor Details (sensor\_t)**
+
+This typedef describes the specific capabilities of this sensor, and allows us to know what sensor we are using beneath the abstraction layer.
+
+```
+/* Sensor details (40 bytes) */
+/** struct sensor_s is used to describe basic information about a specific sensor. */
+typedef struct
+{
+    char     name[12];
+    int32_t  version;
+    int32_t  sensor_id;
+    int32_t  type;
+    float    max_value;
+    float    min_value;
+    float    resolution;
+    int32_t  min_delay;
+} sensor_t;
+```
+
+The individual fields are intended to be used as follows:
+
+- **name**: The sensor name or ID, up to a maximum of twelve characters (ex. "MPL115A2")
+- **version**: The version of the sensor HW and the driver to allow us to differentiate versions of the board or driver
+- **sensor\_id**: A unique sensor identifier that is used to differentiate this specific sensor instance from any others that are present on the system or in the sensor network
+- **type**: The sensor type, based on **sensors\_type\_t** in sensors.h
+- **max\_value**: The maximum value that this sensor can return (in the appropriate SI unit)
+- **min\_value**: The minimum value that this sensor can return (in the appropriate SI unit)
+- **resolution**: The smallest difference between two values that this sensor can report (in the appropriate SI unit)
+- **min\_delay**: The minimum delay in microseconds between two sensor events, or '0' if there is no constant sensor rate
+
+**Sensor Data/Events (sensors\_event\_t)**
+
+This typedef is used to return sensor data from any sensor supported by the abstraction layer, using standard SI units and scales.
+
+```
+/* Sensor event (36 bytes) */
+/** struct sensor_event_s is used to provide a single sensor event in a common format. */
+typedef struct
+{
+    int32_t version;
+    int32_t sensor_id;
+    int32_t type;
+    int32_t reserved0;
+    int32_t timestamp;
+    union
+    {
+        float           data[4];
+        sensors_vec_t   acceleration;
+        sensors_vec_t   magnetic;
+        sensors_vec_t   orientation;
+        sensors_vec_t   gyro;
+        float           temperature;
+        float           distance;
+        float           light;
+        float           pressure;
+        float           relative_humidity;
+        float           current;
+        float           voltage;
+        sensors_color_t color;
+    };
+} sensors_event_t;
+```
+It includes the following fields:
+
+- **version**: Contain 'sizeof(sensors\_event\_t)' to identify which version of the API we're using in case this changes in the future
+- **sensor\_id**: A unique sensor identifier that is used to differentiate this specific sensor instance from any others that are present on the system or in the sensor network (must match the sensor\_id value in the corresponding sensor\_t enum above!)
+- **type**: the sensor type, based on **sensors\_type\_t** in sensors.h
+- **timestamp**: time in milliseconds when the sensor value was read
+- **data[4]**: An array of four 32-bit values that allows us to encapsulate any type of sensor data via a simple union (further described below)
+
+**Required Functions**
+
+In addition to the two standard types and the sensor type enum, all drivers based on Adafruit_Sensor must also implement the following two functions:
+
+```
+bool getEvent(sensors_event_t*);
+```
+Calling this function will populate the supplied sensors\_event\_t reference with the latest available sensor data.  You should call this function as often as you want to update your data.
+
+```
+void getSensor(sensor_t*);
+```
+Calling this function will provide some basic information about the sensor (the sensor name, driver version, min and max values, etc.
+
+**Standardised SI values for sensors\_event\_t**
+
+A key part of the abstraction layer is the standardisation of values on SI units of a particular scale, which is accomplished via the data[4] union in sensors\_event\_t above.  This 16 byte union includes fields for each main sensor type, and uses the following SI units and scales:
+
+- **acceleration**: values are in **meter per second per second** (m/s^2)
+- **magnetic**: values are in **micro-Tesla** (uT)
+- **orientation**: values are in **degrees**
+- **gyro**: values are in **rad/s**
+- **temperature**: values in **degrees centigrade** (Celsius) 
+- **distance**: values are in **centimeters**
+- **light**: values are in **SI lux** units
+- **pressure**: values are in **hectopascal** (hPa)
+- **relative\_humidity**: values are in **percent**
+- **current**: values are in **milliamps** (mA)
+- **voltage**: values are in **volts** (V)
+- **color**: values are in 0..1.0 RGB channel luminosity and 32-bit RGBA format
+
+## The Unified Driver Abstraction Layer in Practice ##
+
+Using the unified sensor abstraction layer is relatively easy once a compliant driver has been created.
+
+Every compliant sensor can now be read using a single, well-known 'type' (sensors\_event\_t), and there is a standardised way of interrogating a sensor about its specific capabilities (via sensor\_t).
+
+An example of reading the [TSL2561](https://github.com/adafruit/Adafruit_TSL2561) light sensor can be seen below:
+
+```
+ Adafruit_TSL2561 tsl = Adafruit_TSL2561(TSL2561_ADDR_FLOAT, 12345);
+ ...
+ /* Get a new sensor event */ 
+ sensors_event_t event;
+ tsl.getEvent(&event);
+ 
+ /* Display the results (light is measured in lux) */
+ if (event.light)
+ {
+   Serial.print(event.light); Serial.println(" lux");
+ }
+ else
+ {
+   /* If event.light = 0 lux the sensor is probably saturated
+      and no reliable data could be generated! */
+   Serial.println("Sensor overload");
+ }
+```
+
+Similarly, we can get the basic technical capabilities of this sensor with the following code:
+
+```
+ sensor_t sensor;
+ 
+ sensor_t sensor;
+ tsl.getSensor(&sensor);
+
+ /* Display the sensor details */
+ Serial.println("------------------------------------");
+ Serial.print  ("Sensor:       "); Serial.println(sensor.name);
+ Serial.print  ("Driver Ver:   "); Serial.println(sensor.version);
+ Serial.print  ("Unique ID:    "); Serial.println(sensor.sensor_id);
+ Serial.print  ("Max Value:    "); Serial.print(sensor.max_value); Serial.println(" lux");
+ Serial.print  ("Min Value:    "); Serial.print(sensor.min_value); Serial.println(" lux");
+ Serial.print  ("Resolution:   "); Serial.print(sensor.resolution); Serial.println(" lux");  
+ Serial.println("------------------------------------");
+ Serial.println("");
+```

lib/Adafruit_Sensor/library.properties

@@ -0,0 +1,9 @@
+name=Adafruit_Sensor
+version=1.0.2
+author=Adafruit <[email protected]>
+maintainer=Adafruit <[email protected]>
+sentence=Required for all Adafruit Unified Sensor based libraries.
+paragraph=A unified sensor abstraction layer used by many Adafruit sensor libraries.
+category=Sensors
+url=https://github.com/adafruit/Adafruit_Sensor
+architectures=*

lib/Adafruit_Sensor/src/Adafruit_Sensor.h

@@ -0,0 +1,156 @@
+/*
+* Copyright (C) 2008 The Android Open Source Project
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software< /span>
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* Update by K. Townsend (Adafruit Industries) for lighter typedefs, and
+ * extended sensor support to include color, voltage and current */
+
+#ifndef _ADAFRUIT_SENSOR_H
+#define _ADAFRUIT_SENSOR_H
+
+#ifdef PARTICLE
+  #include "Particle.h"
+#elif ARDUINO >= 100
+ #include "Arduino.h"
+ #include "Print.h"
+#else
+ #include "WProgram.h"
+#endif
+
+/* Intentionally modeled after sensors.h in the Android API:
+ * https://github.com/android/platform_hardware_libhardware/blob/master/include/hardware/sensors.h */
+
+/* Constants */
+#define SENSORS_GRAVITY_EARTH             (9.80665F)              /**< Earth's gravity in m/s^2 */
+#define SENSORS_GRAVITY_MOON              (1.6F)                  /**< The moon's gravity in m/s^2 */
+#define SENSORS_GRAVITY_SUN               (275.0F)                /**< The sun's gravity in m/s^2 */
+#define SENSORS_GRAVITY_STANDARD          (SENSORS_GRAVITY_EARTH)
+#define SENSORS_MAGFIELD_EARTH_MAX        (60.0F)                 /**< Maximum magnetic field on Earth's surface */
+#define SENSORS_MAGFIELD_EARTH_MIN        (30.0F)                 /**< Minimum magnetic field on Earth's surface */
+#define SENSORS_PRESSURE_SEALEVELHPA      (1013.25F)              /**< Average sea level pressure is 1013.25 hPa */
+#define SENSORS_DPS_TO_RADS               (0.017453293F)          /**< Degrees/s to rad/s multiplier */
+#define SENSORS_GAUSS_TO_MICROTESLA       (100)                   /**< Gauss to micro-Tesla multiplier */
+
+/** Sensor types */
+typedef enum
+{
+  SENSOR_TYPE_ACCELEROMETER         = (1),   /**< Gravity + linear acceleration */
+  SENSOR_TYPE_MAGNETIC_FIELD        = (2),
+  SENSOR_TYPE_ORIENTATION           = (3),
+  SENSOR_TYPE_GYROSCOPE             = (4),
+  SENSOR_TYPE_LIGHT                 = (5),
+  SENSOR_TYPE_PRESSURE              = (6),
+  SENSOR_TYPE_PROXIMITY             = (8),
+  SENSOR_TYPE_GRAVITY               = (9),
+  SENSOR_TYPE_LINEAR_ACCELERATION   = (10),  /**< Acceleration not including gravity */
+  SENSOR_TYPE_ROTATION_VECTOR       = (11),
+  SENSOR_TYPE_RELATIVE_HUMIDITY     = (12),
+  SENSOR_TYPE_AMBIENT_TEMPERATURE   = (13),
+  SENSOR_TYPE_VOLTAGE               = (15),
+  SENSOR_TYPE_CURRENT               = (16),
+  SENSOR_TYPE_COLOR                 = (17)
+} sensors_type_t;
+
+/** struct sensors_vec_s is used to return a vector in a common format. */
+typedef struct {
+    union {
+        float v[3];
+        struct {
+            float x;
+            float y;
+            float z;
+        };
+        /* Orientation sensors */
+        struct {
+            float roll;    /**< Rotation around the longitudinal axis (the plane body, 'X axis'). Roll is positive and increasing when moving downward. -90�<=roll<=90� */
+            float pitch;   /**< Rotation around the lateral axis (the wing span, 'Y axis'). Pitch is positive and increasing when moving upwards. -180�<=pitch<=180�) */
+            float heading; /**< Angle between the longitudinal axis (the plane body) and magnetic north, measured clockwise when viewing from the top of the device. 0-359� */
+        };
+    };
+    int8_t status;
+    uint8_t reserved[3];
+} sensors_vec_t;
+
+/** struct sensors_color_s is used to return color data in a common format. */
+typedef struct {
+    union {
+        float c[3];
+        /* RGB color space */
+        struct {
+            float r;       /**< Red component */
+            float g;       /**< Green component */
+            float b;       /**< Blue component */
+        };
+    };
+    uint32_t rgba;         /**< 24-bit RGBA value */
+} sensors_color_t;
+
+/* Sensor event (36 bytes) */
+/** struct sensor_event_s is used to provide a single sensor event in a common format. */
+typedef struct
+{
+    int32_t version;                          /**< must be sizeof(struct sensors_event_t) */
+    int32_t sensor_id;                        /**< unique sensor identifier */
+    int32_t type;                             /**< sensor type */
+    int32_t reserved0;                        /**< reserved */
+    int32_t timestamp;                        /**< time is in milliseconds */
+    union
+    {
+        float           data[4];
+        sensors_vec_t   acceleration;         /**< acceleration values are in meter per second per second (m/s^2) */
+        sensors_vec_t   magnetic;             /**< magnetic vector values are in micro-Tesla (uT) */
+        sensors_vec_t   orientation;          /**< orientation values are in degrees */
+        sensors_vec_t   gyro;                 /**< gyroscope values are in rad/s */
+        float           temperature;          /**< temperature is in degrees centigrade (Celsius) */
+        float           distance;             /**< distance in centimeters */
+        float           light;                /**< light in SI lux units */
+        float           pressure;             /**< pressure in hectopascal (hPa) */
+        float           relative_humidity;    /**< relative humidity in percent */
+        float           current;              /**< current in milliamps (mA) */
+        float           voltage;              /**< voltage in volts (V) */
+        sensors_color_t color;                /**< color in RGB component values */
+    };
+} sensors_event_t;
+
+/* Sensor details (40 bytes) */
+/** struct sensor_s is used to describe basic information about a specific sensor. */
+typedef struct
+{
+    char     name[12];                        /**< sensor name */
+    int32_t  version;                         /**< version of the hardware + driver */
+    int32_t  sensor_id;                       /**< unique sensor identifier */
+    int32_t  type;                            /**< this sensor's type (ex. SENSOR_TYPE_LIGHT) */
+    float    max_value;                       /**< maximum value of this sensor's value in SI units */
+    float    min_value;                       /**< minimum value of this sensor's value in SI units */
+    float    resolution;                      /**< smallest difference between two values reported by this sensor */
+    int32_t  min_delay;                       /**< min delay in microseconds between events. zero = not a constant rate */
+} sensor_t;
+
+class Adafruit_Sensor {
+ public:
+  // Constructor(s)
+  Adafruit_Sensor() {}
+  virtual ~Adafruit_Sensor() {}
+
+  // These must be defined by the subclass
+  virtual void enableAutoRange(bool enabled) {};
+  virtual bool getEvent(sensors_event_t*) = 0;
+  virtual void getSensor(sensor_t*) = 0;
+
+ private:
+  bool _autoRange;
+};
+
+#endif