Angle of Arrival / Departure

Angle of Arrival / Departure.

Data Structures

struct sl_rtl_clib_iq_sample_qa_antenna_data_t
struct sl_rtl_clib_iq_sample_qa_dataset_t

Macros

#define SL_RTL_AOX_IQ_SAMPLE_QA_ALL_OK 0
#define SL_RTL_AOX_IQ_SAMPLE_QA_FAILURE 0xffffffff
#define SL_RTL_AOX_IQ_SAMPLE_QA_CLEAR_BIT (code, bit)   (code &= ~(1UL << bit))
#define SL_RTL_AOX_IQ_SAMPLE_QA_SET_BIT (code, bit)   (code |= (1UL << bit))
#define SL_RTL_AOX_IQ_SAMPLE_QA_IS_SET (code, bit)   (code & (1UL << bit))

Typedefs

typedef void * sl_rtl_aox_libitem
Angle of Arrival / Departure library item.

Enumerations

enum sl_rtl_aox_array_type {
SL_RTL_AOX_ARRAY_TYPE_4x4_URA = 0, SL_RTL_AOX_ARRAY_TYPE_3x3_URA , SL_RTL_AOX_ARRAY_TYPE_1x4_ULA , SL_RTL_AOX_ARRAY_TYPE_4x4_DP_URA ,
SL_RTL_AOX_ARRAY_TYPE_COREHW_15x15_DP , SL_RTL_AOX_ARRAY_TYPE_COREHW_12x12_DP , SL_RTL_AOX_ARRAY_TYPE_LAST
}
AoX antenna array type.
enum sl_rtl_aox_switch_pattern_array { SL_RTL_AOX_SWITCH_PATTERN_ARRAY_4x4_CP = 0, SL_RTL_AOX_SWITCH_PATTERN_ARRAY_4x4_DP , SL_RTL_AOX_SWITCH_PATTERN_ARRAY_LAST }
enum sl_rtl_aox_switch_pattern_ptions { SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_DUAL_POLARIZED = 0x1, SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_EXTRA_REFERENCE = 0x2 }
enum sl_rtl_aox_mode {
SL_RTL_AOX_MODE_ONE_SHOT_BASIC = 3, SL_RTL_AOX_MODE_ONE_SHOT_BASIC_LIGHTWEIGHT , SL_RTL_AOX_MODE_ONE_SHOT_FAST_RESPONSE , SL_RTL_AOX_MODE_ONE_SHOT_HIGH_ACCURACY ,
SL_RTL_AOX_MODE_ONE_SHOT_BASIC_AZIMUTH_ONLY , SL_RTL_AOX_MODE_ONE_SHOT_FAST_RESPONSE_AZIMUTH_ONLY , SL_RTL_AOX_MODE_ONE_SHOT_HIGH_ACCURACY_AZIMUTH_ONLY , SL_RTL_AOX_MODE_REAL_TIME_FAST_RESPONSE ,
SL_RTL_AOX_MODE_REAL_TIME_BASIC , SL_RTL_AOX_MODE_REAL_TIME_HIGH_ACCURACY , SL_RTL_AOX_MODE_LAST
}
AoX estimator mode.
enum sl_rtl_aox_constraint_type { SL_RTL_AOX_CONSTRAINT_TYPE_AZIMUTH = 0, SL_RTL_AOX_CONSTRAINT_TYPE_ELEVATION }
enum sl_rtl_aox_switch_pattern_mode { SL_RTL_AOX_SWITCH_PATTERN_MODE_DEFAULT = 0, SL_RTL_AOX_SWITCH_PATTERN_MODE_RANDOM , SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTERNAL , SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTRA_REFERENCE }
enum sl_rtl_slib_iq_sample_qa_result_t {
SL_RTL_AOX_IQ_SAMPLE_QA_INVAL_REF = 0, SL_RTL_AOX_IQ_SAMPLE_QA_DCOFFSET = 2, SL_RTL_AOX_IQ_SAMPLE_QA_SNDR = 3, SL_RTL_AOX_IQ_SAMPLE_QA_ROTATING_ERROR = 4,
SL_RTL_AOX_IQ_SAMPLE_QA_REF_ANT_PHASE_VALUE = 5, SL_RTL_AOX_IQ_SAMPLE_QA_REF_ANT_PHASE_JITTER = 6, SL_RTL_AOX_IQ_SAMPLE_QA_ANT_X_PHASE_JITTER = 7, SL_RTL_AOX_IQ_SAMPLE_QA_ALL_SAME_PHASE = 8,
SL_RTL_AOX_IQ_SAMPLE_QA_SWICHING_JITTER = 9
}

