GPADC Adapter

General Purpose Analog-Digital Converter adapter. More...

Files
file	ad_gpadc.h
	GPADC adapter API.

Data Structures
struct	ad_gpadc_io_conf
	GPADC I/O configuration. More...
struct	ad_gpadc_controller_conf
	GPADC controller configuration. More...

Macros
#define	CONFIG_GPADC_USE_ASYNC_TRANSACTIONS   (1)
	Controls whether GPADC asynchronous transaction API will be used. More...
#define	CONFIG_GPADC_USE_SYNC_TRANSACTIONS   (1)
	Controls whether GPADC synchronous transaction API will be used. More...
#define	HW_GPADC_1   ((void *)GPADC_BASE)
	GPADC controller instance.

Typedefs
typedef struct ad_gpadc_io_conf	ad_gpadc_io_conf_t
	GPADC I/O configuration. More...
typedef hw_gpadc_config_t	ad_gpadc_driver_conf_t
	GPADC driver configuration. More...
typedef struct ad_gpadc_controller_conf	ad_gpadc_controller_conf_t
	GPADC controller configuration. More...
typedef void *	ad_gpadc_handle_t
	GPADC Handle returned by ad_gpadc_open()
typedef void(*	ad_gpadc_user_cb) (void *user_data, int value)
	GPADC adapter callback function. More...

Enumerations
enum	AD_GPADC_ERROR
	enum with return values of API calls

Functions
void	ad_gpadc_init (void)
	Initialize GPADC adapter and some required variables. More...
int	ad_gpadc_read_nof_conv (const ad_gpadc_handle_t handle, int nof_conv, uint16_t *outbuf)
	Read synchronously nof_conv conversions from the selected source. More...
int	ad_gpadc_read_nof_conv_async (const ad_gpadc_handle_t handle, int nof_conv, uint16_t *outbuf, ad_gpadc_user_cb read_async_cb, void *user_data)
	Read asynchronously nof_conv conversions from the selected source. More...
uint16_t	ad_gpadc_get_source_max (const ad_gpadc_driver_conf_t *drv)
	Return maximum value that can be read for ADC source. More...
ad_gpadc_handle_t	ad_gpadc_open (const ad_gpadc_controller_conf_t *conf)
	Open GPADC controller. More...
int	ad_gpadc_reconfig (const ad_gpadc_handle_t p, const ad_gpadc_driver_conf_t *drv)
	Reconfigure GPADC controller. More...
int	ad_gpadc_io_config (const HW_GPADC_ID id, const ad_gpadc_io_conf_t *io, AD_IO_CONF_STATE state)
	Initialize controller pins to on / off io configuration. More...
int	ad_gpadc_close (ad_gpadc_handle_t p, bool force)
	Close GPADC controller. More...
__STATIC_FORCEINLINE int	ad_gpadc_conv_to_temp_x100 (const ad_gpadc_driver_conf_t *drv, uint16_t raw_value)
	Convert raw value read from GPADC to temperature value in hundredths of degree Celsius. More...
uint16_t	ad_gpadc_conv_raw_to_batt_mvolt (const ad_gpadc_driver_conf_t *drv, uint32_t raw_value)
	Convert raw value read from GPADC to battery voltage in mV. The same configuration which was used to obtain the adc_value is needed for the conversion. More...
int	ad_gpadc_conv_to_mvolt (const ad_gpadc_driver_conf_t *drv, uint32_t raw_value)
	Convert raw value read from GPADC to voltage in mV. The same configuration which was used to obtain the adc_value is needed for the conversion. More...

Detailed Description

General Purpose Analog-Digital Converter adapter.

Macro Definition Documentation

CONFIG_GPADC_USE_ASYNC_TRANSACTIONS

#define CONFIG_GPADC_USE_ASYNC_TRANSACTIONS   (1)

Controls whether GPADC asynchronous transaction API will be used.

If the API is not to be used, setting this macro to 0 will save retention RAM, namely the callback pointer and its argument.

CONFIG_GPADC_USE_SYNC_TRANSACTIONS

#define CONFIG_GPADC_USE_SYNC_TRANSACTIONS   (1)

Controls whether GPADC synchronous transaction API will be used.

Warning

If an application based on FreeRTOS employs the RCX as a low power clock or uses BLE, the sys_adc API is enabled forcefully, because is essential for critical tasks, such as RCX and RF calibration. In that case, the synched GPADC transactions feature is enabled as well and cannot be disabled by the application, because is mandatory to perform the aforementioned critical actions.

Typedef Documentation

ad_gpadc_controller_conf_t

typedef struct ad_gpadc_controller_conf ad_gpadc_controller_conf_t

GPADC controller configuration.

Configuration of GPADC controller

ad_gpadc_driver_conf_t

typedef hw_gpadc_config_t ad_gpadc_driver_conf_t

GPADC driver configuration.

Configuration of GPADC low level driver(s)

Note

There may be more than one driver configurations needed (e.g DMA)

ad_gpadc_io_conf_t

typedef struct ad_gpadc_io_conf ad_gpadc_io_conf_t

GPADC I/O configuration.

GPADC I/O configuration

ad_gpadc_user_cb

typedef void(* ad_gpadc_user_cb) (void *user_data, int value)

GPADC adapter callback function.

Parameters

[in]	user_data	pointer to user data
[in]	value	number of remaining conversions

Function Documentation

ad_gpadc_close()

int ad_gpadc_close	(	ad_gpadc_handle_t	p,
		bool	force
	)

Close GPADC controller.

This function:

• Aborts ongoing transactions
• De-initializes the drivers associated with the controller
• Resets controller interface IOs (as specified in ad_gpadc_open())
• Releases the controller resources

Parameters

