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.
|
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_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) |
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:
- Initialize a sl_rtl_aox_libitem instance.
- Setup the antenna array and angle calculation parameters.
- Create the estimator.
- Set the antenna switching pattern.
- Input the I/Q data into the libitem.
- 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 |
◆ sl_rtl_clib_iq_sample_qa_dataset_t
struct sl_rtl_clib_iq_sample_qa_dataset_t |
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
◆ sl_rtl_aox_mode
enum sl_rtl_aox_mode |
AoX estimator mode.
◆ sl_rtl_aox_constraint_type
◆ sl_rtl_aox_switch_pattern_mode
◆ sl_rtl_slib_iq_sample_qa_result_t
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 constraint 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 would mean 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
The IQ sample quality analysis is not done by default, this function turns the functionality on.
◆ 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 overal results.
- Parameters
-
[in] item
Pointer to the initialized and configured AoX libitem
- Returns
- bitmask of found problems, zero means 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 all the 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 all the 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. That 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 the 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. This function can be used for getting the number of snaphots for allocating 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. In case this function has not been called, a default switch pattern of: 0, 1, 2, 3, ..., N-1 will be used, where N is the number of antennas. This function can be called 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. Calling this function updates switching pattern used by the estimator algorithm. This function must be called before calling function sl_rtl_aox_process. This function can be called 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_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. This function can be called 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 andSL_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. Needs to be called 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.