Functions

enum sl_rtl_error_code sl_rtl_aox_init ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_deinit ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_set_num_snapshots ( sl_rtl_aox_libitem *item, uint32_t num_snapshots)
enum sl_rtl_error_code sl_rtl_aox_set_array_type ( sl_rtl_aox_libitem *item, enum sl_rtl_aox_array_type array_type)
enum sl_rtl_error_code sl_rtl_aox_set_mode ( sl_rtl_aox_libitem *item, enum sl_rtl_aox_mode mode)
enum sl_rtl_error_code sl_rtl_aox_calculate_iq_sample_phase_rotation ( sl_rtl_aox_libitem *item, float iq_data_downsampling_factor, float *i_samples, float *q_samples, uint32_t num_samples, float *phase_rotation_out)
enum sl_rtl_error_code sl_rtl_aox_set_iq_sample_phase_rotation ( sl_rtl_aox_libitem *item, float phase_rotation)
enum sl_rtl_error_code sl_rtl_aox_add_constraint ( sl_rtl_aox_libitem *item, enum sl_rtl_aox_constraint_type constraint_type, float min_value, float max_value)
enum sl_rtl_error_code sl_rtl_aox_set_sample_rate ( sl_rtl_aox_libitem *item, float sampleRate)
enum sl_rtl_error_code sl_rtl_aox_set_num_radio_channels ( sl_rtl_aox_libitem *item, uint32_t channels)
enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_configure ( sl_rtl_aox_libitem *item)
uint32_t sl_rtl_aox_iq_sample_qa_get_results ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_get_details ( sl_rtl_aox_libitem *item, sl_rtl_clib_iq_sample_qa_dataset_t *results, sl_rtl_clib_iq_sample_qa_antenna_data_t *antenna_data)
enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_get_channel_details ( sl_rtl_aox_libitem *item, uint8_t channel, sl_rtl_clib_iq_sample_qa_dataset_t *results, sl_rtl_clib_iq_sample_qa_antenna_data_t *antenna_data)
enum sl_rtl_error_code sl_rtl_aox_create_estimator ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_convert_raw_samples ( sl_rtl_aox_libitem *item, uint32_t start_offset, float iq_data_downsampling_factor, float *raw_i_samples_in, float *raw_q_samples_in, uint32_t num_raw_samples_in, float **i_samples_out, float **q_samples_out, uint32_t num_snapshots_out)
enum sl_rtl_error_code sl_rtl_aox_calculate_number_of_snapshots ( sl_rtl_aox_libitem *item, uint32_t num_raw_samples_in, uint32_t start_offset, float iq_data_downsampling_factor, uint32_t num_channels, uint32_t *num_snapshots_out)
enum sl_rtl_error_code sl_rtl_aox_set_switch_pattern_mode ( sl_rtl_aox_libitem *item, enum sl_rtl_aox_switch_pattern_mode mode)
enum sl_rtl_error_code sl_rtl_aox_update_switch_pattern ( sl_rtl_aox_libitem *item, uint32_t *switch_pattern_in, uint32_t **switch_pattern_out)
enum sl_rtl_error_code sl_rtl_aox_set_switch_pattern_seed ( sl_rtl_aox_libitem *item, int32_t seed_value)
enum sl_rtl_error_code sl_rtl_aox_convert_switch_pattern ( sl_rtl_aox_libitem *item, uint32_t array_id, uint32_t options, uint32_t switch_pattern_size_in, uint32_t *switch_pattern_in, uint32_t *switch_pattern_size_out, uint32_t **switch_pattern_out)
enum sl_rtl_error_code sl_rtl_aox_reset_estimator ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_process ( sl_rtl_aox_libitem *item, float **i_samples, float **q_samples, float tone_frequency, float *az_out, float *el_out)
enum sl_rtl_error_code sl_rtl_aox_get_latest_aoa_standard_deviation ( sl_rtl_aox_libitem *item, float *az_std_dev, float *el_std_dev)
enum sl_rtl_error_code sl_rtl_aox_set_expected_direction ( sl_rtl_aox_libitem *item, float expected_az, float expected_el)
enum sl_rtl_error_code sl_rtl_aox_set_expected_deviation ( sl_rtl_aox_libitem *item, float deviation_az, float deviation_el)
enum sl_rtl_error_code sl_rtl_aox_clear_expected_direction ( sl_rtl_aox_libitem *item)
enum sl_rtl_error_code sl_rtl_aox_enable_spectrum ( sl_rtl_aox_libitem *item, bool enable)
enum sl_rtl_error_code sl_rtl_aox_get_spectrum_size ( sl_rtl_aox_libitem *item, uint32_t *rows, uint32_t *cols)
enum sl_rtl_error_code sl_rtl_aox_get_spectrum ( sl_rtl_aox_libitem *item, float **spectrum_out)