[in]	p	pointer returned from ad_gpadc_open()
[in]	force	force close even if an async read is pending

Returns

0: success, <0: error code

ad_gpadc_conv_raw_to_batt_mvolt()

uint16_t ad_gpadc_conv_raw_to_batt_mvolt	(	const ad_gpadc_driver_conf_t *	drv,
		uint32_t	raw_value
	)

Convert raw value read from GPADC to battery voltage in mV. The same configuration which was used to obtain the adc_value is needed for the conversion.

Parameters

[in]	drv	GPADC driver configuration structure, NULL to use the current ADC settings
[in]	raw_value	value returned from ad_gpadc_read_nof_conv() or ad_gpadc_read_nof_conv_async()

Returns

battery voltage in mV

ad_gpadc_conv_to_mvolt()

int ad_gpadc_conv_to_mvolt	(	const ad_gpadc_driver_conf_t *	drv,
		uint32_t	raw_value
	)

Convert raw value read from GPADC to voltage in mV. The same configuration which was used to obtain the adc_value is needed for the conversion.

Parameters

[in]	drv	GPADC driver configuration structure, NULL to use the current ADC settings
[in]	raw_value	value returned from ad_gpadc_read_nof_conv() or ad_gpadc_read_nof_conv_async()

Returns

voltage in mV

ad_gpadc_conv_to_temp_x100()

__STATIC_FORCEINLINE int ad_gpadc_conv_to_temp_x100	(	const ad_gpadc_driver_conf_t *	drv,
		uint16_t	raw_value
	)

Convert raw value read from GPADC to temperature value in hundredths of degree Celsius.

Parameters

[in]	drv	GPADC driver configuration structure, NULL to use the current ADC settings
[in]	raw_value	raw value returned from ad_gpadc_read_nof_conv() or ad_gpadc_read_nof_conv_async()

Returns

value of temperature in hundredths of degree Celsius

ad_gpadc_get_source_max()

uint16_t ad_gpadc_get_source_max

(

const ad_gpadc_driver_conf_t *

drv

)

Return maximum value that can be read for ADC source.

A GPADC raw value can have 10 to 16 valid bits (left aligned) depending on oversampling specified in source description. This function will return value 0x3FF, 0x7FF, 0xFFF, 0x1FFF, 0x3FFF, 0x7FFF or 0xFFFF depending on oversampling, offering a right-aligned representation for the maximum value that the GPADC can return (i.e. when the measured voltage equals to Vref).

Parameters

[in]

drv

GPADC driver configuration structure

Returns

value 0x3FF, 0x7FF, 0xFFF, 0x1FFF, 0x3FFF, 0x7FFF or 0xFFFF

ad_gpadc_init()

void ad_gpadc_init

(

void

)

Initialize GPADC adapter and some required variables.

Warning

Do not call this function directly. It is called automatically during power manager initialization.

ad_gpadc_io_config()

int ad_gpadc_io_config	(	const HW_GPADC_ID	id,
		const ad_gpadc_io_conf_t *	io,
		AD_IO_CONF_STATE	state
	)

Initialize controller pins to on / off io configuration.

This function should be called for setting pins to the correct level before external devices are powered up (e.g on system init). It does not need to be called before every ad_gpadc_open() call.

Parameters

[in]	id	controller instance
[in]	io	controller io configuration
[in]	state	on/off io configuration

Returns

0: success, <0: error code

ad_gpadc_open()

ad_gpadc_handle_t ad_gpadc_open

(

const ad_gpadc_controller_conf_t *

conf

)

Open GPADC controller.

This function:

• Acquires the resources needed for using the controller
• Configures the controller interface IOs
• Initializes the drivers associated with the controller

Parameters

[in]

conf

controller configuration

Returns

>0: pointer to adapter instance - should be used in subsequent API calls, <0: error code

Note

The function will block until it acquires all controller resources

ad_gpadc_read_nof_conv()

int ad_gpadc_read_nof_conv	(	const ad_gpadc_handle_t	handle,
		int	nof_conv,
		uint16_t *	outbuf
	)

Read synchronously nof_conv conversions from the selected source.

This function starts synchronous measurement read. Blocking read - caller task will block until the resource becomes available

Parameters

[in]	handle	handle to GPADC source
[in]	nof_conv	number of conversions to be delivered. Must be non-zero
[out]	outbuf	pointer to conversion results buffer. Output buffer contains raw values

See also

ad_gpadc_open()

ad_gpadc_close()

Returns

0 on success, negative value on error

ad_gpadc_read_nof_conv_async()

int ad_gpadc_read_nof_conv_async	(	const ad_gpadc_handle_t	handle,
		int	nof_conv,
		uint16_t *	outbuf,
		ad_gpadc_user_cb	read_async_cb,
		void *	user_data
	)

Read asynchronously nof_conv conversions from the selected source.

This function starts asynchronous measurement read. Non blocking read operation

Parameters

[in]	handle	handle to GPADC source
[in]	nof_conv	number of conversions to be delivered. Must be non-zero
[out]	outbuf	pointer to conversion results buffer. Output buffer contains raw values
[in]	read_async_cb	user callback fired after read operation completes
[in]	user_data	pointer to user data passed to callback

See also

ad_gpadc_open()

ad_gpadc_close()

Returns

0 on success, negative value on error

ad_gpadc_reconfig()

int ad_gpadc_reconfig	(	const ad_gpadc_handle_t	p,
		const ad_gpadc_driver_conf_t *	drv
	)

Reconfigure GPADC controller.

This function will apply a new GPADC driver configuration.

Parameters

[in]	p	pointer returned from ad_gpadc_open()
[in]	drv	GPADC driver configuration structure

Returns

0: success, <0: error code