File for the HAL APIs of ADC called by application layer. More...

Data Structures
struct	IotAdcConfig_t
	data structures for ioctl request More...

struct	IotAdcChStatus_t
	data structure for ioctl GetChStatus More...

struct	IotAdcChBuffer_t
	data structure for ioctl SetChBuffer setting channel data buffer is optional using this ioctl if client doesn't pass in data buffer for driver to use, callback is triggered for every ADC sample to pass data back to client as driver doesn't have buffer to accumulate data. As soon as callback returns, xConverted_Data becomes invalid. On the other hand however if client does pass a buffer for driver to use, callback is triggered only after driver has filled buffer with xBufLen samples, client buffer is passed back in callback as XConverted_Data whose life span is controlled by the client even after callback returns. More...

struct	IotAdcChain_t
	Some ADC host controller supports grouping multiple ADC channels into a chain. When the chain is triggered to sample ADC data, all ADC channels in the group are sampled in sequence so that client doesn't need to trigger each channel individually. Coverted ADC samples from such chain group can be passed back to the client with a single callback. This data structure is used for ioctl to define ADC chain setting. More...

Macros
#define	IOT_ADC_SUCCESS ( 0 )
	Error code returned by ADC driver. More...

#define	IOT_ADC_FAILED ( 1 )

#define	IOT_ADC_INVALID_VALUE ( 2 )

#define	IOT_ADC_NOT_OPEN ( 3 )

#define	IOT_ADC_FUNCTION_NOT_SUPPORTED ( 4 )

#define	IOT_ADC_CH_BUSY ( 5 )

Typedefs
typedef struct IotAdcDescriptor *	IotAdcHandle_t
	IotAdcHandle_t is the handle type returned by calling iot_adc_open(). This is initialized in open and returned to caller. The caller must pass this pointer to the rest of the ADC APIs.

typedef void(*	IotAdcCallback_t) (uint16_t pusConvertedData, void pvUserContext)
	adc notification callback type More...

Enumerations
enum	IotAdcChState_t { eChStateIdle, eChStateBusy }

enum	IotAdcIoctlRequest_t { eSetAdcConfig, eGetAdcConfig, eGetChStatus, eSetChBuffer, eSetAdcChain }
	adc ioctl request types. More...

Functions
IotAdcHandle_t	iot_adc_open (int32_t lAdc)
	Initializes ADC controller with default configuration. init ADC controller, enable ADC clock, reset HW FIFO, set default configuration parameters, etc. Also allocate all required resources for ADC operation such as software data buffer etc. More...

int32_t	iot_adc_close (IotAdcHandle_t const pxAdc)
	Close ADC controller. All pending operation will be cancelled, put ADC module in reset state or low power state if possible. Release all resources claimed during open call. More...

void	iot_adc_set_callback (IotAdcHandle_t const pxAdc, uint8_t ucAdcChannel, IotAdcCallback_t xAdcCallback, void *pvUserContext)
	Sets channel callback on availability of channel scan data. On availability of ADC scan data, the application is notified with a function callback. The callback function and user context for callback are set using iot_adc_set_callback. More...

int32_t	iot_adc_start (IotAdcHandle_t const pxAdc, uint8_t ucAdcChannel)
	Start data acquisition for ADC channel until iot_adc_stop API is called. data will be passed back to client using callback function. by default each callback will pass back one data sample, however if client has used ioctl to pass in data buffer, only when buffer is full will callback be triggered. More...

int32_t	iot_adc_stop (IotAdcHandle_t const pxAdc, uint8_t ucAdcChannel)
	Stop data acquisition for ADC channel. More...

int32_t	iot_adc_read_sample (IotAdcHandle_t const pxAdc, uint8_t ucAdcChannel, uint16_t *pusAdcSample)
	read one ADC data sample. This API will return one ADC sample. More...

int32_t	iot_adc_ioctl (IotAdcHandle_t const pxAdc, IotAdcIoctlRequest_t xRequest, void *const pvBuffer)
	Used for various ADC control functions. More...

Detailed Description

File for the HAL APIs of ADC called by application layer.

Macro Definition Documentation

◆ IOT_ADC_SUCCESS

#define IOT_ADC_SUCCESS ( 0 )

Error code returned by ADC driver.

ADC operation completed successfully.

◆ IOT_ADC_FAILED

#define IOT_ADC_FAILED ( 1 )

ADC operation failed.

◆ IOT_ADC_INVALID_VALUE

#define IOT_ADC_INVALID_VALUE ( 2 )

At least one parameter is invalid.

◆ IOT_ADC_NOT_OPEN

#define IOT_ADC_NOT_OPEN ( 3 )

ADC operation not possible unless ADC instance is opened.

◆ IOT_ADC_FUNCTION_NOT_SUPPORTED

#define IOT_ADC_FUNCTION_NOT_SUPPORTED ( 4 )

ADC operation not supported.

◆ IOT_ADC_CH_BUSY

