path: root/peripheral/libupm/src/ads1x15/ads1x15.h

/*
 * Author: Marc Graham <marc@m2ag.net>
 * 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 <iostream>
#include <string>
#include "mraa.hpp"
#include "mraa/i2c.hpp"

/*=========================================================================
    I2C ADDRESS/BITS
    -----------------------------------------------------------------------*/
#define ADS1X15_ADDRESS                 (0x48)    // 1001 000 (ADDR = GND)
/*=========================================================================*/


/*=========================================================================
    POINTER REGISTER
    -----------------------------------------------------------------------*/
#define ADS1X15_REG_POINTER_MASK        (0x03)
#define ADS1X15_REG_POINTER_CONVERT     (0x00)
#define ADS1X15_REG_POINTER_CONFIG      (0x01)
#define ADS1X15_REG_POINTER_LOWTHRESH   (0x02)
#define ADS1X15_REG_POINTER_HITHRESH    (0x03)
/*=========================================================================*/

/*=========================================================================
    CONFIG REGISTER

    -----------------------------------------------------------------------*/
#define ADS1X15_OS_MASK      (0x8000)
#define ADS1X15_OS_SINGLE    (0x8000)  // Write: Set to start a single-conversion
#define ADS1X15_OS_BUSY      (0x0000)  // Read: Bit = 0 when conversion is in progress
#define ADS1X15_OS_NOTBUSY   (0x8000)  // Read: Bit = 1 when device is not performing a conversion

#define ADS1X15_MUX_MASK     (0x7000)
#define ADS1X15_MUX_DIFF_0_1 (0x0000)  // Differential P = AIN0, N = AIN1 (default)
#define ADS1X15_MUX_DIFF_0_3 (0x1000)  // Differential P = AIN0, N = AIN3
#define ADS1X15_MUX_DIFF_1_3 (0x2000)  // Differential P = AIN1, N = AIN3
#define ADS1X15_MUX_DIFF_2_3 (0x3000)  // Differential P = AIN2, N = AIN3
#define ADS1X15_MUX_SINGLE_0 (0x4000)  // Single-ended AIN0
#define ADS1X15_MUX_SINGLE_1 (0x5000)  // Single-ended AIN1
#define ADS1X15_MUX_SINGLE_2 (0x6000)  // Single-ended AIN2
#define ADS1X15_MUX_SINGLE_3 (0x7000)  // Single-ended AIN3

#define ADS1X15_PGA_MASK     (0x0E00)
#define ADS1X15_PGA_6_144V   (0x0000)  // +/-6.144V range = Gain 2/3
#define ADS1X15_PGA_4_096V   (0x0200)  // +/-4.096V range = Gain 1
#define ADS1X15_PGA_2_048V   (0x0400)  // +/-2.048V range = Gain 2 (default)
#define ADS1X15_PGA_1_024V   (0x0600)  // +/-1.024V range = Gain 4
#define ADS1X15_PGA_0_512V   (0x0800)  // +/-0.512V range = Gain 8
#define ADS1X15_PGA_0_256V   (0x0A00)  // +/-0.256V range = Gain 16

#define ADS1X15_MODE_MASK    (0x0100)
#define ADS1X15_MODE_CONTIN  (0x0000)  // Continuous conversion mode
#define ADS1X15_MODE_SINGLE  (0x0100)  // Power-down single-shot mode (default)

#define ADS1X15_DR_MASK      (0x00E0)

#define ADS1X15_CMODE_MASK   (0x0010)
#define ADS1X15_CMODE_TRAD   (0x0000)  // Traditional comparator with hysteresis (default)
#define ADS1X15_CMODE_WINDOW (0x0010)  // Window comparator

#define ADS1X15_CPOL_MASK    (0x0008)
#define ADS1X15_CPOL_ACTVLOW (0x0000)  // ALERT/RDY pin is low when active (default)
#define ADS1X15_CPOL_ACTVHI  (0x0008)  // ALERT/RDY pin is high when active

#define ADS1X15_CLAT_MASK    (0x0400)  // Determines if ALERT/RDY pin latches once asserted
#define ADS1X15_CLAT_NONLAT  (0x0000)  // Non-latching comparator (default)
#define ADS1X15_CLAT_LATCH   (0x0400)  // Latching comparator

