Location Finding#

sl_rtl_loc_locator_measurement_field#

sl_rtl_loc_locator_measurement_field

Locator-specific measurements.

sl_rtl_loc_target_measurement_field#

sl_rtl_loc_target_measurement_field

Target-specific measurements - Not yet supported.

sl_rtl_loc_estimation_mode#

sl_rtl_loc_estimation_mode

Estimation mode.

sl_rtl_loc_measurement_validation_method#

sl_rtl_loc_measurement_validation_method

Measurement validation method.

sl_rtl_loc_locator_parameter#

sl_rtl_loc_locator_parameter

Locator-specific parameters related to locationing.

sl_rtl_loc_default_accuracy_parameter#

sl_rtl_loc_default_accuracy_parameter

sl_rtl_loc_target_parameter#

sl_rtl_loc_target_parameter

Target-specific parameters related to locationing.

sl_rtl_loc_result#

sl_rtl_loc_result

Locationing state results.

sl_rtl_loc_libitem#

typedef void* sl_rtl_loc_libitem

Locationing library item.

sl_rtl_loc_init#

enum sl_rtl_error_code sl_rtl_loc_init (sl_rtl_loc_libitem *item)

Initialize the locationing libitem instance.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_deinit#

enum sl_rtl_error_code sl_rtl_loc_deinit (sl_rtl_loc_libitem *item)

Deinitialize the locationing libitem instance.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_reinit#

enum sl_rtl_error_code sl_rtl_loc_reinit (sl_rtl_loc_libitem *item)

Reinitialize the locationing libitem instance.

Reset the libitem's internal values to the starting point so that it can start all over from the beginning. This can be used, for example, in testing instead of deleting and re-creating the libitem object.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_mode#

enum sl_rtl_error_code sl_rtl_loc_set_mode (sl_rtl_loc_libitem *item, enum sl_rtl_loc_estimation_mode mode)

Set the locationing dimensionality mode. Possible choices are 2D or 3D modes. Two-dimensional mode does not vary the z-position of the target and assumes it is 0 at all times. When updating, for example, the distance measure- ment from the locator to the target in 2D mode, it should be noted that even if the locator and tag are on different z-planes, the distance should be given as the distance as if they were on the same z-plane.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_measurement_validation#

enum sl_rtl_error_code sl_rtl_loc_set_measurement_validation (sl_rtl_loc_libitem *item, enum sl_rtl_loc_measurement_validation_method method)

Set the measurement validation method. If not given, the minimum method is used. Possible choices are minimum, medium, and full. The minimum does not increase the calculation CPU load because it is integrated inside the algorithm's normal operation. The medium and full methods use additionally one or multiple calculation rounds respectively and may discard the most inaccurate measurements from the calculation. However, they will always leave enough of them to calculate the estimate.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_add_locator#

enum sl_rtl_error_code sl_rtl_loc_add_locator (sl_rtl_loc_libitem *item, struct sl_rtl_loc_locator_item *locator_item, uint32_t *locator_id_out)

Add a locator item into the locationing estimator after setting its position and orientation parameters. Add all locators using this function before calling sl_rtl_loc_create_position_estimator to create the estimator instance.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_add_tag#

enum sl_rtl_error_code sl_rtl_loc_add_tag (sl_rtl_loc_libitem *item, int32_t *tag_id_out)

Add an asset tag item into the locationing estimator.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_remove_tag#

enum sl_rtl_error_code sl_rtl_loc_remove_tag (sl_rtl_loc_libitem *item, int32_t tag_id)

Remove an asset tag item previously added with sl_rtl_loc_add_tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_create_position_estimator#

enum sl_rtl_error_code sl_rtl_loc_create_position_estimator (sl_rtl_loc_libitem *item)

Create the position estimator instance after all locators have been added.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_locator_parameter#

enum sl_rtl_error_code sl_rtl_loc_set_locator_parameter (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_parameter parameter, float value)

Set locator-specific parameters, such as the azimuth and elevation measurement covariances.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_target_parameter#

enum sl_rtl_error_code sl_rtl_loc_set_target_parameter (sl_rtl_loc_libitem *item, enum sl_rtl_loc_target_parameter parameter, float value)

Set target-specific parameters, such as the known target height.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_target_parameter_tag#

enum sl_rtl_error_code sl_rtl_loc_set_target_parameter_tag (sl_rtl_loc_libitem *item, enum sl_rtl_loc_target_parameter parameter, float value, int32_t tag_id)

Set target-specific parameters, such as the known target height for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_clear_measurements#

