ModularSensors > Topics > Supported Sensors > Analog Sensors via TI ADS1x15 > TI ADS1x15 External Voltage Sensor

TI ADS1x15 External Voltage Sensor topic

Classes for simple external analog voltage measurements.

Introduction

Analog data output is supported in ModularSensors by way of the Texas Instruments ADS1115.

The External Voltage module is used for any case where the voltage itself is the desired value (as for an external battery). It can also be used in combination with a calculated variable to support any other analog sensor not explicity supported by ModularSensors. To increase the range available for voltage measurements, this module supports the use of a voltage divider.

If you are working with an EnviroDIY Mayfly, the easiest voltage divider to connect is the Grove voltage divider sold by seeed studio. The grove voltage divider is a simple voltage divider designed to measure high external voltages on a low voltage ADC. This module employs a variable gain via two pairs of voltage dividers, and a unity gain amplification to reduce output impedance of the module.

Sensor Datasheet

Technical specifications for the Grove Voltage Divider can be found at: http://wiki.seeedstudio.com/Grove-Voltage_Divider

Build flags

  • -D MS_USE_ADS1015
    • switches from the 16-bit ADS1115 to the 12 bit ADS1015

Sensor Constructor

TIADS1x15::TIADS1x15(int8_t powerPin, uint8_t adsChannel, float gain = 1, uint8_t i2cAddress = 0x48, uint8_t measurementsToAverage = 1)

Construct a new External Voltage object - need the power pin and the data channel on the ADS1x15.

Parameters
powerPin The pin on the mcu controlling power to the sensor Use -1 if it is continuously powered.
adsChannel The ADS channel of interest (0-3).
gain The gain multiplier, if a voltage divider is used.
i2cAddress The I2C address of the ADS 1x15, default is 0x48 (ADDR = GND)
measurementsToAverage The number of measurements to take and average before giving a "final" result from the sensor; optional with a default value of 1.

The gain value, I2C address, and number of measurements to average are optional. If nothing is given a 1x gain is used.

Example Code

The TI ADS1X15 external voltage sensor is used in the menu a la carte example.

1#include <sensors/TIADS1x15.h>
2
3// NOTE: Use -1 for any pins that don't apply or aren't being used.
4const int8_t ADSPower = sensorPowerPin; // Power pin
5const int8_t ADSChannel = 2; // The ADS channel of interest
6const float dividerGain = 10; // Gain setting if using a voltage divider
7const uint8_t evADSi2c_addr = 0x48; // The I2C address of the ADS1115 ADC
8const uint8_t VoltReadsToAvg = 1; // Only read one sample
9
10// Create an External Voltage sensor object
11TIADS1x15 ads1x15(ADSPower, ADSChannel, dividerGain, evADSi2c_addr,
12 VoltReadsToAvg);
13
14// Create a voltage variable pointer
15Variable* ads1x15Volt =
16 new TIADS1x15_Voltage(&ads1x15, "12345678-abcd-1234-ef00-1234567890ab");

Classes

class TIADS1x15
The Sensor sub-class for the external votlage as measured by TI ADS1115 or ADS1015.
class TIADS1x15_Voltage
The Variable sub-class used for the voltage output from a TI ADS1115 or ADS1015.

Typedefs

using ExternalVoltage = TIADS1x15 deprecated in v0.33.0
typedef for backwards compatibility; use the TIADS1x15 class in new code
using ExternalVoltage_Volt = TIADS1x15_Voltage deprecated in v0.33.0
typedef for backwards compatibility; use the TIADS1x15_Voltage class in new code

Sensor Variable Counts

The number of variables that can be returned by ADS1x15

#define TIADS1X15_NUM_VARIABLES = 1
Sensor::_numReturnedValues; the ADS1115 can report 1 value.
#define TIADS1X15_INC_CALC_VARIABLES = 0
Sensor::_incCalcValues; we don't calculate any additional values.

Configuration Defines

Defines to help configure the address of the ADD

#define ADS1115_ADDRESS = 0x48
The assumed address of the ADS1115, 1001 000 (ADDR = GND)

Sensor Timing

The sensor timing for a TI ADS1x15 analog-to-digital converter (ADC) The timing used for simple external voltage measurements is that of the ADS1x15.

#define TIADS1X15_WARM_UP_TIME_MS = 2
Sensor::_warmUpTime_ms; the ADS1115 warms up in 2ms.
#define TIADS1X15_STABILIZATION_TIME_MS = 0
Sensor::_stabilizationTime_ms; the ADS1115 is stable 0ms after warm-up.
#define TIADS1X15_MEASUREMENT_TIME_MS = 0
Sensor::_measurementTime_ms; the ADS1115 completes 860 conversions per second, but the wait for the conversion to complete is built into the underlying library, so we do not need to wait further here.

