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.
typedef void * sl_rtl_aox_antenna_pattern
Angle of Arrival / Departure antenna array radiation pattern.

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_options { 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_AOA_MODE_ONE_SHOT_BASIC = 3, SL_RTL_AOA_MODE_ONE_SHOT_BASIC_LIGHTWEIGHT , SL_RTL_AOA_MODE_ONE_SHOT_FAST_RESPONSE , SL_RTL_AOA_MODE_ONE_SHOT_HIGH_ACCURACY ,
SL_RTL_AOA_MODE_ONE_SHOT_BASIC_AZIMUTH_ONLY , SL_RTL_AOA_MODE_ONE_SHOT_FAST_RESPONSE_AZIMUTH_ONLY , SL_RTL_AOA_MODE_ONE_SHOT_HIGH_ACCURACY_AZIMUTH_ONLY , SL_RTL_AOA_MODE_REAL_TIME_FAST_RESPONSE ,
SL_RTL_AOA_MODE_REAL_TIME_BASIC , SL_RTL_AOA_MODE_REAL_TIME_HIGH_ACCURACY , SL_RTL_AOA_MODE_LAST , SL_RTL_AOD_MODE_ONE_SHOT_BASIC = 3 | 0x20,
SL_RTL_AOD_MODE_ONE_SHOT_BASIC_LIGHTWEIGHT , SL_RTL_AOD_MODE_ONE_SHOT_FAST_RESPONSE , SL_RTL_AOD_MODE_ONE_SHOT_HIGH_ACCURACY , SL_RTL_AOD_MODE_ONE_SHOT_BASIC_AZIMUTH_ONLY ,
SL_RTL_AOD_MODE_ONE_SHOT_FAST_RESPONSE_AZIMUTH_ONLY , SL_RTL_AOD_MODE_ONE_SHOT_HIGH_ACCURACY_AZIMUTH_ONLY , SL_RTL_AOD_MODE_REAL_TIME_FAST_RESPONSE , SL_RTL_AOD_MODE_REAL_TIME_BASIC ,
SL_RTL_AOD_MODE_REAL_TIME_HIGH_ACCURACY , SL_RTL_AOD_MODE_LAST , SL_RTL_AOX_MODE_ONE_SHOT_BASIC = 3 | 0x40, 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
}
AoA, AoD (and AoX for backward compatibility) estimator modes.
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_aox_standard_deviation ( sl_rtl_aox_libitem *item, float *az_std_dev, float *el_std_dev)
static 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)
static enum sl_rtl_error_code sl_rtl_aox_get_latest_aod_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_polarization_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)
enum sl_rtl_error_code sl_rtl_aox_get_polarization_spectrum ( sl_rtl_aox_libitem *item, float **spectrum_out)
enum sl_rtl_error_code sl_rtl_aox_antenna_pattern_init ( sl_rtl_aox_antenna_pattern *pattern, enum sl_rtl_aox_array_type array_type)
enum sl_rtl_error_code sl_rtl_aox_set_antenna_pattern ( sl_rtl_aox_libitem *item, sl_rtl_aox_antenna_pattern *pattern)
enum sl_rtl_error_code sl_rtl_aox_antenna_pattern_deinit ( sl_rtl_aox_antenna_pattern *pattern)

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.

sl_rtl_aox_antenna_pattern

Angle of Arrival / Departure antenna array radiation pattern.

Enumeration Type Documentation

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

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_options

Enumerator
SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_DUAL_POLARIZED
SL_RTL_AOX_SWITCH_PATTERN_OPTIONS_EXTRA_REFERENCE

sl_rtl_aox_mode

AoA, AoD (and AoX for backward compatibility) estimator modes.

Enumerator
SL_RTL_AOA_MODE_ONE_SHOT_BASIC

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

SL_RTL_AOA_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_AOA_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_AOA_MODE_ONE_SHOT_HIGH_ACCURACY

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

SL_RTL_AOA_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_AOA_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_AOA_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_AOA_MODE_REAL_TIME_FAST_RESPONSE

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

SL_RTL_AOA_MODE_REAL_TIME_BASIC

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

SL_RTL_AOA_MODE_REAL_TIME_HIGH_ACCURACY

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

SL_RTL_AOA_MODE_LAST

Placeholder.

SL_RTL_AOD_MODE_ONE_SHOT_BASIC

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

SL_RTL_AOD_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_AOD_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_AOD_MODE_ONE_SHOT_HIGH_ACCURACY

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

SL_RTL_AOD_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_AOD_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_AOD_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_AOD_MODE_REAL_TIME_FAST_RESPONSE

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

