ADS1118.cpp

/**
*  Arduino Library for Texas Instruments ADS1118 - 16-Bit Analog-to-Digital Converter with 
*  Internal Reference and Temperature Sensor
*  
*  @author Alvaro Salazar <alvaro@denkitronik.com>
*  http://www.denkitronik.com
*
*/


/**
 * The MIT License
 *
 * Copyright 2018 Alvaro Salazar <alvaro@denkitronik.com>.
 *
 * 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 "ADS1118.h"
#include "Arduino.h"

/**
* Debugging:
*   Uncomment some of the 3 lines above to debug the method you want. 
* Warning: 
*   Keep them commented in production
*/
//#define DEBUG_BEGIN  			//Debug begin() method
//#define DEBUG_GETADCVALUE  	//Debug getADCValue() method
//#define DEBUG_GETTEMPERATURE  //Debug getTemperature() method

#ifdef DEBUG_BEGIN
    #define DEBUG_BEGIN(x) decodeConfigRegister(x)
#else
    #define DEBUG_BEGIN(x)
#endif

#ifdef DEBUG_GETADCVALUE
    #define DEBUG_GETADCVALUE(x) decodeConfigRegister(x)
#else
    #define DEBUG_GETADCVALUE(x)
#endif

#ifdef DEBUG_GETTEMPERATURE
    #define DEBUG_GETTEMPERATURE(x) decodeConfigRegister(x)
#else
    #define DEBUG_GETTEMPERATURE(x)
#endif

/**
 * Constructor of the class
 * @param io_pin_cs a byte indicating the pin to be use as the chip select pin (CS)
 */
ADS1118::ADS1118(uint8_t io_pin_cs) {
    cs = io_pin_cs;
}

/**
 * This method initialize the SPI port and the config register
 */
void ADS1118::begin() {
    pinMode(cs, OUTPUT);
	digitalWrite(cs, HIGH);
    SPI.begin();
    SPI.beginTransaction(SPISettings(SCLK, MSBFIRST, SPI_MODE1));
	configRegister.bits={RESERVED, VALID_CFG, PULLUP, ADC_MODE, RATE_8SPS, SINGLE_SHOT, FSR_0256, DIFF_0_1, START_NOW}; //Default values
    DEBUG_BEGIN(configRegister); //Debug this method: print the config register in the Serial port
}

/**
 * Getting a sample from the specified input
 * @param inputs Sets the input of the ADC: Diferential inputs: DIFF_0_1, DIFF_0_3, DIFF_1_3, DIFF_2_3. Single ended input: AIN_0, AIN_1, AIN_2, AIN_3
 * @return A word containing the ADC value
 */
uint16_t ADS1118::getADCValue(uint8_t inputs) {
    uint16_t value;
    byte dataMSB, dataLSB, configMSB, configLSB, count=0;
	if(lastSensorMode==ADC_MODE)  //Lucky you! We don't have to read twice the sensor
		count=1;
	else
		configRegister.bits.sensorMode=ADC_MODE; //Sorry but we will have to read twice the sensor
	configRegister.bits.mux=inputs;
    do{	
		digitalWrite(cs, LOW);
		dataMSB = SPI.transfer(configRegister.byte.msb);
		dataLSB = SPI.transfer(configRegister.byte.lsb);
		configMSB = SPI.transfer(configRegister.byte.msb);
		configLSB = SPI.transfer(configRegister.byte.lsb);
		digitalWrite(cs, HIGH);
		for(int i=0;i<CONV_TIME[configRegister.bits.rate];i++) //Lets wait the conversion time
			delayMicroseconds(1000);
		count++;
	}while (count<=1);  //We make two readings because the second reading is the ADC conversion.	
    DEBUG_GETADCVALUE(configRegister);  //Debug this method: print the config register in the Serial port
	value = (dataMSB << 8) | (dataLSB);
    return value;
}