#define ADS1X15_CQUE_MASK    (0x0003)
/* This wouldn't compile for the python wrapper. with these in for some reason.
#define ADS1X15_CQUE_1CONV   (0x0000)  // Assert ALERT/RDY after one conversions
#define ADS1X15_CQUE_2CONV     (0x0001)  // Assert ALERT/RDY after two conversions
#define ADS1X15_CQUE_4CONV     (0x0002)  // Assert ALERT/RDY after four conversions
#define ADS1X15_CQUE_NONE      (0x0003)  // Disable the comparator and put ALERT/RDY in high state (default)
*/
/*=========================================================================*/

namespace upm {
  /**
   * @brief ADS1X15 family adc library
   *
   * Library for TI analog to digital converter ic. Base clase fro ADS1X15 provides all the functionality that
   * ADS1115 and ADS1015 ics have in common.
   *
   * @defgroup ads1x15 libupm-ads1x15
   * @ingroup ti adafruit i2c electric
   */
    class ADS1X15 {

        public:

           /**
            * @enum ADSGAIN
            * @brief uint16_t enum containing values for
            * setting gain for ADS1X15 devices.
            *
            * @var ADSGAIN::TWOTHIRDS = 0x0000
            * @var ADSGAIN::ONE       = 0x0200
            * @var ADSGAIN::TWO       = 0x0400
            * @var ADSGAIN::FOUR      = 0x0600
            * @var ADSGAIN::EIGHT     = 0x0800
            * @var ADSGAIN::SIXTEEN   = 0x0A00
            */
            typedef enum ADSGAIN {
              GAIN_TWOTHIRDS    = ADS1X15_PGA_6_144V,
              GAIN_ONE          = ADS1X15_PGA_4_096V,
              GAIN_TWO          = ADS1X15_PGA_2_048V,
              GAIN_FOUR         = ADS1X15_PGA_1_024V,
              GAIN_EIGHT        = ADS1X15_PGA_0_512V,
              GAIN_SIXTEEN      = ADS1X15_PGA_0_256V
            } ADSGAIN ;

            /**
             * @enum ADSMUXMODE
             * @brief uint16_t enum containing values used
             * for selecting ADS1X15 read operations.
             *
             * @var ADSMUXMODE::DIFF_0_1 = 0x0000
             * @var ADSMUXMODE::DIFF_0_2 = 0x1000
             * @var ADSMUXMODE::DIFF_1_3 = 0x2000
             * @var ADSMUXMODE::DIFF_2_3 = 0x3000
             * @var ADSMUXMODE::SINGLE_0 = 0x4000
             * @var ADSMUXMODE::SINGLE_1 = 0x5000
             * @var ADSMUXMODE::SINGLE_2 = 0x6000
             * @var ADSMUXMODE::SINGLE_3 = 0x7000
             */
            typedef enum ADSMUXMODE {
              DIFF_0_1        = ADS1X15_MUX_DIFF_0_1,  // Differential P = AIN0, N = AIN1 (default)
              DIFF_0_3        = ADS1X15_MUX_DIFF_0_3,  // Differential P = AIN0, N = AIN3
              DIFF_1_3        = ADS1X15_MUX_DIFF_1_3,  // Differential P = AIN1, N = AIN3
              DIFF_2_3        = ADS1X15_MUX_DIFF_2_3,  // Differential P = AIN2, N = AIN3
              SINGLE_0        = ADS1X15_MUX_SINGLE_0,  // Single-ended AIN0
              SINGLE_1        = ADS1X15_MUX_SINGLE_1,  // Single-ended AIN1
              SINGLE_2        = ADS1X15_MUX_SINGLE_2,  // Single-ended AIN2
              SINGLE_3        = ADS1X15_MUX_SINGLE_3   // Single-ended AIN3
            } ADSMUXMODE;

