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]itemPointer 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]itemPointer 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]itemPointer to the initialized AoX libitem
[in]num_snapshotsNumber 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]itemPointer to the initialized AoX libitem
[in]array_typeArray 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]itemPointer to the initialized AoX libitem
[in]modeEstimator 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]itemPointer to the initialized AoX libitem
[in]iq_data_downsampling_factorRatio 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_samplesFloat-array of the reference period I samples
[in]q_samplesFloat-array of the reference period Q samples
[in]num_samplesNumber of samples, or size of the I or Q sample array
[out]phase_rotation_outReturned 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]itemPointer to the initialized AoX libitem
[in]phase_rotationFloat 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]itemPointer to the initialized and configured AoX libitem
[in]constraint_typeSelect which constraints should be added.
[in]min_valueStarting (minimum) value of the range including the min_value.
[in]max_valueEnding (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]itemPointer to the initialized and configured AoX libitem
[in]sampleRateThe 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]itemPointer to the initialized and configured AoX libitem
[in]channelsThe 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]itemPointer 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]itemPointer 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]itemPointer to the initialized and configured AoX libitem
[out]resultsThe data structure with data related to the latest data packet
[out]antenna_dataThe 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]itemPointer to the initialized and configured AoX libitem
[in]channelRadio channel to show results for.
[out]resultsThe data structure with data related to the last data packet using the requested channel
[out]antenna_dataThe 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]itemPointer 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]itemPointer to the initialized and configured AoX libitem
[in]start_offsetThe start offset in the buffer (for example, for skipping a reference period)
[in]iq_data_downsampling_factorRatio between chip IQ-data sampling rate and downsampled rate. For example, 4.8e6 / 500e3 = 9.6
[in]raw_i_samples_inI-part sample buffer input
[in]raw_q_samples_inQ-part sample buffer input
[in]num_raw_samples_inNumber of IQ-sample pairs in the input buffers
[out]i_samples_outBuffer for the processed I-samples. Must be allocated by the user. Indexing: i_samples_out[snapshot][antenna]
[out]q_samples_outBuffer for the processed Q-samples. Must be allocated by the user. Indexing: q_samples_out[snapshot][antenna]
[in]num_snapshots_outNumber 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]itemPointer to the initialized and configured AoX libitem
[in]num_raw_samples_inTotal number of RAW IQ-sample pairs
[in]start_offsetThe start offset in the buffer, for example, for skipping a reference period
[in]iq_data_downsampling_factorRatio between chip IQ-data sampling rate and downsampled rate. For example, 4.8e6 / 500e3 = 9.6.
[in]num_channelsNumber of channels in the RAW data
[out]num_snapshots_outCalculated 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]itemPointer to the initialized and configured AoX libitem
[in]modeRequired 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]itemPointer to the initialized and configured AoX libitem
[in]switch_pattern_inPointer 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_outPointer 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]itemPointer to the initialized and configured AoX libitem
[in]seed_valueThe 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]itemPointer 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]itemPointer to the initialized and configured AoX libitem
[in]i_samplesTwo-dimensional float-array of captured I samples as i_samples[snapshot][antenna]
[in]q_samplesTwo-dimensional float-array of captured Q samples as q_samples[snapshot][antenna], corresponding to the I samples array
[in]tone_frequencyThe frequency of the signal from which the I/Q data was captured from as float (e.g., 2.46e9f)
[out]az_outOutput azimuth angle
[out]el_outOutput 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]itemPointer to the initialized and configured AoX libitem
[out]az_std_devPointer for getting standard deviation of the latest azimuth estimate
[out]el_std_devPointer 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]itemPointer to the initialized and configured AoX libitem
[in]expected_azExpected azimuth angle calculated by position algorithm
[in]expected_elExpected 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]itemPointer to the initialized and configured AoX libitem
[in]deviation_azDeviation of the expected azimuth angle calculated by position algorithm
[in]deviation_elDeviation 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]itemPointer 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]itemPointer to the initialized libitem
[in]enableSet 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]itemPointer to the initialized libitem
[in]rowsNumber of rows in the pseudospectrum data array
[in]colsNumber 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]itemPointer to the initialized libitem
[out]spectrum_outOutputted pseudospectrum
Returns
SL_RTL_ERROR_SUCCESS if successful