/**
 * Getting the millivolts from the specified inputs
 * @param inputs Sets the inputs to be adquired. Diferential inputs: DIFF_0_1, DIFF_0_3, DIFF_1_3, DIFF_2_3. Single ended input: AIN_0, AIN_1, AIN_2, AIN_3
 * @return A double (32bits) containing the ADC value in millivolts
 */
double ADS1118::getMilliVolts(uint8_t inputs) {
	float volts;
    float fsr = pgaFSR[configRegister.bits.pga];
	uint16_t value;
	value=getADCValue(inputs);
	if(value>=0x8000){
		value=((~value)+1); //Applying binary twos complement format
		volts=((float)(value*fsr/32768)*-1);
	} else {
		volts=(float)(value*fsr/32768);
	}
    return volts*1000;
}


/**
 * Getting the millivolts from the settled inputs
 * @return A double (32bits) containing the ADC value in millivolts
 */
double ADS1118::getMilliVolts() {
	float volts;
    float fsr = pgaFSR[configRegister.bits.pga];
	uint16_t value;
	value=getADCValue(configRegister.bits.mux);
	if(value>=0x8000){
		value=((~value)+1); //Applying binary twos complement format
		volts=((float)(value*fsr/32768)*-1);
	} else {
		volts=(float)(value*fsr/32768);
	}
    return volts*1000;
}

/**
 * Getting the temperature in degrees celsius from the internal sensor of the ADS1118
 * @return A double (32bits) containing the temperature in degrees celsius of the internal sensor
 */
double ADS1118::getTemperature() {
    uint16_t convRegister;
    uint8_t dataMSB, dataLSB, configMSB, configLSB, count=0;
	if(lastSensorMode==TEMP_MODE)
		count=1;  //Lucky you! We don't have to read twice the sensor
	else
		configRegister.bits.sensorMode=TEMP_MODE; //Sorry but we will have to read twice the sensor
    do{
		digitalWrite(cs, LOW);
		dataMSB = SPI.transfer(configRegister.byte.msb);
		dataLSB = SPI.transfer(configRegister.byte.lsb);
		configMSB = SPI.transfer(configRegister.byte.msb);
		configLSB = SPI.transfer(configRegister.byte.lsb);
		digitalWrite(cs, HIGH);
		for(int i=0;i<CONV_TIME[configRegister.bits.rate];i++) //Lets wait the conversion time
			delayMicroseconds(1000);
		count++;
	}while (count<=1);  //We make two readings because the second reading is the temperature.
    DEBUG_GETTEMPERATURE(configRegister);  //Debug this method: print the config register in the Serial port
	convRegister = ((dataMSB << 8) | (dataLSB))>>2;
    if((convRegister<<2) >= 0x8000){
		convRegister=((~convRegister)>>2)+1; //Converting to right-justified and applying binary twos complement format
        return (double)(convRegister*0.03125*-1);
    }
    return (double)convRegister*0.03125;
}

/**
 * Setting the sampling rate specified in the config register
 * @param samplingRate It's the sampling rate: RATE_8SPS, RATE_16SPS, RATE_32SPS, RATE_64SPS, RATE_128SPS, RATE_250SPS, RATE_475SPS, RATE_860SPS
 */
void ADS1118::setSampligRate(uint8_t samplingRate){
	configRegister.bits.rate=samplingRate;
}

/**
 * Setting the full scale range in the config register
 * @param fsr The full scale range: FSR_6144 (±6.144V)*, FSR_4096(±4.096V)*, FSR_2048(±2.048V), FSR_1024(±1.024V), FSR_0512(±0.512V), FSR_0256(±0.256V). (*) No more than VDD + 0.3 V must be applied to this device.
 */
void ADS1118::setFullScaleRange(uint8_t fsr){
	configRegister.bits.pga=fsr;
}

/**
 * Setting the inputs to be adquired in the config register. 
 * @param input The input selected: Diferential inputs: DIFF_0_1, DIFF_0_3, DIFF_1_3, DIFF_2_3. Single ended input: AIN_0, AIN_1, AIN_2, AIN_3
 */