enum sl_rtl_error_code sl_rtl_loc_clear_measurements (sl_rtl_loc_libitem *item)

Clear previous measurements. Call this function before setting new measurements if the previous measurements are not valid for the next iteration step.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_clear_measurements_tag#

enum sl_rtl_error_code sl_rtl_loc_clear_measurements_tag (sl_rtl_loc_libitem *item, int32_t tag_id)

Clear previous measurements for a specified tag. Call this function before setting new measurements if the previous measurements are not valid for the next iteration step.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_locator_measurement#

enum sl_rtl_error_code sl_rtl_loc_set_locator_measurement (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float value)

Set a new measurement for a locator specified by the locator ID.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_locator_measurement_tag#

enum sl_rtl_error_code sl_rtl_loc_set_locator_measurement_tag (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float value, int32_t tag_id)

Set a new measurement for a locator specified by the locator ID for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_target_measurement#

enum sl_rtl_error_code sl_rtl_loc_set_target_measurement (sl_rtl_loc_libitem *item, enum sl_rtl_loc_target_measurement_field field, float value)

Set a new measurement for the target. Because the current version does not support this function, calling it has no effect.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_set_default_accuracy#

enum sl_rtl_error_code sl_rtl_loc_set_default_accuracy (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_default_accuracy_parameter param, float value)

Set the default accuracy value for direction / distance. This value will be used if not given explicitly by measurement.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_process#

enum sl_rtl_error_code sl_rtl_loc_process (sl_rtl_loc_libitem *item, float time_step)

Process the current time step of the locationing filter. Call this function after old measurements are cleared and new measurements are set for the current time step. The process will step the filter forward and provide new state results and state covariance values, which can be retrieved with separate function calls.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_process_tag#

enum sl_rtl_error_code sl_rtl_loc_process_tag (sl_rtl_loc_libitem *item, float time_step, int32_t tag_id)

Process the current time step of the locationing filter for a specified tag. Call this function after old measurements are cleared and new measurements are set for the current time step. The process will step the filter forward and provide new state results and state covariance values, which can be retrieved with separate function calls.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_result#

enum sl_rtl_error_code sl_rtl_loc_get_result (sl_rtl_loc_libitem *item, enum sl_rtl_loc_result result, float *value)

Get result of the current state variables or state covariances.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_result_tag#

enum sl_rtl_error_code sl_rtl_loc_get_result_tag (sl_rtl_loc_libitem *item, enum sl_rtl_loc_result result, float *value, int32_t tag_id)

Get result of the current state variables or state covariances for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_measurement_in_system_coordinates#

enum sl_rtl_error_code sl_rtl_loc_get_measurement_in_system_coordinates (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float *value_out)

Get the latest measurement converted into the coordinate system of the multi-locator system.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_measurement_in_system_coordinates_tag#

enum sl_rtl_error_code sl_rtl_loc_get_measurement_in_system_coordinates_tag (sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float *value_out, int32_t tag_id)

Get the latest measurement converted into the coordinate system of the multi-locator system for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_expected_direction#

enum sl_rtl_error_code sl_rtl_loc_get_expected_direction (sl_rtl_loc_libitem *item, uint32_t locator_id, float *azimuth, float *elevation, float *distance)

Get the expected direction of the asset for the locator.

Returns

• SL_RTL_ERROR_SUCCESS if the locator does not require correction

• SL_RTL_ERROR_INCORRECT_MEASUREMENT if the locator's previous measurement was ignored because the error is too large

• Another error code in case of error

Position calculation has a better overall view to the asset's location than any individual locator. If the direction angles differ too much from the expected direction, the locator can be instructed to correct its internal state so that in can recover from this incorrectness faster. See also sl_rtl_aox_set_expected_direction()

sl_rtl_loc_get_expected_direction_tag#

enum sl_rtl_error_code sl_rtl_loc_get_expected_direction_tag (sl_rtl_loc_libitem *item, uint32_t locator_id, float *azimuth, float *elevation, float *distance, int32_t tag_id)

Get the expected direction of the asset for the locator for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if the locator does not require correction

• SL_RTL_ERROR_INCORRECT_MEASUREMENT if the locator's previous measurement was ignored because of too large error

• Another error code in case of error

Position calculation has a better overall view to the asset's location than any individual locator. If the direction angles differ too much from the expected direction, the locator can be instructed to correct its internal state so that in can recover from this incorrectness faster. See also sl_rtl_aox_set_expected_direction().

sl_rtl_loc_get_expected_deviation#

