ADC Control
Hardware Abstraction Layer (HAL) API Reference > Sample APIs for Peripheral Access

Macros

#define NUM_ADC_USERS 3U
Be sure to update NUM_ADC_USERS if additional users are added to the ADCUser list.
#define ADC_MUXN_BITS (4)
#define ADC_MUX_ADC0 0x0
#define ADC_MUX_ADC1 0x1
#define ADC_MUX_ADC2 0x2
#define ADC_MUX_ADC3 0x3
#define ADC_MUX_ADC4 0x4
#define ADC_MUX_ADC5 0x5
#define ADC_MUX_GND 0x8
#define ADC_MUX_VREF2 0x9
#define ADC_MUX_VREF 0xA
#define ADC_MUX_VREG2 0xB

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.

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.
enum { ADC_REF_INT = 42U }
ADCReferenceType Enumeration. Note: EM35x only supports one reference type: Internal.
enum {
ADC_SAMPLE_CLOCKS_32 = 0x0,
ADC_SAMPLE_CLOCKS_64 = 0x1,
ADC_SAMPLE_CLOCKS_128 = 0x2,
ADC_SAMPLE_CLOCKS_256 = 0x3,
ADC_SAMPLE_CLOCKS_512 = 0x4,
ADC_SAMPLE_CLOCKS_1024 = 0x5,
ADC_SAMPLE_CLOCKS_2048 = 0x6,
ADC_SAMPLE_CLOCKS_4096 = 0x7
}
ADCRateType enumeration. These rates are specified in the number of clock cycles That a conversion takes. The actual time taken will depend on the selected ADC clock rate. (Default is 6MHz)
enum {
ADC_CONVERSION_TIME_US_32 = 0x0,
ADC_CONVERSION_TIME_US_64 = 0x1,
ADC_CONVERSION_TIME_US_128 = 0x2,
ADC_CONVERSION_TIME_US_256 = 0x3,
ADC_CONVERSION_TIME_US_512 = 0x4,
ADC_CONVERSION_TIME_US_1024 = 0x5,
ADC_CONVERSION_TIME_US_2048 = 0x6,
ADC_CONVERSION_TIME_US_4096 = 0x7
}
ADC rates for compatibility with EM2xx applications. For EM35x only applications, the ADC_SAMPLE_CLOCKS_nnn definitions should be used instead.
enum {
ADC_SOURCE_ADC0_VREF2 = ((ADC_MUX_ADC0 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC0_GND = ((ADC_MUX_ADC0 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC1_VREF2 = ((ADC_MUX_ADC1 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC1_GND = ((ADC_MUX_ADC1 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC2_VREF2 = ((ADC_MUX_ADC2 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC2_GND = ((ADC_MUX_ADC2 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC3_VREF2 = ((ADC_MUX_ADC3 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC3_GND = ((ADC_MUX_ADC3 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC4_VREF2 = ((ADC_MUX_ADC4 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC4_GND = ((ADC_MUX_ADC4 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC5_VREF2 = ((ADC_MUX_ADC5 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_ADC5_GND = ((ADC_MUX_ADC5 << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_ADC1_ADC0 = ((ADC_MUX_ADC1 << ADC_MUXN_BITS) + ADC_MUX_ADC0),
ADC_SOURCE_ADC0_ADC1 = ((ADC_MUX_ADC1 << ADC_MUXN_BITS) + ADC_MUX_ADC0),
ADC_SOURCE_ADC3_ADC2 = ((ADC_MUX_ADC3 << ADC_MUXN_BITS) + ADC_MUX_ADC2),
ADC_SOURCE_ADC2_ADC3 = ((ADC_MUX_ADC3 << ADC_MUXN_BITS) + ADC_MUX_ADC2),
ADC_SOURCE_ADC5_ADC4 = ((ADC_MUX_ADC5 << ADC_MUXN_BITS) + ADC_MUX_ADC4),
ADC_SOURCE_GND_VREF2 = ((ADC_MUX_GND << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_VGND = ((ADC_MUX_GND << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_VREF_VREF2 = ((ADC_MUX_VREF << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_VREF = ((ADC_MUX_VREF << ADC_MUXN_BITS) + ADC_MUX_GND),
ADC_SOURCE_VREG2_VREF2 = ((ADC_MUX_VREG2 << ADC_MUXN_BITS) + ADC_MUX_VREF2),
ADC_SOURCE_VDD_GND = ((ADC_MUX_VREG2 << ADC_MUXN_BITS) + ADC_MUX_GND)
}

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.
uint16_t halMeasureVdd ( ADCRateType rate)
Measures VDD_PADS in millivolts at the specified sample rate Due to the conversions performed, this function takes slightly under 250us with a variation across successive conversions approximately +/-20mv of the average conversion.

Detailed Description

Sample A/D converter driver.

See adc.h for source code.

Note
The EmberZNet stack does use these functions.

To use the ADC system, include this file and ensure that halInternalInitAdc() is called whenever the microcontroller is started. Call halInternalSleepAdc() to sleep the module and halInternalInitAdc() to wake up the module.

A "user" is a separate thread of execution and usage. That is, internal Ember code is one user and clients are a different user. But a client that is calling the ADC in two different functions constitutes only one user, as long as the ADC access is not interleaved.

Note
This code does not allow access to the continuous reading mode of the ADC, which some clients may require.

Many functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus return values.

Sample A/D converter driver.

Note
EM35x ADC driver support is preliminary and may be changed in a future release

Macro Definition Documentation

◆ ADC_MUX_ADC0

#define ADC_MUX_ADC0   0x0

Channel 0 : ADC0 on PB5

◆ ADC_MUX_ADC1

#define ADC_MUX_ADC1   0x1

Channel 1 : ADC0 on PB6

◆ ADC_MUX_ADC2

#define ADC_MUX_ADC2   0x2

Channel 2 : ADC0 on PB7

◆ ADC_MUX_ADC3

#define ADC_MUX_ADC3   0x3

Channel 3 : ADC0 on PC1

◆ ADC_MUX_ADC4

#define ADC_MUX_ADC4   0x4

Channel 4 : ADC0 on PA4

◆ ADC_MUX_ADC5

#define ADC_MUX_ADC5   0x5

Channel 5 : ADC0 on PA5

◆ ADC_MUX_GND

#define ADC_MUX_GND   0x8

Channel 8 : VSS (0V) - not for high voltage range

◆ ADC_MUX_VREF

#define ADC_MUX_VREF   0xA

Channel A : VREF (1.2V)

◆ ADC_MUX_VREF2

#define ADC_MUX_VREF2   0x9

Channel 9 : VREF/2 (0.6V)

◆ ADC_MUX_VREG2

#define ADC_MUX_VREG2   0xB

Channel B : Regulator/2 (0.9V) - not for high voltage range

◆ ADC_MUXN_BITS

#define ADC_MUXN_BITS   (4)

◆ NUM_ADC_USERS

#define NUM_ADC_USERS   3U

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

Typedef Documentation

◆ ADCChannelType

typedef uint8_t ADCChannelType

A type for the channel enumeration.

◆ ADCRateType

typedef uint8_t ADCRateType

A type for the sample rate enumeration.

◆ ADCReferenceType

typedef uint8_t ADCReferenceType

A type for the reference voltage enumeration.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

ADCReferenceType Enumeration. Note: EM35x only supports one reference type: Internal.

Enumerator
ADC_REF_INT

Internal reference.

◆ anonymous enum

anonymous enum

ADCRateType enumeration. These rates are specified in the number of clock cycles That a conversion takes. The actual time taken will depend on the selected ADC clock rate. (Default is 6MHz)

Enumerator
ADC_SAMPLE_CLOCKS_32

Rate 32 cycles, 5 effective bits in ADC_DATA[15:11]

ADC_SAMPLE_CLOCKS_64

Rate 64 cycles, 6 effective bits in ADC_DATA[15:10]

ADC_SAMPLE_CLOCKS_128

Rate 128 cycles, 7 effective bits in ADC_DATA[15:9]

ADC_SAMPLE_CLOCKS_256

Rate 256 cycles, 8 effective bits in ADC_DATA[15:8]

ADC_SAMPLE_CLOCKS_512

Rate 512 cycles, 9 effective bits in ADC_DATA[15:7]

ADC_SAMPLE_CLOCKS_1024

Rate 1024 cycles, 10 effective bits in ADC_DATA[15:6]

ADC_SAMPLE_CLOCKS_2048

Rate 2048 cycles, 11 effective bits in ADC_DATA[15:5]

ADC_SAMPLE_CLOCKS_4096

Rate 4096 cycles, 12 effective bits in ADC_DATA[15:4]

◆ anonymous enum

anonymous enum

ADC rates for compatibility with EM2xx applications. For EM35x only applications, the ADC_SAMPLE_CLOCKS_nnn definitions should be used instead.

Enumerator
ADC_CONVERSION_TIME_US_32

Rate 32 us, 5 effective bits in ADC_DATA[15:11]

ADC_CONVERSION_TIME_US_64

Rate 64 us, 6 effective bits in ADC_DATA[15:10]

ADC_CONVERSION_TIME_US_128

Rate 128 us, 7 effective bits in ADC_DATA[15:9]

ADC_CONVERSION_TIME_US_256

Rate 256 us, 8 effective bits in ADC_DATA[15:8]

ADC_CONVERSION_TIME_US_512

Rate 512 us, 9 effective bits in ADC_DATA[15:7]

ADC_CONVERSION_TIME_US_1024

Rate 1024 us, 10 effective bits in ADC_DATA[15:6]

ADC_CONVERSION_TIME_US_2048

Rate 2048 us, 11 effective bits in ADC_DATA[15:5]

ADC_CONVERSION_TIME_US_4096

Rate 4096 us, 12 effective bits in ADC_DATA[15:4]

◆ anonymous enum

anonymous enum
Enumerator
ADC_SOURCE_ADC0_VREF2
ADC_SOURCE_ADC0_GND
ADC_SOURCE_ADC1_VREF2
ADC_SOURCE_ADC1_GND
ADC_SOURCE_ADC2_VREF2
ADC_SOURCE_ADC2_GND
ADC_SOURCE_ADC3_VREF2
ADC_SOURCE_ADC3_GND
ADC_SOURCE_ADC4_VREF2
ADC_SOURCE_ADC4_GND
ADC_SOURCE_ADC5_VREF2
ADC_SOURCE_ADC5_GND
ADC_SOURCE_ADC1_ADC0
ADC_SOURCE_ADC0_ADC1
ADC_SOURCE_ADC3_ADC2
ADC_SOURCE_ADC2_ADC3
ADC_SOURCE_ADC5_ADC4
ADC_SOURCE_GND_VREF2
ADC_SOURCE_VGND
ADC_SOURCE_VREF_VREF2
ADC_SOURCE_VREF
ADC_SOURCE_VREG2_VREF2
ADC_SOURCE_VDD_GND

◆ ADCUser

enum 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

Function Documentation

◆ emberCalibrateVref()

void emberCalibrateVref ( void )

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

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.

◆ halAdcCalibrate()

EmberStatus halAdcCalibrate ( ADCUser id )

Calibrates or recalibrates the ADC system.

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.

Parameters
id An ADC user.
Returns
One of the following:

◆ halAdcGetClock()

bool halAdcGetClock ( void )

Get ADC clock mode.

Returns
A true if the slow clock is selected.

◆ halAdcSetClock()

void halAdcSetClock ( bool slow )

Set ADC clock mode.

Parameters
slow A bool to select slow or normal clock.

◆ 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).

Use this function to get a human useful value.

Parameters
value An uint16_t to be converted.
Returns
Volts as signed fixed point with units 10^-4 Volts.

◆ 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.

◆ halInternalSleepAdc()

void halInternalSleepAdc ( void )

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

◆ halMeasureVdd()

uint16_t halMeasureVdd ( ADCRateType rate )

Measures VDD_PADS in millivolts at the specified sample rate Due to the conversions performed, this function takes slightly under 250us with a variation across successive conversions approximately +/-20mv of the average conversion.

Returns
A measurement of VDD_PADS in millivolts.

◆ 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
id An ADC user.
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:

◆ 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
id An ADC user.
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:

◆ halStartAdcConversion()

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

Starts an ADC conversion for the user specified by id .

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).

Parameters
id An ADC user.
reference Voltage reference to use, chosen from enum ADCReferenceType (fixed at ADC_REF_INT for the EM250).
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.
rate EM250 rate number (see the ADC EM250 rate enum).
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.