ADC.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       ADC.h
 *  @brief      Analog to Digital Conversion (ADC) Input Driver
 *
 *  @anchor ti_drivers_ADC_Overview
 *  # Overview
 *
 *  The ADC driver allows you to manage an Analog to Digital peripheral via
 *  simple and portable APIs. This driver supports sampling and converting
 *  raw values into microvolts.
 *
 *  <hr>
 *  @anchor ti_drivers_ADC_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_ADC_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_ADC_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_ADC_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_ADC_Synopsis_Code
 *  @code
 *  // Import ADC Driver definitions
 *  #include <ti/drivers/ADC.h>
 *
 *  // Define name for ADC channel index
 *  #define THERMOCOUPLE_OUT  0
 *
 *  // One-time init of ADC driver
 *  ADC_init();
 *
 *  // initialize optional ADC parameters
 *  ADC_Params params;
 *  ADC_Params_init(&params);
 *  params.isProtected = true;
 *
 *  // Open ADC channels for usage
 *  ADC_Handle adcHandle = ADC_open(THERMOCOUPLE_OUT, &params);
 *
 *  // Sample the analog output from the Thermocouple
 *  ADC_convert(adcHandle, &result);
 *
 *  // Convert the sample to microvolts
 *  resultUv = ADC_convertToMicroVolts(adcHandle, result);
 *
 *  ADC_close(adcHandle);
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_ADC_Examples
 *  # Examples
 *
 *  @li @ref ti_drivers_ADC_Examples_open "Opening an ADC instance"
 *  @li @ref ti_drivers_ADC_Examples_convert "Taking an ADC sample"
 *  @li @ref ti_drivers_ADC_Examples_convert_microvolts "Converting a sample to microvolts"
 *  @li @ref ti_drivers_ADC_Examples_convert_chain "Executing multi-channel sampling"
 *
 *  @anchor ti_drivers_ADC_Examples_open
 *  ## Opening an ADC instance
 *
 *  @code
 *  ADC_Handle adc;
 *  ADC_Params params;
 *
 *  ADC_Params_init(&params);
 *
 *  adc = ADC_open(0, &params);
 *  if (adc == NULL) {
 *      // ADC_open() failed
 *      while (1) {}
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_ADC_Examples_convert
 *  ## Taking an ADC sample
 *
 *  An ADC conversion with an ADC peripheral is started by calling
 *  ADC_convert(). The result value is returned by ADC_convert()
 *  once the conversion is finished.
 *
 *  @code
 *  int_fast16_t res;
 *  uint_fast16_t adcValue;
 *
 *  res = ADC_convert(adc, &adcValue);
 *  if (res == ADC_STATUS_SUCCESS)
 *  {
 *      print(adcValue);
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_ADC_Examples_convert_microvolts
 *  ## Converting a sample to microvolts
 *
 *  The result value returned by ADC_convert() is a raw value. The
 *  following uses ADC_convertToMicroVolts() to convert the raw value
 *  into microvolts.
 *  @code
 *  int_fast16_t res;
 *  uint_fast16_t adcValue;
 *  uint32_t adcValueUv;
 *
 *  res = ADC_convert(adc, &adcValue);
 *  if (res == ADC_STATUS_SUCCESS)
 *  {
 *      adcValueUv = ADC_convertToMicroVolts(adc, adcValue);
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_ADC_Examples_convert_chain
 *  ## Executing multi-channel sampling
 *
 *  ADC_convertChain() provides an optimized way to perform
 *  ADC conversions for several ADC instances (multi-channel sampling).
 *  It takes a list of identically configured ADC instances and returns
 *  a buffer with the corresponding result values once the conversion
 *  is finished. One typical use-case would be reading a group of sensors
 *  that share the sampling duration.
 *
 *  Should the configuration of the ADC instances differ, the configuration
 *  of the first instance in the list is used to set the parameters of the
 *  entire conversion chain.
 *  @code
 *  ADC_Handle   adc[ADC_COUNT];
 *  int_fast16_t res;
 *  uint16_t     retValues[ADC_COUNT];
 *  uint8_t      i;
 *
 *  res = ADC_convertChain(adc, retValues, ADC_COUNT);
 *  if (res == ADC_STATUS_SUCCESS)
 *  {
 *      for (i = 0; i < ADC_COUNT; i++) {
 *          print(retValues[i]);
 *      }
 *  }
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_ADC_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 ******************************************************************************
 */

#ifndef ti_drivers_ADC__include
#define ti_drivers_ADC__include

#include <stdbool.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ADC_convertRawToMicroVolts ADC_convertToMicroVolts

#define ADC_CMD_RESERVED           (32)

#define ADC_STATUS_RESERVED        (-32)

#define ADC_STATUS_SUCCESS         (0)

#define ADC_STATUS_ERROR           (-1)

#define ADC_STATUS_UNDEFINEDCMD    (-2)

/* Add ADC_CMD_<commands> here */

typedef struct ADC_Config_ *ADC_Handle;

typedef struct {
    void    *custom;        
    bool    isProtected;    
} ADC_Params;

typedef void (*ADC_CloseFxn) (ADC_Handle handle);

typedef int_fast16_t (*ADC_ControlFxn) (ADC_Handle handle, uint_fast16_t cmd,
    void *arg);

typedef int_fast16_t (*ADC_ConvertFxn) (ADC_Handle handle, uint16_t *value);

typedef int_fast16_t (*ADC_ConvertChainFxn) (ADC_Handle *handleList,
    uint16_t *dataBuffer, uint8_t channelCount);

typedef uint32_t (*ADC_ConvertToMicroVoltsFxn) (ADC_Handle handle,
    uint16_t adcValue);

typedef void (*ADC_InitFxn) (ADC_Handle handle);

typedef ADC_Handle (*ADC_OpenFxn) (ADC_Handle handle, ADC_Params *params);

typedef struct {
    ADC_CloseFxn      closeFxn;

    ADC_ControlFxn    controlFxn;

    ADC_ConvertFxn    convertFxn;

    ADC_ConvertChainFxn convertChainFxn;

    ADC_ConvertToMicroVoltsFxn convertToMicroVolts;

    ADC_InitFxn       initFxn;

    ADC_OpenFxn       openFxn;
} ADC_FxnTable;

typedef struct ADC_Config_ {
    ADC_FxnTable const *fxnTablePtr;

    void               *object;

    void         const *hwAttrs;
} ADC_Config;

extern void ADC_close(ADC_Handle handle);

extern int_fast16_t ADC_control(ADC_Handle handle, uint_fast16_t cmd,
    void *arg);

extern int_fast16_t ADC_convert(ADC_Handle handle, uint16_t *value);

extern int_fast16_t ADC_convertChain(ADC_Handle *handleList,
    uint16_t *dataBuffer, uint8_t channelCount);

extern uint32_t ADC_convertToMicroVolts(ADC_Handle handle,
    uint16_t adcValue);

extern void ADC_init(void);

extern ADC_Handle ADC_open(uint_least8_t index, ADC_Params *params);

extern void ADC_Params_init(ADC_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ADC__include */