Detailed Description

Angle of Arrival / Departure.

These functions are related to the calculation of the Angle of Arrival and Angle of Departure from I/Q samples. The angles can be calculated following these steps:

  1. Initialize a sl_rtl_aox_libitem instance.
  2. Set up the antenna array and angle calculation parameters.
  3. Create the estimator.
  4. Set the antenna switching pattern.
  5. Input the I/Q data into the libitem.
  6. Process the I/Q data into an angle.

Data Structure Documentation

◆ sl_rtl_clib_iq_sample_qa_antenna_data_t

struct sl_rtl_clib_iq_sample_qa_antenna_data_t
Data Fields
float level Antenna signal level, in decibels.
float snr Antenna level signal to noise ratio, in decibels.
float phase_value Antenna's average unrotated phase value in the packet, in radians.
float phase_jitter Phase variation of snapshots' data of an antenna in packet, in radians.

◆ sl_rtl_clib_iq_sample_qa_dataset_t

struct sl_rtl_clib_iq_sample_qa_dataset_t
Data Fields
bool data_available If false, all the antenna values are undefined.
uint32_t curr_channel Radio channel for the last packet.
float ref_freq Apparent supplemental tone frequency.
float ref_sndr Reference period signal to noise and distortion ratio.
float switching_jitter Estimated antenna switching clock jitter.

Macro Definition Documentation

◆ SL_RTL_AOX_IQ_SAMPLE_QA_ALL_OK

#define SL_RTL_AOX_IQ_SAMPLE_QA_ALL_OK   0

◆ SL_RTL_AOX_IQ_SAMPLE_QA_FAILURE

#define SL_RTL_AOX_IQ_SAMPLE_QA_FAILURE   0xffffffff

◆ SL_RTL_AOX_IQ_SAMPLE_QA_CLEAR_BIT

#define SL_RTL_AOX_IQ_SAMPLE_QA_CLEAR_BIT ( code,
bit
) (code &= ~(1UL << bit))

◆ SL_RTL_AOX_IQ_SAMPLE_QA_SET_BIT

#define SL_RTL_AOX_IQ_SAMPLE_QA_SET_BIT ( code,
bit
) (code |= (1UL << bit))

◆ SL_RTL_AOX_IQ_SAMPLE_QA_IS_SET

#define SL_RTL_AOX_IQ_SAMPLE_QA_IS_SET ( code,
bit
) (code & (1UL << bit))

Typedef Documentation

◆ sl_rtl_aox_libitem

typedef void* sl_rtl_aox_libitem

Angle of Arrival / Departure library item.

Enumeration Type Documentation

◆ sl_rtl_aox_array_type

enum sl_rtl_aox_array_type

AoX antenna array type.

Enumerator
SL_RTL_AOX_ARRAY_TYPE_4x4_URA

Silicon Labs Ref. 4x4 Uniform Rectangular Array.

SL_RTL_AOX_ARRAY_TYPE_3x3_URA

Silicon Labs Ref. 3x3 Uniform Rectangular Array.

SL_RTL_AOX_ARRAY_TYPE_1x4_ULA

Silicon Labs Ref. 1x4 Uniform Linear Array.

SL_RTL_AOX_ARRAY_TYPE_4x4_DP_URA

Silicon Labs Ref. 4x4 Uniform Dual Polarized Rectangular Array.

SL_RTL_AOX_ARRAY_TYPE_COREHW_15x15_DP

CoreHw Ref. 150 mm x 150 mm, 8 Element Dual Polarized Array.

