Measurement/Device control module. More...

Collaboration diagram for Measurement/Device Control:

Data Structures
struct	argus_meas_frame_t
	The device measurement configuration structure. More...

Macros
#define	ARGUS_RAW_DATA_VALUES 132U

#define	ARGUS_RAW_DATA_SIZE (3U * ARGUS_RAW_DATA_VALUES)

#define	ARGUS_AUX_CHANNEL_COUNT (5U)

#define	ARGUS_AUX_DATA_SIZE (3U * ARGUS_AUX_CHANNEL_COUNT)

Functions
status_t	Argus_StartMeasurementTimer (argus_hnd_t *hnd, argus_measurement_ready_callback_t cb)
	Starts the timer based measurement cycle asynchronously.

status_t	Argus_StopMeasurementTimer (argus_hnd_t *hnd)
	Stops the timer based measurement cycle.

status_t	Argus_TriggerMeasurement (argus_hnd_t *hnd, argus_measurement_ready_callback_t cb)
	Triggers a single measurement frame asynchronously.

bool	Argus_IsDataEvaluationPending (argus_hnd_t *hnd)
	Determines whether a data evaluation is pending.

bool	Argus_IsTimerMeasurementActive (argus_hnd_t *hnd)
	Determines if the device if active with timer based measurements.

status_t	Argus_Abort (argus_hnd_t *hnd)
	Stops the currently ongoing measurements and SPI activity immediately.

status_t	Argus_GetStatus (argus_hnd_t *hnd)
	Checks the state of the device/driver.

status_t	Argus_Ping (argus_hnd_t *hnd)
	Tests the connection to the device by sending a ping message.

status_t	Argus_EvaluateData (argus_hnd_t hnd, argus_results_t res)
	Evaluates measurement data from the raw sensor readout data.

status_t	Argus_EvaluateDataDebug (argus_hnd_t hnd, argus_results_t res, argus_results_debug_t *dbg)
	Evaluates measurement data from the raw sensor readout data.

status_t	Argus_ExecuteXtalkCalibrationSequence (argus_hnd_t *hnd)
	Executes a crosstalk calibration measurement.

status_t	Argus_ExecuteRelativeRangeOffsetCalibrationSequence (argus_hnd_t *hnd)
	Executes a relative range offset calibration measurement.

status_t	Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence (argus_hnd_t *hnd, q9_22_t targetRange)
	Executes an absolute range offset calibration measurement.

Detailed Description

Measurement/Device control module.

Measurement/Device Operation

This module contains measurement and device control specific definitions and methods.

Macro Definition Documentation

◆ ARGUS_AUX_CHANNEL_COUNT

#define ARGUS_AUX_CHANNEL_COUNT (5U)

The number channels for auxiliary measurements readout.

◆ ARGUS_AUX_DATA_SIZE

#define ARGUS_AUX_DATA_SIZE (3U * ARGUS_AUX_CHANNEL_COUNT)

Size of the auxiliary data in bytes.

◆ ARGUS_RAW_DATA_SIZE

#define ARGUS_RAW_DATA_SIZE (3U * ARGUS_RAW_DATA_VALUES)

Size of the raw data in bytes.

◆ ARGUS_RAW_DATA_VALUES

#define ARGUS_RAW_DATA_VALUES 132U

Number of raw data values.

Function Documentation

◆ Argus_Abort()

status_t Argus_Abort ( argus_hnd_t * hnd )

Stops the currently ongoing measurements and SPI activity immediately.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_EvaluateData()

status_t Argus_EvaluateData	(	argus_hnd_t *	hnd,
		argus_results_t *	res
	)

Evaluates measurement data from the raw sensor readout data.

This function must be called after each completion of a measurement cycle. The completion of a measurement cycle is communicated by the API via the invocation of the measurement data ready callback. The callback is installed in the API when new measurements are started either via the Argus_TriggerMeasurement or via the Argus_StartMeasurementTimer functions.

This function evaluates measurement values like distances, amplitudes states and auxiliary values like temperature or voltage values from the raw sensor readout data obtained from the device during the measurement cycle. A pointer to a argus_results_t data structure must be passed where all the evaluated values will be written to. The structure must persist during the whole execution of the Argus_EvaluateData function.

In addition to the evaluation of measurement data, the function feeds back the obtained information to the device in order to optimize its performance with respect to the ambient conditions, utilizing the so called Dynamic Configuration Adaption (DCA) feature.

Furthermore, several calibration algorithm are applied to the data.

If the function is called without any data ready to be evaluated from the measurement module, the error code ERROR_ARGUS_BUFFER_EMPTY is returned and not data is written to the passed argus_results_t data structure.