            /**
             * @enum ADSCOMP
             * @brief uint16_t enum containing values
             * for setting ADS1X15 comparator queue modes.
             *
             * @var ADSCOMP::CQUE_1CONV = 0x0000
             * @var ADSCOMP::CQUE_2CONV = 0x0001
             * @var ADSCOMP::CQUE_3CONV = 0x0002
             * @var ADSCOMP::CQUE_NONE  = 0x0003
             */
            typedef enum ADSCOMP {
               CQUE_1CONV      = 0x0000,    // Assert ALERT/RDY after one conversions
               CQUE_2CONV      = 0x0001,    // Assert ALERT/RDY after two conversions
               CQUE_4CONV      = 0x0002,    // Assert ALERT/RDY after four conversions
               CQUE_NONE       = 0x0003      // Disable the comparator and put ALERT/RDY in high state (default)
            } ADSCOMP;

            /**
             * @enum ADSTHRESH
             * @brief uint8_t enum containing register addresses
             * used for setting HI and LOW threshold values as
             * well as setting conversion ready and set to default.
             *
             * @var ADSTHRESH::THRESH_LOW     = 0x02
             * @var ADSTHRESH::THRESH_HIGH    = 0x03
             * @var ADSTHRESH::CONVERSION_RDY = 0x04
             * @var ADSTHRESH::THRESH_DEFAULT = 0x05
             */
            typedef enum ADSTHRESH {
                THRESH_LOW      = ADS1X15_REG_POINTER_LOWTHRESH,
                THRESH_HIGH     = ADS1X15_REG_POINTER_HITHRESH,
                CONVERSION_RDY  = 0x04,
                THRESH_DEFAULT  = 0x05

            } ADSTHRESH;

            /**
             * @enum ADSSAMPLERATE
             * @brief uint16_t enum containing values
             * representing the sample rate of the device.
             * Will be overridden in subclass
             *
             * @var ADSSAMPLERATE::SPS_DEFAULT = 0x0080
             */
            typedef enum ADSSAMPLERATE {
               SPS_DEFAULT     = 0x0080
            } ADSSAMPLERATE;

            /**
             * ADS1X15 constructor
             *
             * @param bus i2c bus the sensor is attached to.
             * @param address. Device address. Default is 0x48.
             */
            ADS1X15(int bus, uint8_t address);

            /**
             * ADS1X15 destructor
             */
            virtual ~ADS1X15 ();

            /**
             * Returns the name of the sensor
             */
            std::string name()
            {
                return m_name;
            }

            /**
             *  Returns the contents of conversion register without performing
             *  a conversion operation. Will use a multiplier based on the
             *  current gain setting to give the voltage as a float. Used
             *  internally to return the HI and LOW threshold values.
             *
             *  @param reg uint8_t value specifying register to read.
             *  Should generally be called with no parameter.
             */
            float getLastSample(int reg = ADS1X15_REG_POINTER_CONVERT);

            /**
             * Performs a read as specified by ADS1X15::ADSMUXMOE and
             * returns the value as a float. Uses getLastSample() internally
             * to return voltage value.
             *
             * @pram mode ADSMUXMODE specifying inputs to be sampled.
             */
            float getSample(ADSMUXMODE mode = ADS1X15::DIFF_0_1);

            /**
             * Returns the current gain setting being used by the device
             * as an ADSGAIN value.
             */
            ADSGAIN getGain(){
                return  (ADSGAIN)(m_config_reg & ADS1X15_PGA_MASK);
            }

            /**
             * Sets the PGA gain bits to the desired gain. Default
             * is +/- 2.094 volts.
             *
             * @param gain ADSGAIN value reprenting the desired gain.
             * See warnings in spec sheet.
             */
            void setGain(ADSGAIN gain = ADS1X15::GAIN_TWO);

            /**
             * Returns the current device sample rate a an ADSSAMPLERATE
             * value.
             */
            ADSSAMPLERATE getSPS(void){
                return (ADSSAMPLERATE)(m_config_reg & ADS1X15_DR_MASK);
            }

            /**
             * Sets the sample rate of the device. This function
             * needs to be overrode in subclasses as the ADS1115 and
             * ADS1015 have different data rates.
             *
             * @param ADSSAMPLERATE enum
             * SPS_DEFAULT = 0x0080
             */
            virtual void setSPS(ADSSAMPLERATE rate);