SL_RTL_AOX_ARRAY_TYPE_COREHW_12x12_DP

CoreHw Ref. 120 mm x 120 mm, 8 Element Dual Polarized Array.

SL_RTL_AOX_ARRAY_TYPE_LAST

Placeholder.

◆ sl_rtl_aox_switch_pattern_array

enum sl_rtl_aox_switch_pattern_array
Enumerator
SL_RTL_AOX_SWITCH_PATTERN_ARRAY_4x4_CP
SL_RTL_AOX_SWITCH_PATTERN_ARRAY_4x4_DP
SL_RTL_AOX_SWITCH_PATTERN_ARRAY_LAST

◆ sl_rtl_aox_switch_pattern_ptions

enum sl_rtl_aox_switch_pattern_ptions
Enumerator
SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_DUAL_POLARIZED
SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_EXTRA_REFERENCE

◆ sl_rtl_aox_mode

enum sl_rtl_aox_mode

AoX estimator mode.

Enumerator
SL_RTL_AOX_MODE_ONE_SHOT_BASIC

Medium filtering, medium response. Returns 2D angle, requires 10 rounds. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_BASIC_LIGHTWEIGHT

Medium filtering, medium response, low CPU cost & low elevation resolution. 2D angle, req. 10 rounds. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_FAST_RESPONSE

Low filtering, fast response, low CPU cost & low elevation resolution. 2D angle, requires 2 rounds. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_HIGH_ACCURACY

High filtering, slow response. 2D angle, requires 20 rounds. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_BASIC_AZIMUTH_ONLY

Equivalent to ONE_SHOT_BASIC with low CPU cost and returns 1D angle. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_FAST_RESPONSE_AZIMUTH_ONLY

Equivalent to ONE_SHOT_FAST_RESPONSE with low CPU cost, 1D angle. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_ONE_SHOT_HIGH_ACCURACY_AZIMUTH_ONLY

Equivalent to ONE_SHOT_HIGH_ACCURACY with low CPU cost, 1D angle. Most suitable for single shot measurement.

SL_RTL_AOX_MODE_REAL_TIME_FAST_RESPONSE

Low filtering, fast response, lowest CPU cost, 2D angle, Most suitable for real-time tracking.

SL_RTL_AOX_MODE_REAL_TIME_BASIC

Medium filtering, medium response, medium CPU cost, 2D angle, Most suitable for real-time tracking.

SL_RTL_AOX_MODE_REAL_TIME_HIGH_ACCURACY

High filtering, slow response, highest CPU cost, 2D angle, Most suitable for real-time tracking.

SL_RTL_AOX_MODE_LAST

Placeholder.

◆ sl_rtl_aox_constraint_type

enum sl_rtl_aox_constraint_type
Enumerator
SL_RTL_AOX_CONSTRAINT_TYPE_AZIMUTH

Azimuth constraint in degrees.

SL_RTL_AOX_CONSTRAINT_TYPE_ELEVATION

Elevation constraint in degrees.

◆ sl_rtl_aox_switch_pattern_mode

enum sl_rtl_aox_switch_pattern_mode
Enumerator
SL_RTL_AOX_SWITCH_PATTERN_MODE_DEFAULT

Internally defined switch pattern: 0, 1, 2, ..., N-1, where N is the number of antennas.

SL_RTL_AOX_SWITCH_PATTERN_MODE_RANDOM

Internally defined random switch pattern.

SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTERNAL

Switch pattern set externally by the user.

SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTRA_REFERENCE

Switch pattern set externally by the user with extra reference antenna as a first.

◆ sl_rtl_slib_iq_sample_qa_result_t

enum sl_rtl_slib_iq_sample_qa_result_t
Enumerator
SL_RTL_AOX_IQ_SAMPLE_QA_INVAL_REF

Invalid reference period data.

SL_RTL_AOX_IQ_SAMPLE_QA_DCOFFSET

DC offset too large.

SL_RTL_AOX_IQ_SAMPLE_QA_SNDR

Reference period SNDR too large.

SL_RTL_AOX_IQ_SAMPLE_QA_ROTATING_ERROR

Rotation error too large.

SL_RTL_AOX_IQ_SAMPLE_QA_REF_ANT_PHASE_VALUE

Reference antenna phase value too big.

SL_RTL_AOX_IQ_SAMPLE_QA_REF_ANT_PHASE_JITTER