SL_RTL_AOD_MODE_REAL_TIME_BASIC

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

SL_RTL_AOD_MODE_REAL_TIME_HIGH_ACCURACY

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

SL_RTL_AOD_MODE_LAST

Placeholder.

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

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

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

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 to correct 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()

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 checks 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.

When using a custom pattern in SL_RTL_AOX_SWITCH_PATTERN_MODE_EXTERNAL mode, the pattern in switch_pattern_in must not contain duplicate elements and the antenna indices must be within the range 0 to (number_of_antennas - 1). Number_of_antennas is the amount of antennas in the set array type, for example for the 4x4 URA this is 16 and for the 1x4 ULA this is 4. The length of the switching pattern must be equal to number_of_antennas.

Note: The RF switch pattern indices may be different to the indices required by the RTL algorithm. For example, a 1x4 ULA might use RF controls [12, 13, 14, 15] for switching the antennas 1-4, but the RTL algorithm requires the switch pattern [0, 1, 2, 3]. If the RF controls are switched as [14, 15, 13, 12], the RTL algorithm requires the pattern [2, 3, 1, 0].

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.
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
)

Convert switching pattern from antenna indices to antenna switching pin control logic. Call this function at run-time after initializing and creating the estimator.

Parameters
[in] item Pointer to the initialized and configured AoX libitem.
[in] array_id Array ID, see sl_rtl_aox_switch_pattern_array , for example SL_RTL_AOX_SWITCH_PATTERN_ARRAY_4x4_DP
[in] options Switch pattern options, see sl_rtl_aox_switch_pattern_options . Can be used to set for example dual polarization (default is single polarization).
[in] switch_pattern_size_in The length of the input switching pattern.
[in] switch_pattern_in The input switching pattern.
[out] switch_pattern_size_out The outputted length of the converted switching pattern.
[out] switch_pattern_out The outputted switching pattern.
Returns
SL_RTL_ERROR_SUCCESS if successful
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_aox_standard_deviation()

enum sl_rtl_error_code sl_rtl_aox_get_latest_aox_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_get_latest_aoa_standard_deviation()

static 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
)
inline static

Kept for backward compatibility

sl_rtl_aox_get_latest_aod_standard_deviation()

static enum sl_rtl_error_code sl_rtl_aox_get_latest_aod_standard_deviation ( sl_rtl_aox_libitem * item,
float * az_std_dev,
float * el_std_dev
)
inline static

Kept for backward compatibility

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 correctness 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. This function 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. This function should be called after calling the AoX process function.

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

sl_rtl_aox_get_polarization_spectrum_size()

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

Get the size of the polarization pseudospectrum. This function should be called after calling the AoX process function.

Parameters
[in] item Pointer to the initialized libitem.
[out] rows Number of rows in the polarization pseudospectrum data array.
[out] 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

sl_rtl_aox_get_polarization_spectrum()

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

Get the polarization spectrum. 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_polarization_spectrum_size() .

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

sl_rtl_aox_antenna_pattern_init()

enum sl_rtl_error_code sl_rtl_aox_antenna_pattern_init ( sl_rtl_aox_antenna_pattern * pattern,
enum sl_rtl_aox_array_type array_type
)

Initialize the antenna radiation pattern item for the given array board. The antenna pattern item can be shared by multiple different estimators.

Parameters
[in] pattern Pointer to the pattern item to initialize.
[in] array_type Array type of the board for which the pattern is loaded.
Returns
SL_RTL_ERROR_SUCCESS if successful

sl_rtl_aox_set_antenna_pattern()

enum sl_rtl_error_code sl_rtl_aox_set_antenna_pattern ( sl_rtl_aox_libitem * item,
sl_rtl_aox_antenna_pattern * pattern
)

Set the given estimator to use the given antenna radiation pattern in the model. The same antenna pattern can be shared between multiple estimators. The antenna pattern can be cleared for an estimator by setting it to NULL. The estimator will then use the default model.

Note
: This function should be called only after the estimator is created.
Parameters
[in] item Pointer to the initialized libitem.
[in] pattern Pointer to the initialized antenna pattern item.
Returns
SL_RTL_ERROR_SUCCESS if successful

sl_rtl_aox_antenna_pattern_deinit()

enum sl_rtl_error_code sl_rtl_aox_antenna_pattern_deinit ( sl_rtl_aox_antenna_pattern * pattern )

Deinitialize the antenna radiation pattern item.

Parameters
[in] pattern Pointer to the initialized pattern item.
Returns
SL_RTL_ERROR_SUCCESS if successful