#define IOT_ADC_CH_BUSY ( 5 )

ADC channel is busy at current time.

Typedef Documentation

◆ IotAdcCallback_t

typedef void( * IotAdcCallback_t) (uint16_t *pusConvertedData, void *pvUserContext)

adc notification callback type

Parameters

[in]	pvUserContext	User Context passed when setting the callback. This is not used or modified by the driver. The context is provided by the caller when setting the callback, and is passed back to the caller in the callback.
[out]	pusConvertedData	pointer to converted ADC sample data.

Enumeration Type Documentation

◆ IotAdcChState_t

enum IotAdcChState_t

Enumerator
eChStateIdle	ADC channel is idle.
eChStateBusy	ADC channel is busy.

◆ IotAdcIoctlRequest_t

enum IotAdcIoctlRequest_t

adc ioctl request types.

Enumerator
eSetAdcConfig	Set the ADC Configuration. Takes IotAdcConfig_t parameter.
eGetAdcConfig	Get the ADC Configuration. Returns results in IotAdcConfig_t parameter.
eGetChStatus	Get the Channel Status. Returns results in IotAdcChStatus_t parameter.
eSetChBuffer	Set the buffer for ADC values to be stored in. Takes IotAdcChBuffer_t parameter.
eSetAdcChain	ADC Chain for multiple ADC channels. Takes IotAdcChain_t parameter.

Function Documentation

◆ iot_adc_open()

IotAdcHandle_t iot_adc_open ( int32_t lAdc )

Initializes ADC controller with default configuration. init ADC controller, enable ADC clock, reset HW FIFO, set default configuration parameters, etc. Also allocate all required resources for ADC operation such as software data buffer etc.

Warning: Must be called prior to any other ADC api's so that a valid handle is obtained.; Once opened, the same ADC instance must be closed before calling open again.

Parameters

[in] lAdc The instance of ADC controller to initialize.

Returns

handle to the ADC controller on success
NULL, if
- invalid instance number
- open same instance more than once before closing it.

◆ iot_adc_close()

int32_t iot_adc_close ( IotAdcHandle_t const pxAdc )

Close ADC controller. All pending operation will be cancelled, put ADC module in reset state or low power state if possible. Release all resources claimed during open call.

Parameters

[in] pxAdc handle to ADC controller returned from iot_adc_open() call.

Returns

IOT_ADC_SUCCESS, on success;
IOT_I2C_INVALID_VALUE, if pxAdc is NULL
IOT_ADC_NOT_OPEN, if is not in open state (already closed).

◆ iot_adc_set_callback()

void iot_adc_set_callback	(	IotAdcHandle_t const	pxAdc,
		uint8_t	ucAdcChannel,
		IotAdcCallback_t	xAdcCallback,
		void *	pvUserContext
	)

Sets channel callback on availability of channel scan data. On availability of ADC scan data, the application is notified with a function callback. The callback function and user context for callback are set using iot_adc_set_callback.

Note: This callback is per AdcChannel for each handle.; If input handle or AdcChannel is invalid, or if callback function is NULL, this function silently takes no action.

Parameters

[in]	pxAdc	The Adc handle returned in the open() call.
[in]	ucAdcChannel	The Adc channel for which the callback is set
[in]	xAdcCallback	The callback function to be called on availability of ADC channel data.
[in]	pvUserContext	The user context to be passed when callback is called.

Example Callback Function For asychronous ADC calls, a callback function is used to signal when the async task is complete. This example uses a Semaphore to signal the completion.

static void prvAdcChCallback( uint16_t * pusConvertedData,
                              void * pvUserContext )
{
    BaseType_t xHigherPriorityTaskWoken;
    xSemaphoreGiveFromISR( xIotAdcSemaphore, &xHigherPriorityTaskWoken );
    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}

◆ iot_adc_start()

int32_t iot_adc_start	(	IotAdcHandle_t const	pxAdc,
		uint8_t	ucAdcChannel
	)

Start data acquisition for ADC channel until iot_adc_stop API is called. data will be passed back to client using callback function. by default each callback will pass back one data sample, however if client has used ioctl to pass in data buffer, only when buffer is full will callback be triggered.

Warning: iot_adc_set_callback() must be called prior to this in order to get notification when adc scan is complete and data is available

Note: iot_adc_set_callback() must be called prior to iot_adc_start().

Parameters

[in]	pxAdc.	The ADC handle returned in the open() call
[in]	ucAdcChannel.	The ADC channel to start data acquisition

Returns

