adc_8h | EmberZNET API Reference Guide | Zigbee | v6.9

Header for A/D converter.

See ADC Control for documentation.

License#

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.

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

NUM_ADC_USERS

Enumerator
ADC_USER_LQI	LQI User ID.
ADC_USER_APP	Application User ID
ADC_USER_APP2	Application User ID

Typedef Documentation#

ADCChannelType#

typedef uint8_t ADCChannelType

A type for the channel enumeration.

ADCReferenceType#

typedef uint8_t ADCReferenceType

A type for the reference voltage enumeration.

ADCRateType#

typedef uint8_t ADCRateType

A type for the sample rate enumeration.

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

Type	Direction	Argument Name	Description
void	N/A

halInternalSleepAdc#

void halInternalSleepAdc (void )

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

Parameters

Type	Direction	Argument Name	Description
void	N/A

halStartAdcConversion#

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

Starts an ADC conversion for the user specified by id.

Parameters

Type	Direction	Argument Name	Description
ADCUser	N/A	id	An ADC user.
ADCReferenceType	N/A	reference	Voltage reference to use, chosen from enum ADCReferenceType (fixed at ADC_REF_INT for the EM250).
ADCChannelType	N/A	channel	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.
ADCRateType	N/A	rate	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.

halRequestAdcData#

EmberStatus halRequestAdcData (ADCUser id, uint16_t * value)

Parameters

Type	Direction	Argument Name	Description
ADCUser	N/A	id	An ADC user.
uint16_t *	N/A	value	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

One of the following:
- EMBER_ADC_CONVERSION_DONE if the conversion is complete.
- EMBER_ADC_CONVERSION_DEFERRED if the conversion is still waiting to start.
- EMBER_ADC_CONVERSION_BUSY if the conversion is currently taking place.
- EMBER_ADC_NO_CONVERSION_PENDING if id does not have a pending conversion.

halReadAdcBlocking#

EmberStatus halReadAdcBlocking (ADCUser id, uint16_t * value)

Parameters

Type	Direction	Argument Name	Description
ADCUser	N/A	id	An ADC user.
uint16_t *	N/A	value	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

One of the following:
- EMBER_ADC_CONVERSION_DONE if the conversion is complete.
- EMBER_ADC_NO_CONVERSION_PENDING if id does not have a pending conversion.

halAdcCalibrate#

EmberStatus halAdcCalibrate (ADCUser id)

Calibrates or recalibrates the ADC system.

Parameters

Type	Direction	Argument Name	Description
ADCUser	N/A	id	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

One of the following:
- EMBER_ADC_CONVERSION_DONE if the calibration is complete.
- EMBER_ERR_FATAL if the calibration failed.

halConvertValueToVolts#

int32_t halConvertValueToVolts (uint16_t value)

Parameters

Type	Direction	Argument Name	Description
uint16_t	N/A	value	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.

emberCalibrateVref#

void emberCalibrateVref (void )

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

Parameters

Type	Direction	Argument Name	Description
void	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.

halAdcSetClock#

void halAdcSetClock (bool slow)

Set ADC clock mode.

Parameters

Type	Direction	Argument Name	Description
bool	N/A	slow	A bool to select slow or normal clock.

halAdcGetClock#

bool halAdcGetClock (void )

Get ADC clock mode.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

A true if the slow clock is selected.