Header for A/D converter.

See ADC Control for documentation.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code. 

/***************************************************************************/
#ifndef __ADC_H__
#define __ADC_H__

#ifdef DOXYGEN_SHOULD_SKIP_THIS

enum ADCUser
#else
// A type for the ADC User enumeration.
typedef uint8_t ADCUser;
enum
#endif //DOXYGEN_SHOULD_SKIP_THIS
{
  ADC_USER_LQI = 0,

  ADC_USER_APP = 1,

  ADC_USER_APP2 = 2
};

#define NUM_ADC_USERS 3U // make sure to update if the above is adjusted

typedef uint8_t ADCChannelType;

typedef uint8_t ADCReferenceType;

typedef uint8_t ADCRateType;

#if defined(EMBER_TEST)
  #include "hal/micro/unix/simulation/adc.h"
#elif defined(CORTEXM3_EMBER_MICRO)
  #include "hal/plugin/adc/adc-cortexm3.h"
#endif

void halInternalInitAdc(void);

void halInternalSleepAdc(void);

EmberStatus halStartAdcConversion(ADCUser id,
                                  ADCReferenceType reference,
                                  ADCChannelType channel,
                                  ADCRateType rate);

EmberStatus halRequestAdcData(ADCUser id, uint16_t *value);

EmberStatus halReadAdcBlocking(ADCUser id, uint16_t *value);

EmberStatus halAdcCalibrate(ADCUser id);

int32_t halConvertValueToVolts(uint16_t value);

void emberCalibrateVref(void);

void halAdcSetClock(bool slow);

bool halAdcGetClock(void);

#endif // __ADC_H__

Macros#

#define
NUM_ADC_USERS 3U

Be sure to update NUM_ADC_USERS if additional users are added to the ADCUser list.

Enumerations#

enum
ADCUser {
ADC_USER_LQI = 0
ADC_USER_APP = 1
ADC_USER_APP2 = 2
}

ADC functions employ a user ID to keep different users separate.

Typedefs#

typedef uint8_t
ADCChannelType

A type for the channel enumeration.

typedef uint8_t
ADCReferenceType

A type for the reference voltage enumeration.

typedef uint8_t
ADCRateType

A type for the sample rate enumeration.

Functions#

void
halInternalInitAdc(void)

Initializes and powers-up the ADC. Should also be called to wake from sleep. The ADC is required for EM250 stack operation so this function must be called from halInit.

void
halInternalSleepAdc(void)

Shuts down the voltage reference and ADC system to minimize power consumption in sleep.

EmberStatus
halStartAdcConversion(ADCUser id, ADCReferenceType reference, ADCChannelType channel, ADCRateType rate)

Starts an ADC conversion for the user specified by id.

EmberStatus
halRequestAdcData(ADCUser id, uint16_t *value)

Returns the status of a pending conversion previously started by halStartAdcConversion(). If the conversion is complete, writes the raw register value of the conversion (the unaltered value taken directly from the ADC's data register) into value.

EmberStatus
halReadAdcBlocking(ADCUser id, uint16_t *value)

Waits for the user's request to complete and then, if a conversion was done, writes the raw register value of the conversion (the unaltered value taken directly from the ADC's data register) into value and returns EMBER_ADC_CONVERSION_DONE, or immediately returns EMBER_ADC_NO_CONVERSION_PENDING.

EmberStatus
halAdcCalibrate(ADCUser id)

Calibrates or recalibrates the ADC system.

int32_t
halConvertValueToVolts(uint16_t value)