Note: The call to this function is mandatory for each finished measurement cycle, i.e. for each call to the measurement data ready callback. If the function is not called, the data is not evaluated and the internal raw data buffers are not freed. In that case, they can not be reused for the next measurement and the API can not start new measurements. There are up to two internal buffers available, the to callback is called twice before the API must wait for the data evaluation to finish.

Parameters

hnd	The API handle; contains all internal states and data.
res	A pointer to the results structure that will be populated with evaluated data.

Returns: Returns the status (STATUS_OK on success).

Examples: 01_simple_example.c, 01_simple_example_with_hal_self_test.c, 02_advanced_example.c, 02_advanced_example_with_hal_self_test.c, 03_high_speed_example.c, and 04_multi_device_example.c.

◆ Argus_EvaluateDataDebug()

status_t Argus_EvaluateDataDebug	(	argus_hnd_t *	hnd,
		argus_results_t *	res,
		argus_results_debug_t *	dbg
	)

Evaluates measurement data from the raw sensor readout data.

This function enhances the Argus_EvaluateData by adding additional debug data into a specified debug data structure (dbg). If the dbg is null, the function is eqivalent to the Argus_EvaluateData function. This, see Argus_EvaluateData for reference.

Parameters

hnd	The API handle; contains all internal states and data.
res	A pointer to the results structure that will be populated with evaluated data.
dbg	An optional pointer (can be null) to the debug data structure.

Returns: Returns the status (STATUS_OK on success).

Examples: 05_simple_example_debug.c.

◆ Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence()

status_t Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence	(	argus_hnd_t *	hnd,
		q9_22_t	targetRange
	)

Executes an absolute range offset calibration measurement.

This function immediately triggers an absolute range offset calibration measurement sequence. The ordinary measurement activity is suspended while the calibration is ongoing.

In order to perform a relative range offset calibration, a flat calibration target must be setup perpendicular to the sensors field-of-view.

                 AFBR-S50 ToF Sensor
          #|
          #|                                         |
          #|-----+                                   |
          #| RX  |                                   |
Reference #|----++                                   | Calibration
    Plane #| TX |                                    | Target
          #|----+                                    |
          #|                                         |
          #| <------- targetRange -----------------> |

There are two options to run the offset calibration: relative and absolute.

Relative (Argus_ExecuteRelativeRangeOffsetCalibrationSequence): when the absolute distance is not essential or the distance to the calibration target is not known, the relative method can be used to compensate the relative pixel range offset w.r.t. the average range. The absolute or global range offset is not changed.
Absolute (Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence): when the absolute distance is essential and the distance to the calibration target is known, the absolute method can be used to calibrate the absolute measured distance. Additionally, the relative pixel offset w.r.t. the average range is also compensated.

After calibration has finished successfully, the obtained data is applied immediately and can be read from the API using the Argus_GetCalibrationPixelRangeOffsets or Argus_GetCalibrationGlobalRangeOffsets function.

Parameters

hnd	The API handle; contains all internal states and data.
targetRange	The absolute range between the reference plane and the calibration target in meter an Q9.22 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_ExecuteRelativeRangeOffsetCalibrationSequence()

status_t Argus_ExecuteRelativeRangeOffsetCalibrationSequence ( argus_hnd_t * hnd )

Executes a relative range offset calibration measurement.

This function immediately triggers a relative range offset calibration measurement sequence. The ordinary measurement activity is suspended while the calibration is ongoing.

In order to perform a relative range offset calibration, a flat calibration target must be setup perpendicular to the sensors field-of-view.

                 AFBR-S50 ToF Sensor
          #|
          #|                                         |
          #|-----+                                   |
          #| RX  |                                   |
Reference #|----++                                   | Calibration
    Plane #| TX |                                    | Target
          #|----+                                    |
          #|                                         |
          #| <------- targetRange -----------------> |

There are two options to run the offset calibration: relative and absolute.

Relative (Argus_ExecuteRelativeRangeOffsetCalibrationSequence): when the absolute distance is not essential or the distance to the calibration target is not known, the relative method can be used to compensate the relative pixel range offset w.r.t. the average range. The absolute or global range offset is not changed.
Absolute (Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence): when the absolute distance is essential and the distance to the calibration target is known, the absolute method can be used to calibrate the absolute measured distance. Additionally, the relative pixel offset w.r.t. the average range is also compensated.

After calibration has finished successfully, the obtained data is applied immediately and can be read from the API using the Argus_GetCalibrationPixelRangeOffsets or Argus_GetCalibrationGlobalRangeOffsets function.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_ExecuteXtalkCalibrationSequence()