enum sl_rtl_error_code sl_rtl_loc_get_expected_deviation (sl_rtl_loc_libitem *item, uint32_t locator_id, float *azimuth, float *elevation, float *distance)

Get the deviation values for expected direction of the asset for the locator.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_expected_deviation_tag#

enum sl_rtl_error_code sl_rtl_loc_get_expected_deviation_tag (sl_rtl_loc_libitem *item, uint32_t locator_id, float *azimuth, float *elevation, float *distance, int32_t tag_id)

Get the deviation values for expected direction of the asset for the locator for a specified tag.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_get_number_disabled#

int sl_rtl_loc_get_number_disabled (sl_rtl_loc_libitem *item)

Get the number of locators, which are disabled from position calculation because the direction error is too large.

Returns

• Number of locators needing correction, or -1 in case of any other error

sl_rtl_loc_get_number_disabled_tag#

int sl_rtl_loc_get_number_disabled_tag (sl_rtl_loc_libitem *item, int32_t tag_id)

Get the number of locators, which are disabled from position calculation because the direction error is too large, for a specified tag.

Returns

• Number of locators needing correction, or -1 in case of any other error

sl_rtl_loc_filter_in_reach#

bool sl_rtl_loc_filter_in_reach (sl_rtl_loc_libitem *item, uint32_t locator_id)

Check if the asset is in reach of a given locator according to the position-based filtering.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_clear#

enum sl_rtl_error_code sl_rtl_loc_filter_clear (sl_rtl_loc_libitem *item, uint32_t locator_id)

Clear all the position-based filters from a locator or from all locators.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_sphere#

enum sl_rtl_error_code sl_rtl_loc_filter_sphere (sl_rtl_loc_libitem *item, uint32_t locator_id, float radius, bool exclude_region)

Add a position-based filter. This filter is based on the distance from a locator. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_circle#

enum sl_rtl_error_code sl_rtl_loc_filter_circle (sl_rtl_loc_libitem *item, uint32_t locator_id, float radius, bool exclude_region)

Add a position-based filter. The two dimensional filter is based on the distance from a locator. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_box#

enum sl_rtl_error_code sl_rtl_loc_filter_box (sl_rtl_loc_libitem *item, uint32_t locator_id, float xDelta, float yDelta, float zDelta, bool exclude_region)

Add a position-based filter. This filter defines relative distances in coordinate axes' directions. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_rect#

enum sl_rtl_error_code sl_rtl_loc_filter_rect (sl_rtl_loc_libitem *item, uint32_t locator_id, float xDelta, float yDelta, bool exclude_region)

Add a position-based filter. This two dimensional filter defines relative distances in coordinate axes' directions. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_room#

enum sl_rtl_error_code sl_rtl_loc_filter_room (sl_rtl_loc_libitem *item, uint32_t locator_id, float minX, float maxX, float minY, float maxY, float minZ, float maxZ, bool exclude_region)

Add a position-based filter. This filter defines an area in global coordinates. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_filter_floor#

enum sl_rtl_error_code sl_rtl_loc_filter_floor (sl_rtl_loc_libitem *item, uint32_t locator_id, float minX, float maxX, float minY, float maxY, bool exclude_region)

Add a position-based filter. The two dimensional filter defines an area in global coordinates. The filter can be added to one locator or all locators. A locator may have several filters which are combined.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_enable_trilateration#

enum sl_rtl_error_code sl_rtl_loc_enable_trilateration (sl_rtl_loc_libitem *item, bool value)

Enable trilateration method in location calculation.

The trilateration method calculates the position based on the distances from the locators rather than the direction angles. This function enables the method, but the location calculation may still utilize also the directon if available to further increase the accuracy.

Trilateration method is not turned on by default.

Returns

• SL_RTL_ERROR_SUCCESS if successful

sl_rtl_loc_trilateration_prefer_below_plane#

enum sl_rtl_error_code sl_rtl_loc_trilateration_prefer_below_plane (sl_rtl_loc_libitem *item, bool value)

Prefer the asset location below or above the locator plane.

If the locators are all in the same plane (or close to it), the height of the asset may become ambiguous. Set the preference to be below or above plane so that is more likely to end up in the correct position.

The default options is below the plane.

Returns

• SL_RTL_ERROR_SUCCESS if successful

SL_RTL_LOC_ALL_LOCATORS#

#define SL_RTL_LOC_ALL_LOCATORS

(uint32_t)(-1)

SL_RTL_LOC_ALL_TAGS#

#define SL_RTL_LOC_ALL_TAGS

INT32_MAX