IOT_ADC_SUCCESS on success
IOT_ADC_INVALID_VALUE, on NULL handle or invalid AdcChannel
IOT_ADC_NOT_OPEN if ADC has not been opened yet.
IOT_ADC_CH_BUSY if ADC operation has started but is not complete
IOT_ADC_FAILED if not callback function has been set. Example Asynchronous read
// ADC Instance to open
int32_t lAdcInstance = 0;
// Return value of ADC functions
int32_t lRetVal;
// ADC Channel to read
int32_t lAdcChannel = 0;
// User/Driver context; if necessary
void xUserContext = NULL;
// Open the ADC instance and get a handle.
xAdcHandle = iot_adc_open( lAdcInstance );
// assert(lRetVal == IOT_ADC_SUCCESS);
// set the callback function
iot_adc_set_callback( xAdcHandle, lAdcChannel, prvAdcChCallback, &xUserCntx );
// start channel data scan on channel
lRetVal = iot_adc_start( xAdcHandle, lAdcChannel );
// assert( IOT_ADC_SUCCESS == lRetVal );
// wait for the Adc operation to complete
lRetVal = xSemaphoreTake( xIotAdcSemaphore, lIotAdcChWaitTime );
// assert ( pdTRUE == lRetVal );
// stop channel data scan
lRetVal = iot_adc_stop( xAdcHandle, lAdcChannel );
assert( IOT_ADC_SUCCESS == lRetVal );
// close ADC module
lRetVal = iot_adc_close( xAdcHandle );
// assert( IOT_ADC_SUCCESS == lRetVal );

◆ iot_adc_stop()

int32_t iot_adc_stop	(	IotAdcHandle_t const	pxAdc,
		uint8_t	ucAdcChannel
	)

Stop data acquisition for ADC channel.

Parameters

[in]	pxAdc.	The ADC handle returned in the open() call
[in]	ucAdcChannel.	The ADC channel to stop data acquisition

Returns

IOT_ADC_SCUCCESS on success
IOT_ADC_INVALID_VALUE, on NULL handle or invalid AdcChannel
IOT_ADC_NOT_OPEN if Adc has been closed without re-opening.

◆ iot_adc_read_sample()

int32_t iot_adc_read_sample	(	IotAdcHandle_t const	pxAdc,
		uint8_t	ucAdcChannel,
		uint16_t *	pusAdcSample
	)

read one ADC data sample. This API will return one ADC sample.

Parameters

[in]	pxAdc.	The ADC handle returned in the open() call
[in]	ucAdcChannel.	The ADC channel to read data from
[out]	pusAdcSample.	ADC channel read sample value

Returns

IOT_ADC_SCUCCESS on success
IOT_ADC_INVALID_VALUE, on NULL handle or invalid AdcChannel
IOT_ADC_CH_BUSY if ADC operation not complete.
IOT_ADC_NOT_OPEN if Adc has been closed without re-opening. Example Synchronous read
// ADC Instance to open
int32_t lAdcInstance = 0;
// ADC Channel to read
int32_t lAdcChannel = 0;
// Declare and ADC handle
IotAdcHandle_t xAdcHandle;
// Return value of ADC functions
int32_t lRetVal;
// ADC value read
uint16_t usSample;
// Open the ADC instance and get a handle.
xAdcHandle = iot_adc_open( lAdcInstance );
// assert(lRetVal == IOT_ADC_SUCCESS);
// Read sample from ADC channel
lRetVal = iot_adc_read_sample( xAdcHandle, lAdcChannel, &usSample);
// assert(lRetVal == IOT_ADC_SUCCESS);
// Close the ADC instance and get a handle.
lRetVal = iot_adc_close( xAdcHandle );
// assert(lRetVal == IOT_ADC_SUCCESS);

◆ iot_adc_ioctl()

int32_t iot_adc_ioctl	(	IotAdcHandle_t const	pxAdc,
		IotAdcIoctlRequest_t	xRequest,
		void *const	pvBuffer
	)

Used for various ADC control functions.

Parameters

[in]	pxAdc	The Adc handle returned in the open() call.
[in]	xRequest	ioctl request defined by IotAdcIoctlRequest_s enums
	[in/out]	pvBuffer data buffer for ioctl request
[in]	pvBuffer	size

Returns

IOT_ADC_SCUCCESS on success
IOT_ADC_INVALID_VALUE, on NULL handle or invalid request or NULL or invalid buffer pointer
IOT_ADC_CH_BUSY if ADC operation not complete.
IOT_ADC_NOT_OPEN if Adc has been closed without re-opening.
IOT_ADC_FAILED if invalid ADC chain is requested.
IOT_ADC_FUNCTION_NOT_SUPPORTED only valid for eSetAdcChain, if feature not supported

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IOT_ADC_SUCCESS

◆ IOT_ADC_FAILED

◆ IOT_ADC_INVALID_VALUE

◆ IOT_ADC_NOT_OPEN

◆ IOT_ADC_FUNCTION_NOT_SUPPORTED

◆ IOT_ADC_CH_BUSY

Typedef Documentation

◆ IotAdcCallback_t

Enumeration Type Documentation

◆ IotAdcChState_t

◆ IotAdcIoctlRequest_t

Function Documentation

◆ iot_adc_open()

◆ iot_adc_close()

◆ iot_adc_set_callback()

◆ iot_adc_start()

◆ iot_adc_stop()

◆ iot_adc_read_sample()

◆ iot_adc_ioctl()