            /**
             * Returns the comparator mode.
             * False = Traditional comparator with Hysteresis (default)
             * True  = Window Comparator
             */
            bool getCompMode(void){
                return (bool)(m_config_reg & ADS1X15_CMODE_MASK);
            }

            /**
             * Sets the comparator mode of the device.
             *
             * @param mode bool value denoting mode.
             * False = Traditional comparator with Hysteresis (default)
             * True  = Window Comparator
             */
            void setCompMode(bool mode = false);

            /**
             * Get comparator polarity. Reports the polarity
             * of the ALERT/RDY pin. Returns:
             * False = Active Low (default)
             * True  = Active High
             */
            bool getCompPol(void){
                return (bool)(m_config_reg & ADS1X15_CPOL_MASK);
            }

            /**
             * Sets the comparator polarity. Controls the
             * polarity of the ALERT/RDY pin.
             *
             * @param mode bool.
             * False = Active Low (default)
             * True  = Active High
             */
            void setCompPol(bool mode = false);

            /**
             * Returns bool representing the state of the
             * comparator latching functionality.
             * False = Non Latching comparator (default)
             * True  = Latching Comparator
             */
            bool getCompLatch(void){
                return (bool)(m_config_reg & ADS1X15_CLAT_MASK);
            }

            /**
             * Sets bit controlling comparator operation.
             *
             * @param mode bool
             * False = Non Latching comparator (default)
             * True  = Latching Comparator
             */
            void setCompLatch(bool mode = false);

            /**
             * Returns ADSCOMP value representing the state of
             * comparator queue.
             *
             * CQUE_1CONV = Assert after one conversion
             * CQUE_2CONV = Assert after two conversions
             * CQUE_2CONV = Assert after four conversions
             * CQUE_NONE = Disable comparator (default)
             */
            ADSCOMP getCompQue(void){
                return (ADSCOMP)(m_config_reg & ADS1X15_CQUE_MASK);
            }

            /**
             * Sets bits controlling Comparator queue operation.
             *
             * @param mode ADSCOMP enum.
             * CQUE_1CONV = Assert after one conversion
             * CQUE_2CONV = Assert after two conversions
             * CQUE_2CONV = Assert after four conversions
             * CQUE_NONE  = Disable comparator (default)
             */
            void setCompQue(ADSCOMP mode = ADS1X15::CQUE_NONE);

            /**
             * Returns bool reflecting state of device mode bit.
             *
             * False = Power Down Single shot mode (default)
             * True  = Continuous conversion mode
             */
            bool getContinuous(void){
                return !(bool)(m_config_reg & ADS1X15_MODE_MASK);
            }

            /**
             * Sets the state of device mode but.
             *
             * @param mode bool
             * False = Power Down Single shot mode (default)
             * True  = Continuous conversion mode
             */
            void setContinuous(bool mode = false);

            /**
             * Returns current high or low threshold setting.
             *
             * @param reg ADSTHRES enum value.
             * Returns 0.0 unless THRESH_HIGH or THRESH_LOW requested.
             */
            float getThresh(ADSTHRESH reg = THRESH_LOW);

            /**
             * Sets threshold levels or configures for conversion ready
             * operation of ALERT/RDY output.
             *
             * @param reg ADSTHRESH enum
             * @param value float value to set threshold register to.
             *
             * THRESH_LOW      = Sets low thresh register.
             * THRESH_HIGH     = Sets high thresh register.
             * CONVERSION_RDY  = Configures conversion ready operation
             * THRESH_DEFAULT  = resets high/low registers to startup values.
             */
            void setThresh(ADSTHRESH reg = THRESH_DEFAULT , float value = 0.0);

        protected:
            std::string m_name;
            float m_conversionDelay;
            uint8_t m_bitShift;
            uint16_t m_config_reg;
            //Must be overridden in subclass for proper values.
            virtual float getMultiplier(void) = 0;
            //Must be overridden in subclass for proper values.
            virtual void setDelay(void) = 0;
            void getCurrentConfig();
            void updateConfigRegister(uint16_t update, bool read = false);
            uint16_t swapWord(uint16_t value);

               mraa::I2c* i2c;

    };}