Voltage

The volt variable from a TI ADS1x15 analog-to-digital converter (ADC)

  • Range:
    • without voltage divider: 0 - 3.6V [when ADC is powered at 3.3V]
    • 1/gain = 3x: 0.3 ~ 12.9V
    • 1/gain = 10x: 1 ~ 43V
  • Accuracy:
    • 16-bit ADC (ADS1115): < 0.25% (gain error), <0.25 LSB (offset errror)
    • 12-bit ADC (ADS1015, using build flag MS_USE_ADS1015): < 0.15% (gain error), <3 LSB (offset errror)
  • Resolution:
    • 16-bit ADC (ADS1115):
    • 12-bit ADC (ADS1015, using build flag MS_USE_ADS1015):

TIADS1x15_Voltage::TIADS1x15_Voltage(TIADS1x15* parentSense, const char* uuid = "", const char* varCode = "extVoltage") explicit

Construct a new TIADS1x15_Voltage object.

Parameters
parentSense The parent TIADS1x15 providing the result values.
uuid A universally unique identifier (UUID or GUID) for the variable; optional with the default value of an empty string.
varCode A short code to help identify the variable in files; optional with a default value of "extVoltage".

#define TIADS1X15_VAR_NUM = 0
Variable number; voltage is stored in sensorValues[0].
#define TIADS1X15_VAR_NAME = "voltage"
Variable name in ODM2 controlled vocabulary; "voltage".
#define TIADS1X15_UNIT_NAME = "volt"
Variable unit name in ODM2 controlled vocabulary; "volt".
#define TIADS1X15_DEFAULT_CODE = "extVoltage"
Default variable short code; "extVoltage".
#define TIADS1X15_RESOLUTION = 4
Decimals places in string representation; voltage should have 4.

Typedef documentation

typedef TIADS1x15 ExternalVoltage
#include <src/sensors/TIADS1x15.h>

typedef for backwards compatibility; use the TIADS1x15 class in new code

typedef TIADS1x15_Voltage ExternalVoltage_Volt
#include <src/sensors/TIADS1x15.h>

typedef for backwards compatibility; use the TIADS1x15_Voltage class in new code

Define documentation

#define TIADS1X15_NUM_VARIABLES = 1
#include <src/sensors/TIADS1x15.h>

Sensor::_numReturnedValues; the ADS1115 can report 1 value.

#define TIADS1X15_INC_CALC_VARIABLES = 0
#include <src/sensors/TIADS1x15.h>

Sensor::_incCalcValues; we don't calculate any additional values.

#define ADS1115_ADDRESS = 0x48
#include <src/sensors/TIADS1x15.h>

The assumed address of the ADS1115, 1001 000 (ADDR = GND)

#define TIADS1X15_WARM_UP_TIME_MS = 2
#include <src/sensors/TIADS1x15.h>

Sensor::_warmUpTime_ms; the ADS1115 warms up in 2ms.

#define TIADS1X15_STABILIZATION_TIME_MS = 0
#include <src/sensors/TIADS1x15.h>

Sensor::_stabilizationTime_ms; the ADS1115 is stable 0ms after warm-up.

We assume a voltage is instantly ready.

#define TIADS1X15_MEASUREMENT_TIME_MS = 0
#include <src/sensors/TIADS1x15.h>

Sensor::_measurementTime_ms; the ADS1115 completes 860 conversions per second, but the wait for the conversion to complete is built into the underlying library, so we do not need to wait further here.

#define TIADS1X15_VAR_NUM = 0
#include <src/sensors/TIADS1x15.h>

Variable number; voltage is stored in sensorValues[0].

#define TIADS1X15_VAR_NAME = "voltage"
#include <src/sensors/TIADS1x15.h>

Variable name in ODM2 controlled vocabulary; "voltage".

#define TIADS1X15_UNIT_NAME = "volt"
#include <src/sensors/TIADS1x15.h>

Variable unit name in ODM2 controlled vocabulary; "volt".

#define TIADS1X15_DEFAULT_CODE = "extVoltage"
#include <src/sensors/TIADS1x15.h>

Default variable short code; "extVoltage".

#define TIADS1X15_RESOLUTION = 4
#include <src/sensors/TIADS1x15.h>

Decimals places in string representation; voltage should have 4.