Reference antenna phase jitter too large.

SL_RTL_AOX_IQ_SAMPLE_QA_ANT_X_PHASE_JITTER

Antenna X phase jitter too large.

SL_RTL_AOX_IQ_SAMPLE_QA_ALL_SAME_PHASE

All the antennas seen in the same phase.

SL_RTL_AOX_IQ_SAMPLE_QA_SWICHING_JITTER

Switching jitter too large.

Function Documentation

◆ sl_rtl_aox_init()

enum sl_rtl_error_code sl_rtl_aox_init ( sl_rtl_aox_libitem * item )

Initialize the AoX libitem instance.

Parameters
[in] item Pointer to the libitem to be initialized
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_deinit()

enum sl_rtl_error_code sl_rtl_aox_deinit ( sl_rtl_aox_libitem * item )

Deinitialize a libitem instance of the AoX estimator.

Parameters
[in] item Pointer to the libitem to be deinitialized
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_set_num_snapshots()

enum sl_rtl_error_code sl_rtl_aox_set_num_snapshots ( sl_rtl_aox_libitem * item,
uint32_t num_snapshots
)

Set the number of signal snapshots to be used in the angle estimation.

Parameters
[in] item Pointer to the initialized AoX libitem
[in] num_snapshots Number of snapshots as positive integer value
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_set_array_type()

enum sl_rtl_error_code sl_rtl_aox_set_array_type ( sl_rtl_aox_libitem * item,
enum sl_rtl_aox_array_type array_type
)

Set the array type used with the estimator.

Parameters
[in] item Pointer to the initialized AoX libitem
[in] array_type Array type as sl_rtl_aox_array_type
Returns
SL_RTL_ERROR_SUCCESS if successful

Set the array type used with the estimator. For example, the array type should be set to SL_RTL_AOX_ARRAY_TYPE_4x4_URA when using the reference 4x4 URA board.

◆ sl_rtl_aox_set_mode()

enum sl_rtl_error_code sl_rtl_aox_set_mode ( sl_rtl_aox_libitem * item,
enum sl_rtl_aox_mode mode
)

Set the estimation mode.

Parameters
[in] item Pointer to the initialized AoX libitem
[in] mode Estimator mode as sl_rtl_aox_mode
Returns
SL_RTL_ERROR_SUCCESS if successful

Set the estimation mode. For example, ::SL_RTL_AOX_MODE_BASIC sets medium filtering and estimates both azimuth and elevation. For further description of the modes, see the documentation of sl_rtl_aox_mode .

◆ sl_rtl_aox_calculate_iq_sample_phase_rotation()

enum sl_rtl_error_code sl_rtl_aox_calculate_iq_sample_phase_rotation ( sl_rtl_aox_libitem * item,
float iq_data_downsampling_factor,
float * i_samples,
float * q_samples,
uint32_t num_samples,
float * phase_rotation_out
)

Estimate the I/Q-sample phase rotation error in degrees.

Parameters
[in] item Pointer to the initialized AoX libitem
[in] iq_data_downsampling_factor Ratio between reference period IQ-data sampling rate and actual IQ-data (i.e., antenna array data) sampling rate. For example, 1e6 / 500e3 = 2.0
[in] i_samples Float-array of the reference period I samples
[in] q_samples Float-array of the reference period Q samples
[in] num_samples Number of samples, or size of the I or Q sample array
[out] phase_rotation_out Returned phase rotation value as float in degrees
Returns
SL_RTL_ERROR_SUCCESS if successful

Estimate the I/Q-sample phase rotation error caused by switching and CTE frequency error based on I/Q samples from the reference period.

◆ sl_rtl_aox_set_iq_sample_phase_rotation()

enum sl_rtl_error_code sl_rtl_aox_set_iq_sample_phase_rotation ( sl_rtl_aox_libitem * item,
float phase_rotation
)

Set a constant value of I/Q sample phase rotation in degrees.

Parameters
[in] item Pointer to the initialized AoX libitem
[in] phase_rotation Float value of I/Q sample phase rotation in degrees
Returns
SL_RTL_ERROR_SUCCESS if successful

Set a constant value of I/Q sample phase rotation in degrees. The sample rotation can be used for correcting the switching and CTE frequency error.

Note
: This function should be called only after the estimator is created.

◆ sl_rtl_aox_add_constraint()