status_t Argus_ExecuteXtalkCalibrationSequence ( argus_hnd_t * hnd )

Executes a crosstalk calibration measurement.

This function immediately triggers a crosstalk vector calibration measurement sequence. The ordinary measurement activity is suspended while the calibration is ongoing.

In order to perform a crosstalk calibration, the reflection of the transmitted signal must be kept from the receiver side, by either covering the TX completely (or RX respectively) or by setting up an absorbing target at far distance.

After calibration has finished successfully, the obtained data is applied immediately and can be read from the API using the Argus_GetCalibrationCrosstalkVectorTable function.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetStatus()

status_t Argus_GetStatus ( argus_hnd_t * hnd )

Checks the state of the device/driver.

Returns the current module status or error if any.

     See the following for a list of errors:

     Status:
     - Idle/OK: Device and SPI interface are idle (== #STATUS_IDLE).
     - Busy: Device or SPI interface are busy (== #STATUS_BUSY).
     - Initializing: The modules and devices are currently initializing
                     (== #STATUS_INITIALIZING).
     .

     Error:
     - Not Initialized: The modules (or any submodule) has not been
                        initialized yet (== #ERROR_NOT_INITIALIZED).
     - Not Connected: No device has been connected (or connection errors
                      have occurred) (== #ERROR_ARGUS_NOT_CONNECTED).
     - Timeout: A previous frame measurement has not finished within a
                specified time (== #ERROR_TIMEOUT).
     .

Note: Note that this function returns the actual busy state. This means that it will return STATUS_IDLE during the pause between two consecutive measurement frames. If the device is active with timer based measurements (i.e. started via the Argus_StartMeasurementTimer function), the return state switches from idle to busy and back periodically. Use the Argus_IsTimerMeasurementActive function in order to determine if the device is active with timer based measurements.; Note also that the device might reject configuration parameter update despite the status is STATUS_IDLE. This is due to the fact that the internal raw data buffers are still busy and require to be freed by passing them to the Argus_EvaluateData function. Use the Argus_IsDataEvaluationPending function to see whether any of the raw data buffers is busy or the configuration can be changed.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

Examples: 01_simple_example.c, 01_simple_example_with_hal_self_test.c, and 05_simple_example_debug.c.

◆ Argus_IsDataEvaluationPending()

bool Argus_IsDataEvaluationPending ( argus_hnd_t * hnd )

Determines whether a data evaluation is pending.

If the function returns true, a raw buffer is required to be evaluated to the Argus_EvaluateData function. The raw data buffer is filled with raw data from the measurement tasks which need to be evaluated and the buffer must be freed in order to restart a new measurement task.

Note that no configuration parameters can be update until all raw buffers are evaluated.

Note: See also the Argus_GetStatus function to obtain the current device status and error code if any.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: True if any raw buffer is filled with data that must be evaluated.

◆ Argus_IsTimerMeasurementActive()

bool Argus_IsTimerMeasurementActive ( argus_hnd_t * hnd )

Determines if the device if active with timer based measurements.

If the function returns true, the device is active with timer scheduled measurements that have been started via the Argus_StartMeasurementTimer.

Note that the active state is independent of the busy state that is set when the device is actually busy. The active state is also true if the device is currently idle but waits for the next timer event to trigger a new measurement cycle.

Note: See also the Argus_GetStatus function to obtain the current device status and error code if any.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: True if the device is operating in timer triggered measurement mode.

◆ Argus_Ping()

status_t Argus_Ping ( argus_hnd_t * hnd )

Tests the connection to the device by sending a ping message.

A ping is transferred to the device in order to check the device and SPI connection status. Returns STATUS_OK on success and ERROR_ARGUS_NOT_CONNECTED else-wise.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_StartMeasurementTimer()

status_t Argus_StartMeasurementTimer	(	argus_hnd_t *	hnd,
		argus_measurement_ready_callback_t	cb
	)

Starts the timer based measurement cycle asynchronously.

This function starts a timer based measurement cycle asynchronously in the background. A periodic timer interrupt triggers the measurement frames on the ASIC and the data readout afterwards.

When the measurement has finished, a callback (which is passed as a parameter to the function) is invoked in order to inform the main thread to call the data evaluation method. This call is mandatory to release the data buffer for the next measurement and it must not be invoked directly from the callback since it is currently within an interrupt service routine. Rather a flag should inform the main thread or task scheduler to invoke the evaluation as soon as possible in order to not introduce any unwanted delays to the next measurement frame.

The next measurement frame will be started as soon as the pre- conditions are meet. These are:

timer flag set (i.e. a certain time has passed since the last measurement in order to fulfill eye-safety),
device idle (i.e. no measurement currently ongoing) and
data buffer ready (i.e. the previous data has been evaluated).

Usually, the device idle and data buffer ready conditions are met before the timer tick occurs and thus the timer dictates the frame rate.

The callback function pointer will be invoked when the measurement frame has finished successfully or whenever an error, that cannot be handled internally, occurs.

The periodic timer interrupts are used to check the measurement status for timeouts. An error is invoked when a measurement cycle have not finished within the specified time.

Use Argus_StopMeasurementTimer to stop the measurements.

Note: In order to use this function, the periodic interrupt timer module (see Timer: Hardware Timer Interface) must be implemented!

Parameters

hnd	The API handle; contains all internal states and data.
cb	Callback function that will be invoked when the measurement is completed. Its parameters are the status of the finished measurement cycle and the pointer to the calling API handle, i.e. the /p hnd value. The latter must be passed to the Argus_EvaluateData function. If an error occurred, the status differs from STATUS_OK.

Returns: Returns the status (STATUS_OK on success).

Examples: 02_advanced_example.c, 02_advanced_example_with_hal_self_test.c, 03_high_speed_example.c, and 04_multi_device_example.c.

◆ Argus_StopMeasurementTimer()

status_t Argus_StopMeasurementTimer ( argus_hnd_t * hnd )

Stops the timer based measurement cycle.

This function stops the ongoing timer based measurement cycles that have been started using the Argus_StartMeasurementTimer function.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_TriggerMeasurement()

status_t Argus_TriggerMeasurement	(	argus_hnd_t *	hnd,
		argus_measurement_ready_callback_t	cb
	)

Triggers a single measurement frame asynchronously.

This function immediately triggers a single measurement frame asynchronously if all the pre-conditions are met. Otherwise it returns with a corresponding status (e.g. STATUS_BUSY or STATUS_ARGUS_POWERLIMIT).

When the measurement has finished, a callback (which is passed as a parameter to the function) is invoked in order to inform the main thread to call the data evaluation method. This call is mandatory to release the data buffer for the next measurement and it must not be invoked directly from the callback since it is currently within an interrupt service routine. Rather a flag should inform the main thread or task scheduler to invoke the evaluation task.

The pre-conditions for starting a measurement frame are:

timer flag set (i.e. a certain time has passed since the last measurement in order to fulfill eye-safety),
device idle (i.e. no measurement currently ongoing) and
data buffer ready (i.e. the previous data has been evaluated).

The callback function pointer will be invoked when the measurement frame has finished successfully or whenever an error, that cannot be handled internally, occurs.

The successful finishing of the measurement frame is not checked for timeouts! Instead, the user can call the Argus_GetStatus() function on a regular function to do so.

Note: Despite this function triggers a new measurement cycle upon its invocation, the frame time parameter is still active for this measurement mode. Basically, the first pre-condition mentioned above is controlled via the frame time parameter. This means that measurements cannot be triggered faster than the frame timer parameters specifies. The maximum integration time (i.e. exposure time) is also determined by the frame time such that new measurements are finished with the specified frame time and the device is ready to trigger a new measurement after the frame time has elapse. See Argus_SetConfigurationFrameTime function for more information on the frame time.

Parameters

hnd	The API handle; contains all internal states and data.
cb	Callback function that will be invoked when the measurement is completed. Its parameters are the status of the finished measurement cycle and the pointer to the calling API handle, i.e. the /p hnd value. The latter must be passed to the Argus_EvaluateData function. If an error occurred, the status differs from STATUS_OK.

Returns: Returns the status (STATUS_OK on success).

Examples: 01_simple_example.c, 01_simple_example_with_hal_self_test.c, and 05_simple_example_debug.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ARGUS_AUX_CHANNEL_COUNT

◆ ARGUS_AUX_DATA_SIZE

◆ ARGUS_RAW_DATA_SIZE

◆ ARGUS_RAW_DATA_VALUES

Function Documentation

◆ Argus_Abort()

◆ Argus_EvaluateData()

◆ Argus_EvaluateDataDebug()

◆ Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence()

◆ Argus_ExecuteRelativeRangeOffsetCalibrationSequence()

◆ Argus_ExecuteXtalkCalibrationSequence()

◆ Argus_GetStatus()

◆ Argus_IsDataEvaluationPending()

◆ Argus_IsTimerMeasurementActive()

◆ Argus_Ping()

◆ Argus_StartMeasurementTimer()

◆ Argus_StopMeasurementTimer()

◆ Argus_TriggerMeasurement()