Measurement_api

Functions
USS_message_code	USS_configureUltrasonicMeasurement (USS_SW_Library_configuration *config)
	The following API configures USS module based on user configuration files "ussSwLib_userConfig.c" and "ussSwLib_userConfig.h". This API will internally invoke all USS Configuration APIs. In addition, this API will initialize the timer which will be used to generate delays such as the delay to stabilize PLL XTAL. More...
USS_message_code	USS_startUltrasonicMeasurement (USS_SW_Library_configuration *config, USS_capture_power_mode_option powerMode)
	The following API can be used to trigger a USS Capture via software trigger. NOTE: User must call "USS_configureUltrasonicMeasurement" before calling this API and USS trigger must be set to USS_Triger_Configuration_Software_Trigger. The API will perform the following operations: More...
USS_message_code	USS_startLowPowerUltrasonicCapture (USS_SW_Library_configuration *config)
	The following API has been power optimized for ultrasonic capture. The API controls the capture sequence selected by the user via the sequenceSelection member in USS_Measurement_Configuration structure. NOTE the API has been optimized for USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH1 capture mode. NOTE_1: User must call "USS_configureUltrasonicMeasurement" before calling this API and USS trigger must be set to USS_Triger_Configuration_Software_Trigger. To reduce power consumption between captures the device will: More...
USS_message_code	USS_stopUltrasonicMeasurement (USS_SW_Library_configuration *config, USS_stop_measurement_state stopMeasurementState)
	The following API can be used to stop any active USS capture. The user has the option to select USS state after conversion is stopped. The API will report if capture was successfully stopped or if any errors occurs while stopping the measurement. More...