Convert the raw register value (the unaltered value taken directly from the ADC's data register) into a signed fixed point value with units 10^-4 Volts. The returned value will be in the range -12000 to +12000 (-1.2000 volts to +1.2000 volts).

void
emberCalibrateVref(void)

Calibrates Vref to be 1.2V +/-10mV.

void
halAdcSetClock(bool slow)

Set ADC clock mode.

bool
halAdcGetClock(void)

Get ADC clock mode.

Macro Definition Documentation#

NUM_ADC_USERS#

#define NUM_ADC_USERS
Value:
3U

Be sure to update NUM_ADC_USERS if additional users are added to the ADCUser list.


Definition at line 79 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

Enumeration Documentation#

ADCUser#

ADCUser

ADC functions employ a user ID to keep different users separate.

Avoid many users because each user requires some amount of state storage.

See Also

Enumerator
ADC_USER_LQI

LQI User ID.

ADC_USER_APP

Application User ID

ADC_USER_APP2

Application User ID


Definition at line 59 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

Typedef Documentation#

ADCChannelType#

typedef uint8_t ADCChannelType

A type for the channel enumeration.


Definition at line 83 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

ADCReferenceType#

typedef uint8_t ADCReferenceType

A type for the reference voltage enumeration.


Definition at line 87 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

ADCRateType#

typedef uint8_t ADCRateType

A type for the sample rate enumeration.


Definition at line 91 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

Function Documentation#

halInternalInitAdc#

void halInternalInitAdc (void )

Initializes and powers-up the ADC. Should also be called to wake from sleep. The ADC is required for EM250 stack operation so this function must be called from halInit.

Parameters
N/A

Definition at line 103 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halInternalSleepAdc#

void halInternalSleepAdc (void )

Shuts down the voltage reference and ADC system to minimize power consumption in sleep.

Parameters
N/A

Definition at line 108 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halStartAdcConversion#

EmberStatus halStartAdcConversion (ADCUser id, ADCReferenceType reference, ADCChannelType channel, ADCRateType rate)

Starts an ADC conversion for the user specified by id.

Parameters
N/Aid

An ADC user.

N/Areference

Voltage reference to use, chosen from enum ADCReferenceType (fixed at ADC_REF_INT for the EM250).

N/Achannel

Microprocessor channel number. For EM250 channels, see the EM250 ADC channels enum. For basic, single-ended Atmel channels, see the Atmega single-ended ADC channels enum. For more complex measurements on Atmels (differential and amped channel numbers), see the Atmel datasheet for your micro.

N/Arate

EM250 rate number (see the ADC EM250 rate enum).

@appusage The application must set reference to the voltage reference desired (see the ADC references enum, fixed at ADC_REF_INT for the em250), set channel to the channel number required (see the ADC channel enum), and set rate to reflect the number of bits of accuracy desired (see the ADC rates enum, fixed at ADC_CONVERSION_TIME_US_256 for the Atmega).

Returns

  • One of the following:

    • EMBER_ADC_CONVERSION_DEFERRED if the conversion is still waiting to start.

    • EMBER_ADC_CONVERSION_BUSY if the conversion is currently taking place.

    • EMBER_ERR_FATAL if a passed parameter is invalid.


Definition at line 139 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halRequestAdcData#

EmberStatus halRequestAdcData (ADCUser id, uint16_t * value)

Returns the status of a pending conversion previously started by halStartAdcConversion(). If the conversion is complete, writes the raw register value of the conversion (the unaltered value taken directly from the ADC's data register) into value.

Parameters
N/Aid

An ADC user.

N/Avalue

Pointer to an uint16_t to be loaded with the new value. Take note that the Atmel's ADC only generates 8-bit values which are loaded into the lower 8 bits of value.

Returns


Definition at line 164 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halReadAdcBlocking#

EmberStatus halReadAdcBlocking (ADCUser id, uint16_t * value)

Waits for the user's request to complete and then, if a conversion was done, writes the raw register value of the conversion (the unaltered value taken directly from the ADC's data register) into value and returns EMBER_ADC_CONVERSION_DONE, or immediately returns EMBER_ADC_NO_CONVERSION_PENDING.

Parameters
N/Aid

An ADC user.

N/Avalue

Pointer to an uint16_t to be loaded with the new value. Take note that the Atmel's ADC only generates 8-bit values which are loaded into the lower 8 bits of value.

Returns


Definition at line 183 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halAdcCalibrate#

EmberStatus halAdcCalibrate (ADCUser id)

Calibrates or recalibrates the ADC system.

Parameters
N/Aid

An ADC user.

@appusage Use this function to (re)calibrate as needed. This function is intended for the EM250 microcontroller, which requires proper calibration to calculate a human readible value (a value in volts). If the app does not call this function, the first time (and only the first time) the function halConvertValueToVolts() is called, this function is invoked. To maintain accurate volt calculations, the application should call this whenever it expects the temperature of the micro to change.

Returns


Definition at line 201 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halConvertValueToVolts#

int32_t halConvertValueToVolts (uint16_t value)

Convert the raw register value (the unaltered value taken directly from the ADC's data register) into a signed fixed point value with units 10^-4 Volts. The returned value will be in the range -12000 to +12000 (-1.2000 volts to +1.2000 volts).

Parameters
N/Avalue

An uint16_t to be converted.

@appusage Use this function to get a human useful value.

Returns

  • Volts as signed fixed point with units 10^-4 Volts.


Definition at line 214 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

emberCalibrateVref#

void emberCalibrateVref (void )

Calibrates Vref to be 1.2V +/-10mV.

Parameters
N/A

@appusage This function must be called from halInternalInitAdc() before making ADC readings. This function is not intended to be called from any function other than halInternalInitAdc(). This function ensures that the master cell voltage and current bias values are calibrated before calibrating Vref.


Definition at line 224 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halAdcSetClock#

void halAdcSetClock (bool slow)

Set ADC clock mode.

Parameters
N/Aslow

A bool to select slow or normal clock.


Definition at line 230 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h

halAdcGetClock#

bool halAdcGetClock (void )

Get ADC clock mode.

Parameters
N/A

Returns

  • A true if the slow clock is selected.


Definition at line 236 of file /Users/vihuszar/Git/EmbeddedSoftware/super/platform/base/hal/plugin/adc/adc.h