enum sl_rtl_error_code sl_rtl_aox_add_constraint ( sl_rtl_aox_libitem * item,
enum sl_rtl_aox_constraint_type constraint_type,
float min_value,
float max_value
)

Add constraints for the estimator. Call before sl_rtl_aox_create_estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] constraint_type Select which constraints should be added.
[in] min_value Starting (minimum) value of the range including the min_value.
[in] max_value Ending (maximum) value of the range including the max_value.
Returns
SL_RTL_ERROR_SUCCESS if successful

For example, constraint for SL_RTL_AOX_CONSTRAINT_TYPE_AZIMUTH with min_value = 0 and max_value = 90 means that the angular range 0 to 90 degrees is excluded from the estimators internal processing range and angle estimated between that range are not considered as valid results. Setting constraints will help ruling out false multipath-detections when the locator is installed nearby a wall or a RF-reflective surface.

Note
: This function must called before the estimator is created.

◆ sl_rtl_aox_set_sample_rate()

enum sl_rtl_error_code sl_rtl_aox_set_sample_rate ( sl_rtl_aox_libitem * item,
float sampleRate
)

Configure the IQ sampling sample rate for the library.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] sampleRate The new sample rate.
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_set_num_radio_channels()

enum sl_rtl_error_code sl_rtl_aox_set_num_radio_channels ( sl_rtl_aox_libitem * item,
uint32_t channels
)

Configure the number of radio channels.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] channels The new number of radio channels.
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_iq_sample_qa_configure()

enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_configure ( sl_rtl_aox_libitem * item )

Configure the IQ sample quality analysis.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

This function turns the IQ sample quality analysis, which is not done by default.

◆ sl_rtl_aox_iq_sample_qa_get_results()

uint32_t sl_rtl_aox_iq_sample_qa_get_results ( sl_rtl_aox_libitem * item )

Get the IQ sample quality analysis overall results.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
Returns
bitmask of found problems, zero indicates that everything is OK

◆ sl_rtl_aox_iq_sample_qa_get_details()

enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_get_details ( sl_rtl_aox_libitem * item,
sl_rtl_clib_iq_sample_qa_dataset_t * results,
sl_rtl_clib_iq_sample_qa_antenna_data_t * antenna_data
)

Get the IQ sample quality analysis detailed results for the latest packet.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[out] results The data structure with data related to the latest data packet
[out] antenna_data The array of antenna-specific results
Returns
SL_RTL_ERROR_SUCCESS if successful

Fetch the results for the latest packet.

◆ sl_rtl_aox_iq_sample_qa_get_channel_details()

enum sl_rtl_error_code sl_rtl_aox_iq_sample_qa_get_channel_details ( sl_rtl_aox_libitem * item,
uint8_t channel,
sl_rtl_clib_iq_sample_qa_dataset_t * results,
sl_rtl_clib_iq_sample_qa_antenna_data_t * antenna_data
)

Get the IQ sample quality analysis detailed results for the requested radio channel.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] channel Radio channel to show results for.
[out] results The data structure with data related to the last data packet using the requested channel
[out] antenna_data The array of antenna-specific results
Returns
SL_RTL_ERROR_SUCCESS if successful

Fetch the latest results for the given radio channel, which may be other than the latest packet received.

◆ sl_rtl_aox_create_estimator()

enum sl_rtl_error_code sl_rtl_aox_create_estimator ( sl_rtl_aox_libitem * item )

Create the estimator after initializing the libitem and setting parameters.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_convert_raw_samples()

enum sl_rtl_error_code sl_rtl_aox_convert_raw_samples ( sl_rtl_aox_libitem * item,
uint32_t start_offset,
float iq_data_downsampling_factor,
float * raw_i_samples_in,
float * raw_q_samples_in,
uint32_t num_raw_samples_in,
float ** i_samples_out,
float ** q_samples_out,
uint32_t num_snapshots_out
)