void	USS_generateLPMDelay (USS_SW_Library_configuration *config, USS_low_power_mode_option lpmMode, uint16_t count)
	The following API can be used to generate a Low Power Mode Delay. The API allows to select the desired Low Power Mode. Global interrupts remain enable. The timer clock source for this delay is ACLK. Therefore the delay generate will be determined based on ACLK frequency (e.g. for count = 30 and ACLK freq = 32768 HZ a delay of ~915 msec will be generated. More...
void	USS_configAppTimerPeriod (USS_SW_Library_configuration *config, uint16_t count)
	The following API can be used to set the application timer period between USS measurements. The API allows to select the desired Low Power Mode. Global interrupts remain enable. The timer clock source for this background delay is ACLK. Therefore the timer period will be determined based on ACLK frequency (e.g. for count = 30 and ACLK freq = 32768 HZ a timer period of ~915 msec will be generated. This API will configure the config->systemConfig->measurementPeriod. More...
USS_message_code	USS_waitForAppTimerElapse (USS_SW_Library_configuration *config, USS_low_power_mode_option lpmMode)
	The following API can be used to wait until the background timer between USS measurements has elapsed. If the timer has elapsed prior to entering the API it will return USS_message_code_measurement_period_overflow, otherwise it will wait until the timer elapses, then return USS_message_code_no_error. Note1: USS_configAppTimerPeriod must be called prior to calling this function. More...

Detailed Description

Function Documentation

USS_configureUltrasonicMeasurement()

USS_message_code USS_configureUltrasonicMeasurement

(

USS_SW_Library_configuration *

config

)

The following API configures USS module based on user configuration files "ussSwLib_userConfig.c" and "ussSwLib_userConfig.h". This API will internally invoke all USS Configuration APIs. In addition, this API will initialize the timer which will be used to generate delays such as the delay to stabilize PLL XTAL.

Parameters

[in]

config

is a pointer to the USS SW Library user configuration

Returns

USS_message_code

References BENCHMARK_ENTRY_USS_LIB, _USS_SW_Library_configuration_::measurementConfig, _USS_Measurement_Configuration_::startRxEnCount, USS_registerSAPHInterruptCallback(), USS_SAPH_Interrupt_SEQDN, USSLIB_HAL_configureRxEnTimer(), and USSLIB_HAL_initGPIO().

Referenced by USS_resetUSSModule().

USS_startUltrasonicMeasurement()

USS_message_code USS_startUltrasonicMeasurement	(	USS_SW_Library_configuration *	config,
		USS_capture_power_mode_option	powerMode
	)

The following API can be used to trigger a USS Capture via software trigger.

NOTE: User must call "USS_configureUltrasonicMeasurement" before calling this API and USS trigger must be set to USS_Triger_Configuration_Software_Trigger.

The API will perform the following operations:

1. Verify if USS state is READY
   • If USS is not READY state (e.g. OFF or STANDBY) it will set USS to READY state following recommended USS Power Up sequence.
2. Triggers USS Capture
3. Wait in user selected power mode (USS_capture_power_mode_option) until acquisition sequence is done or any of the following errors occurs:
   • Data Error Abort
   • ASQ Time Mark 4 time out
4. Verifies that SDHS conversion has not been interrupted

Parameters

[in]	config	is a pointer to the USS SW Library user configuration
[in]	powerMode	The following are valid options: USS_capture_power_mode_active, USS_capture_power_mode_low_power_mode_0 USS_capture_power_mode_low_power_mode_1

Returns

USS_message_code

References commonClearUSSInterrupts(), commonEnableCaptureInterrupts(), commonIsconversionSuccessfull(), commonPowerUpUSS(), commonPrepareForUSSPowerUp(), commonSDHSRestoreSDHSDTCA(), commonWaitForconversion(), _USS_Measurement_Configuration_::eofSequenceState, _USS_SW_Library_configuration_::measurementConfig, _USS_Trigger_Configuration_::triggerConfig, _USS_SW_Library_configuration_::triggerConfig, USS_INTERRUPTS_MASK, USS_measurement_end_of_sequence_state_power_off, USS_message_code_no_error, USS_Triger_Configuration_Software_Trigger, and USSSWLIB_USS_interrupt_status.

Referenced by USS_calculateOffsets(), and USS_estimateDCoffset().

USS_startLowPowerUltrasonicCapture()

USS_message_code USS_startLowPowerUltrasonicCapture

(

USS_SW_Library_configuration *

config

)

The following API has been power optimized for ultrasonic capture. The API controls the capture sequence selected by the user via the sequenceSelection member in USS_Measurement_Configuration structure. NOTE the API has been optimized for USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH1 capture mode.

NOTE_1: User must call "USS_configureUltrasonicMeasurement" before calling this API and USS trigger must be set to USS_Triger_Configuration_Software_Trigger. To reduce power consumption between captures the device will:

• Put USS Module in OFF state
• Turn off USSXTAL
• Go to Low Power Mode 3 (LPM3) mode and wait for timer to expire to to trigger the next channel input. If there are no more channel captures pending. then this delay is skipped and the API returns control to the application.

NOTE2: The total delay between Channel acquisition sequences will be determined by the following USS SW library and USS module configurations:

• USS SW library configuration (Please refer to each library configuration parameter some more information):
  • restartLowPowerCaptureCount
  • ussXTALsettlingCount
  • ulpBiasDelay
• USS module (Please refer to device datasheet for typical UUPS power-up delay):
  • USS UUPS module power-up

Parameters

[in]

config

is a pointer to the USS SW Library user configuration

Returns

USS_message_code

References commonSDHSRestoreSDHSDTCA(), _USS_Measurement_Configuration_::eofSequenceState, GENERIC_SAPH_ASCTL0, GENERIC_SAPH_ASCTL1, GENERIC_SAPH_KEY, _USS_SW_Library_configuration_::measurementConfig, _USS_Measurement_Configuration_::restartLowPowerCaptureCount, _USS_Measurement_Configuration_::sequenceSelection, USS_CAPTURE_SEQUENCE_SELECTION_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH0_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH0_CH0_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH1_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH0_CH1_CH0_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH0_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH0_CH1_CH0, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH1_CH1, USS_CAPTURE_SEQUENCE_SELECTION_CH1_CH1_CH1_CH1, USS_commonTriggerSingleCapture(), and USS_message_code_no_error.

Referenced by USS_calculateOffsets(), USS_calibrateSignalGain(), and USS_estimateDCoffset().

USS_stopUltrasonicMeasurement()

USS_message_code USS_stopUltrasonicMeasurement	(	USS_SW_Library_configuration *	config,
		USS_stop_measurement_state	stopMeasurementState
	)

The following API can be used to stop any active USS capture. The user has the option to select USS state after conversion is stopped. The API will report if capture was successfully stopped or if any errors occurs while stopping the measurement.

Parameters

[in]	config	is a pointer to the USS SW Library user configuration
[in]	stopMeasurementState	specifies USS state after sequence is stopped. Possible values are: USS_stop_measurement_state_off USS_stop_measurement_state_ready USS_stop_measurement_state_stand_by

Returns

USS_message_code

References commonEnableCaptureInterrupts(), commonTimerGenerateLowPowerDelay(), USS_low_power_mode_option_low_power_mode_1, USS_message_code_error_occurred, USS_message_code_no_error, USS_SAPH_SEQ_ACQ_DN_INTERRUPT, USS_SAPH_SEQUENCE_STOPPED, USS_stop_measurement_turn_off_USS, USS_TIMER_EXPIRED_EVENT1_INTERRUPT, and USSSWLIB_USS_interrupt_status.

USS_generateLPMDelay()

void USS_generateLPMDelay	(	USS_SW_Library_configuration *	config,
		USS_low_power_mode_option	lpmMode,
		uint16_t	count
	)

The following API can be used to generate a Low Power Mode Delay. The API allows to select the desired Low Power Mode. Global interrupts remain enable. The timer clock source for this delay is ACLK. Therefore the delay generate will be determined based on ACLK frequency (e.g. for count = 30 and ACLK freq = 32768 HZ a delay of ~915 msec will be generated.

Parameters

[in]	config	is a pointer to the USS SW Library user configuration
[in]	lpmMode	selects the low power mode Possible values are: USS_low_power_mode_option_low_power_mode_0 USS_low_power_mode_option_low_power_mode_1 USS_low_power_mode_option_low_power_mode_2 USS_low_power_mode_option_low_power_mode_3
[in]	count	Determines the delay duration

Returns

none

References commonTimerGenerateLowPowerDelay().

USS_configAppTimerPeriod()

void USS_configAppTimerPeriod	(	USS_SW_Library_configuration *	config,
		uint16_t	count
	)

The following API can be used to set the application timer period between USS measurements. The API allows to select the desired Low Power Mode. Global interrupts remain enable. The timer clock source for this background delay is ACLK. Therefore the timer period will be determined based on ACLK frequency (e.g. for count = 30 and ACLK freq = 32768 HZ a timer period of ~915 msec will be generated. This API will configure the config->systemConfig->measurementPeriod.

Parameters

[in]	config	is a pointer to the USS SW Library user configuration
[in]	count	Determines the background timer period. Minimum = 655 (20 milliseconds) Maximum = 65535 (2 seconds)

Returns

none

References commonTimerConfigureTick(), _USS_System_Configuration_::measurementPeriod, _USS_SW_Library_configuration_::systemConfig, and USSSWLIB_USS_measurementPeriod.

USS_waitForAppTimerElapse()

USS_message_code USS_waitForAppTimerElapse	(	USS_SW_Library_configuration *	config,
		USS_low_power_mode_option	lpmMode
	)

The following API can be used to wait until the background timer between USS measurements has elapsed. If the timer has elapsed prior to entering the API it will return USS_message_code_measurement_period_overflow, otherwise it will wait until the timer elapses, then return USS_message_code_no_error.

Note1: USS_configAppTimerPeriod must be called prior to calling this function.

Parameters

[in]	config	is a pointer to the USS SW Library user configuration
[in]	lpmMode	selects the low power mode Possible values are: USS_low_power_mode_option_low_power_mode_0 USS_low_power_mode_option_low_power_mode_1 USS_low_power_mode_option_low_power_mode_2 USS_low_power_mode_option_low_power_mode_3

Returns

USS_message_code

References commonTimerWaitTickEvent(), USS_message_code_measurement_period_overflow, and USS_message_code_no_error.