void ADS1118::setInputSelected(uint8_t input){
	configRegister.bits.mux=input;
}

/**
 * Setting to continuous adquisition mode
 */
void ADS1118::setContinuousMode(){
	configRegister.bits.operatingMode=CONTINUOUS;
}

/**
 * Setting to single shot adquisition and power down mode
 */
void ADS1118::setSingleShotMode(){
	configRegister.bits.operatingMode=SINGLE_SHOT;
}

/**
 * Disabling the internal pull-up resistor of the DOUT pin
 */
void ADS1118::disablePullup(){
	configRegister.bits.operatingMode=NO_PULLUP;
}

/**
 * Enabling the internal pull-up resistor of the DOUT pin
 */
void ADS1118::enablePullup(){
	configRegister.bits.operatingMode=PULLUP;
}

/**
 * Decoding a configRegister structure and then print it out to the Serial port
 * @param configRegister The config register in "union Config" format
 */
void ADS1118::decodeConfigRegister(union Config configRegister){
	String mensaje=String();
	switch(configRegister.bits.singleStart){
		case 0: mensaje="NOINI"; break;
		case 1: mensaje="START"; break;
	}
    mensaje+=" ";
	switch(configRegister.bits.mux){
		case 0: mensaje+="A0-A1"; break;
	    case 1: mensaje+="A0-A3"; break;
		case 2: mensaje+="A1-A3"; break;
		case 3: mensaje+="A2-A3"; break;
		case 4: mensaje+="A0-GD"; break;
		case 5: mensaje+="A1-GD"; break;
		case 6: mensaje+="A2-GD"; break;
		case 7: mensaje+="A3-GD"; break;
		}
    mensaje+=" ";
	switch(configRegister.bits.pga){
		case 0: mensaje+="6.144"; break;
	    case 1: mensaje+="4.096"; break;
		case 2: mensaje+="2.048"; break;
		case 3: mensaje+="1.024"; break;
		case 4: mensaje+="0.512"; break;
		case 5: mensaje+="0.256"; break;
		case 6: mensaje+="0.256"; break;
		case 7: mensaje+="0.256"; break;
		}
    mensaje+=" ";		
	switch(configRegister.bits.operatingMode){
		case 0: mensaje+="CONT."; break;
	    case 1: mensaje+="SSHOT"; break;
	}
    mensaje+=" ";		
	switch(configRegister.bits.rate){
		case 0: mensaje+="8 SPS"; break;
	    case 1: mensaje+="16SPS"; break;
		case 2: mensaje+="32SPS"; break;
		case 3: mensaje+="64SPS"; break;
		case 4: mensaje+="128SP"; break;
		case 5: mensaje+="250SP"; break;
		case 6: mensaje+="475SP"; break;
		case 7: mensaje+="860SP"; break;
	}
    mensaje+=" ";		
	switch(configRegister.bits.sensorMode){
		case 0: mensaje+="ADC_M"; break;
	    case 1: mensaje+="TMP_M"; break;
	}
    mensaje+=" ";		
	switch(configRegister.bits.pullUp){
		case 0: mensaje+="DISAB"; break;
	    case 1: mensaje+="ENABL"; break;
	}
    mensaje+=" ";		
	switch(configRegister.bits.noOperation){
		case 0: mensaje+="INVAL"; break;
	    case 1: mensaje+="VALID"; break;
		case 2: mensaje+="INVAL"; break;
		case 3: mensaje+="INVAL"; break;
	}
    mensaje+=" ";		
	switch(configRegister.bits.reserved){
		case 0: mensaje+="RSRV0"; break;
	    case 1: mensaje+="RSRV1"; break;
	}	
	Serial.println("\nSTART MXSEL PGASL MODES RATES ADTMP PLLUP NOOPE RESER");
	Serial.println(mensaje);
	
}