Convert data in RAW IQ-data buffers to downsampled IQ-data buffers.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] start_offset The start offset in the buffer (for example, for skipping a reference period)
[in] iq_data_downsampling_factor Ratio between chip IQ-data sampling rate and downsampled rate. For example, 4.8e6 / 500e3 = 9.6
[in] raw_i_samples_in I-part sample buffer input
[in] raw_q_samples_in Q-part sample buffer input
[in] num_raw_samples_in Number of IQ-sample pairs in the input buffers
[out] i_samples_out Buffer for the processed I-samples. Must be allocated by the user. Indexing: i_samples_out[snapshot][antenna]
[out] q_samples_out Buffer for the processed Q-samples. Must be allocated by the user. Indexing: q_samples_out[snapshot][antenna]
[in] num_snapshots_out Number of snaphots allocated in the output buffers. This function will check if the given number of snaphots and calculated snapshots based on the length of RAW-data match
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_calculate_number_of_snapshots()

enum sl_rtl_error_code sl_rtl_aox_calculate_number_of_snapshots ( sl_rtl_aox_libitem * item,
uint32_t num_raw_samples_in,
uint32_t start_offset,
float iq_data_downsampling_factor,
uint32_t num_channels,
uint32_t * num_snapshots_out
)

Calculate the number of downsampled snaphots in a RAW IQ-data buffer. Use this function to get the number of snaphots to allocate the i_samples and q_samples buffers for the process-function.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] num_raw_samples_in Total number of RAW IQ-sample pairs
[in] start_offset The start offset in the buffer, for example, for skipping a reference period
[in] iq_data_downsampling_factor Ratio between chip IQ-data sampling rate and downsampled rate. For example, 4.8e6 / 500e3 = 9.6.
[in] num_channels Number of channels in the RAW data
[out] num_snapshots_out Calculated number of snaphots based on the input
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_set_switch_pattern_mode()

enum sl_rtl_error_code sl_rtl_aox_set_switch_pattern_mode ( sl_rtl_aox_libitem * item,
enum sl_rtl_aox_switch_pattern_mode mode
)

Set switch pattern mode. Sets internal mode used by the library. See enum sl_rtl_aox_switch_pattern_mode for detailed description of the modes. If this function isn't called, a default switch pattern of: 0, 1, 2, 3, ..., N-1 will be used, where N is the number of antennas. Call this function at run-time after initializing and creating the estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] mode Required mode
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_update_switch_pattern()

enum sl_rtl_error_code sl_rtl_aox_update_switch_pattern ( sl_rtl_aox_libitem * item,
uint32_t * switch_pattern_in,
uint32_t ** switch_pattern_out
)

Update switch pattern, which is used by the estimator algorithm. This function must be called before calling the function sl_rtl_aox_process. Call this function at run-time after initializing and creating the estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] switch_pattern_in Pointer to the switch pattern array. The pointer must point to a valid switch pattern when SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTERNAL is used.
[out] switch_pattern_out Pointer to the user defined uint32_t* variable. This pointer must be non-zero when using internally defined switch pattern modes, otherwise can be zero.
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_set_switch_pattern_seed()

enum sl_rtl_error_code sl_rtl_aox_set_switch_pattern_seed ( sl_rtl_aox_libitem * item,
int32_t seed_value
)

Set the random seed for the switch pattern, which is used for the random pattern mode. Call this function at run-time after initializing and creating the estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] seed_value The seed value to be used. internally defined switch pattern modes, otherwise can be zero.
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_convert_switch_pattern()

enum sl_rtl_error_code sl_rtl_aox_convert_switch_pattern ( sl_rtl_aox_libitem * item,
uint32_t array_id,
uint32_t options,
uint32_t switch_pattern_size_in,
uint32_t * switch_pattern_in,
uint32_t * switch_pattern_size_out,
uint32_t ** switch_pattern_out
)
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_reset_estimator()

enum sl_rtl_error_code sl_rtl_aox_reset_estimator ( sl_rtl_aox_libitem * item )

Reset estimator state. Calling this function causes the selected aox-mode to start from its initial state. Call this function at run-time after initializing and creating the estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_process()

enum sl_rtl_error_code sl_rtl_aox_process ( sl_rtl_aox_libitem * item,
float ** i_samples,
float ** q_samples,
float tone_frequency,
float * az_out,
float * el_out
)

Calculate the angle estimate.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] i_samples Two-dimensional float-array of captured I samples as i_samples[snapshot][antenna]
[in] q_samples Two-dimensional float-array of captured Q samples as q_samples[snapshot][antenna], corresponding to the I samples array
[in] tone_frequency The frequency of the signal from which the I/Q data was captured from as float (e.g., 2.46e9f)
[out] az_out Output azimuth angle
[out] el_out Output elevation angle
Returns
SL_RTL_ERROR_SUCCESS if successful and SL_RTL_ERROR_ESTIMATION_IN_PROGRESS if estimate is not yet final and more I/Q data needs to be processed.

