ADC Control#

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

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

@0 {

PRIORITIZE_BEACONS_BASED_ON_PARENT_CLASSIFICATION = 0x0001

PRIORITIZE_BEACONS_BASED_ON_TC_CONNECTVITY = 0x0002

TC_CONNECTIVITY = 0x0010

LONG_UPTIME = 0x0020

BAD_PARENT_CONNECTIVITY = 0x0040

EMBER_OUTGOING_MESSAGES = 0x0001

EMBER_INCOMING_MESSAGES = 0x0002

EMBER_RADIO_IS_ON = 0x0004

EMBER_TRANSPORT_ACTIVE = 0x0008

EMBER_APS_LAYER_ACTIVE = 0x0010

EMBER_ASSOCIATING = 0x0020

EMBER_ZLL_TOUCH_LINKING = 0x0040

EMBER_NETWORK_TIMEOUT_REQUEST = 0x0200

EMBER_SEND_ORPHAN_NOTIFICATION = 0x0400

EMBER_MAC_DATA_POLL_SUPER_RETRY = 0x0800

INITIAL = 0x0000

SCAN_FOR_TOUCH_LINK = 0x0001

SCAN_FOR_DEVICE_INFORMATION = 0x0002

SCAN_FOR_IDENTIFY = 0x0004

SCAN_FOR_RESET = 0x0008

TARGET_NETWORK_FOUND = 0x0010

ABORTING_TOUCH_LINK = 0x0020

SCAN_COMPLETE = 0x0040

TOUCH_LINK_TARGET = 0x0080

FORMING_NETWORK = 0x0100

RESETTING_TO_FACTORY_NEW = 0x0200

ADC_REF_INT = 42U

TOKEN_COUNT

COMM_SERIAL = 0x01

COMM_RADIO = 0x02

}

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

enum

@1 {

EMBER_POLL_TIMEOUT_10_SECONDS = 0

EMBER_POLL_TIMEOUT_2_MINUTES = 1

EMBER_POLL_TIMEOUT_4_MINUTES = 2

EMBER_POLL_TIMEOUT_8_MINUTES = 3

EMBER_POLL_TIMEOUT_16_MINUTES = 4

EMBER_POLL_TIMEOUT_32_MINUTES = 5

EMBER_POLL_TIMEOUT_64_MINUTES = 6

EMBER_POLL_TIMEOUT_128_MINUTES = 7

EMBER_POLL_TIMEOUT_256_MINUTES = 8

EMBER_POLL_TIMEOUT_512_MINUTES = 9

EMBER_POLL_TIMEOUT_1024_MINUTES = 10

EMBER_POLL_TIMEOUT_2048_MINUTES = 11

EMBER_POLL_TIMEOUT_4096_MINUTES = 12

EMBER_POLL_TIMEOUT_8192_MINUTES = 13

EMBER_POLL_TIMEOUT_16384_MINUTES = 14

EMBER_RADIO_POWER_MODE_RX_ON

EMBER_RADIO_POWER_MODE_OFF

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

@2 {

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

@3 {

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)

}

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.

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.

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

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

@0#

@0

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

Enumerator
PRIORITIZE_BEACONS_BASED_ON_PARENT_CLASSIFICATION
PRIORITIZE_BEACONS_BASED_ON_TC_CONNECTVITY
TC_CONNECTIVITY
LONG_UPTIME
BAD_PARENT_CONNECTIVITY
EMBER_OUTGOING_MESSAGES	There are messages waiting for transmission.
EMBER_INCOMING_MESSAGES	One or more incoming messages being processed.
EMBER_RADIO_IS_ON	The radio is currently powered on. On sleepy devices, the radio is turned off when not in use. On non-sleepy devices (EMBER_COORDINATOR, EMBER_ROUTER, or EMBER_END_DEVICE), the radio is always on.
EMBER_TRANSPORT_ACTIVE	The transport layer has messages awaiting an ACK.
EMBER_APS_LAYER_ACTIVE	The ZigBee APS layer has messages awaiting an ACK.
EMBER_ASSOCIATING	The node is currently trying to associate with a ZigBee PRO network.
EMBER_ZLL_TOUCH_LINKING	The node is currently touch linking.
EMBER_NETWORK_TIMEOUT_REQUEST	Network Timeout Request Event.
EMBER_SEND_ORPHAN_NOTIFICATION	Sending Orphan Notification Event.
EMBER_MAC_DATA_POLL_SUPER_RETRY	MAC Data Poll Super Retry Event .
INITIAL
SCAN_FOR_TOUCH_LINK
SCAN_FOR_DEVICE_INFORMATION
SCAN_FOR_IDENTIFY
SCAN_FOR_RESET
TARGET_NETWORK_FOUND
ABORTING_TOUCH_LINK
SCAN_COMPLETE
TOUCH_LINK_TARGET
FORMING_NETWORK
RESETTING_TO_FACTORY_NEW
ADC_REF_INT	Internal reference.
TOKEN_COUNT
COMM_SERIAL
COMM_RADIO

@1#

@1

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
EMBER_POLL_TIMEOUT_10_SECONDS
EMBER_POLL_TIMEOUT_2_MINUTES
EMBER_POLL_TIMEOUT_4_MINUTES
EMBER_POLL_TIMEOUT_8_MINUTES
EMBER_POLL_TIMEOUT_16_MINUTES
EMBER_POLL_TIMEOUT_32_MINUTES
EMBER_POLL_TIMEOUT_64_MINUTES
EMBER_POLL_TIMEOUT_128_MINUTES
EMBER_POLL_TIMEOUT_256_MINUTES
EMBER_POLL_TIMEOUT_512_MINUTES
EMBER_POLL_TIMEOUT_1024_MINUTES
EMBER_POLL_TIMEOUT_2048_MINUTES
EMBER_POLL_TIMEOUT_4096_MINUTES
EMBER_POLL_TIMEOUT_8192_MINUTES
EMBER_POLL_TIMEOUT_16384_MINUTES
EMBER_RADIO_POWER_MODE_RX_ON
EMBER_RADIO_POWER_MODE_OFF
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]

@2#

@2

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]

@3#

@3

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

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.

halMeasureVdd#

uint16_t halMeasureVdd (ADCRateType rate)

Parameters

Type	Direction	Argument Name	Description
ADCRateType	N/A	rate

Returns

A measurement of VDD_PADS in millivolts.