Calculate the angle estimate from the given I/Q samples captured at the given frequency. Call this function with new I/Q data as many times as indicated by the sl_rtl_aox_mode used by the estimator before the final estimate is output.

◆ sl_rtl_aox_get_latest_aoa_standard_deviation()

enum sl_rtl_error_code sl_rtl_aox_get_latest_aoa_standard_deviation ( sl_rtl_aox_libitem * item,
float * az_std_dev,
float * el_std_dev
)

Get the standard deviation for the latest AoA/AoD-estimate.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[out] az_std_dev Pointer for getting standard deviation of the latest azimuth estimate
[out] el_std_dev Pointer for getting standard deviation of the latest elevation estimate
Returns
SL_RTL_ERROR_SUCCESS if successful

Call this function after sl_rtl_aox_process to fetch standard deviation for the latest AoA/AoD-estimate. Positive standard deviations indicate line-of-sight detection and negative values indicate likely non-line-of-sight detection.

◆ sl_rtl_aox_set_expected_direction()

enum sl_rtl_error_code sl_rtl_aox_set_expected_direction ( sl_rtl_aox_libitem * item,
float expected_az,
float expected_el
)

Feed the expected angles back to the locator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] expected_az Expected azimuth angle calculated by position algorithm
[in] expected_el Expected elevation angle calculated by position algorithm
Returns
SL_RTL_ERROR_SUCCESS if successful

The position algorithm has a more complete view of the asset's location. The direction it should be found can be calculated back and fed to the locator, so that it can recover faster when, for example, it has locked to a reflection rather than to the line of sight signal. See also sl_rtl_loc_get_expected_direction() .

◆ sl_rtl_aox_set_expected_deviation()

enum sl_rtl_error_code sl_rtl_aox_set_expected_deviation ( sl_rtl_aox_libitem * item,
float deviation_az,
float deviation_el
)

Feed the expected angle deviations back to the locator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
[in] deviation_az Deviation of the expected azimuth angle calculated by position algorithm
[in] deviation_el Deviation of the expected elevation angle calculated by position algorithm
Returns
SL_RTL_ERROR_SUCCESS if successful

Report expected deviations calculated by the position algorithm back to the locator so that angles are calculated more accurately taking in account the goodness of the expected directions. If sl_rtl_aox_set_expected_direction() is called but this function is not called, the algorithm will use default values for the expected deviations. See also sl_rtl_loc_get_expected_deviation() and sl_rtl_aox_set_expected_direction() .

◆ sl_rtl_aox_clear_expected_direction()

enum sl_rtl_error_code sl_rtl_aox_clear_expected_direction ( sl_rtl_aox_libitem * item )

Clear the expected directions and deviations from the locator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

See also sl_rtl_aox_set_expected_direction() and sl_rtl_aox_set_expected_deviation() .

◆ sl_rtl_aox_enable_spectrum()

enum sl_rtl_error_code sl_rtl_aox_enable_spectrum ( sl_rtl_aox_libitem * item,
bool enable
)

Enable or disable outputting the pseudospectrum. Should be called before creating the estimator.

Parameters
[in] item Pointer to the initialized libitem
[in] enable Set to true to enable outputting the pseudospectrum
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_get_spectrum_size()

enum sl_rtl_error_code sl_rtl_aox_get_spectrum_size ( sl_rtl_aox_libitem * item,
uint32_t * rows,
uint32_t * cols
)

Get the size of the pseudospectrum. Should be called after calling the AoX process function.

Parameters
[in] item Pointer to the initialized libitem
[in] rows Number of rows in the pseudospectrum data array
[in] cols Number of columns in the pseudospecutrm data array
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_aox_get_spectrum()

enum sl_rtl_error_code sl_rtl_aox_get_spectrum ( sl_rtl_aox_libitem * item,
float ** spectrum_out
)

Get the pseudospectrum. Memory for the output spectrum must be allocated by the user, the size of the rows and columns are given by sl_rtl_aox_get_spectrum_size() .

Parameters
[in] item Pointer to the initialized libitem
[out] spectrum_out Outputted pseudospectrum
Returns
SL_RTL_ERROR_SUCCESS if successful