Real-Time Locationing Service#

sl_rtl_service_cs_ctx_t#

typedef struct sl_rtl_service_cs_ctx sl_rtl_service_cs_ctx_t

Opaque handle representing a Real-Time Locationing Service processing context.

sl_rtl_service_cs_inst_t#

typedef struct sl_rtl_service_cs_inst sl_rtl_service_cs_inst_t

Opaque handle representing a single CS measurement instance within a context.

sl_rtl_service_cs_result_t#

typedef struct sl_rtl_service_cs_result sl_rtl_service_cs_result_t

Opaque result handle, valid only during the result callback invocation.

sl_rtl_service_cs_result_cb_t#

typedef void(* sl_rtl_service_cs_result_cb_t) (sl_rtl_service_cs_inst_t *inst, const sl_rtl_service_cs_result_t *result, enum sl_rtl_error_code process_status, void *user_data) )(sl_rtl_service_cs_inst_t *inst, const sl_rtl_service_cs_result_t *result, enum sl_rtl_error_code process_status, void *user_data)

Result callback type.

Invoked after RTL processing completes for a given instance. The application can query distance estimates using result and the sl_rtl_service_get_cs_* family of functions from within this callback.

Note

• In RTOS this is called from the RTL task context. In bare-metal this is called synchronously from the super-loop step.

sl_rtl_service_rta_init_cs#

void sl_rtl_service_rta_init_cs (void )

sl_rtl_service_init_cs#

enum sl_rtl_error_code sl_rtl_service_init_cs (const sl_rtl_service_cs_config_t * config, sl_rtl_service_cs_ctx_t ** ctx)

Initialize the RTL service CS context.

Allocates a service context backed by an app_rta processing context with a dedicated thread (RTOS) or super-loop step (bare-metal), a mutex guard for thread-safe access, and a per-instance request slot. If the backing app_rta context is not currently present, it is created automatically.

Note

• Only one service context may exist at a time. Call sl_rtl_service_deinit_cs() before creating a new one. After deinit, this function may be called again to create a new service context.

Returns

• SL_RTL_ERROR_SUCCESS Context created successfully.

• SL_RTL_ERROR_ARGUMENT config or ctx is NULL, or config->result_cb is NULL.

• SL_RTL_ERROR_INTERNAL A context already exists.

• SL_RTL_ERROR_OUT_OF_MEMORY Memory allocation failed.

sl_rtl_service_deinit_cs#

enum sl_rtl_error_code sl_rtl_service_deinit_cs (sl_rtl_service_cs_ctx_t * ctx)

Deinitialize and free the RTL service CS context.

Destroys all remaining instances, cancels any pending requests, and tears down the underlying RTA context.

Warnings

• Must not be called from within a result callback. Doing so returns SL_RTL_ERROR_INTERNAL and leaves the context intact.

Returns

• SL_RTL_ERROR_SUCCESS Context torn down and freed.

• SL_RTL_ERROR_ARGUMENT ctx is NULL or does not match the active context.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed, or a result callback is currently in progress.

sl_rtl_service_create_cs_instance#

enum sl_rtl_error_code sl_rtl_service_create_cs_instance (sl_rtl_service_cs_ctx_t * ctx, sl_rtl_service_cs_inst_t ** inst)

Create an RTL service CS instance within a context.

Allocates an instance from the context's internal pool and initializes the underlying RTL library item. Multiple instances can share a single context (and thus a single processing task). The maximum number of instances per context is bounded by SL_RTL_SERVICE_CS_MAX_INSTANCES.

Returns

• SL_RTL_ERROR_SUCCESS Instance created successfully.

• SL_RTL_ERROR_ARGUMENT ctx or inst is NULL, or ctx is not the active context.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• SL_RTL_ERROR_OUT_OF_MEMORY Instance pool is full.

sl_rtl_service_destroy_cs_instance#

enum sl_rtl_error_code sl_rtl_service_destroy_cs_instance (sl_rtl_service_cs_inst_t * inst)

Destroy an RTL service CS instance.

Deinitializes the underlying RTL library item and returns the instance slot to the pool. Any pending processing request for this instance is cancelled.

Warnings

• Must not be called from within this instance's result callback. Doing so returns SL_RTL_ERROR_INTERNAL.

Returns

• SL_RTL_ERROR_SUCCESS Instance destroyed.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use.

• SL_RTL_ERROR_INTERNAL Called from within the result callback, or guard acquisition failed.

sl_rtl_service_set_cs_algo_mode#

enum sl_rtl_error_code sl_rtl_service_set_cs_algo_mode (sl_rtl_service_cs_inst_t * inst, sl_rtl_cs_algo_mode mode)

Set the estimation algorithm mode for an instance.

Thread-safe: acquires the parent context's RTA guard internally.

Returns

• SL_RTL_ERROR_SUCCESS Mode set successfully.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_create_cs_estimator

sl_rtl_service_set_cs_mode#

enum sl_rtl_error_code sl_rtl_service_set_cs_mode (sl_rtl_service_cs_inst_t * inst, sl_rtl_cs_mode main_mode, sl_rtl_cs_mode sub_mode)

Set the CS mode (main and sub) for an instance.

Thread-safe: acquires the parent context's RTA guard internally.

Returns

• SL_RTL_ERROR_SUCCESS Mode set successfully.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_create_cs_estimator

sl_rtl_service_set_cs_params#

enum sl_rtl_error_code sl_rtl_service_set_cs_params (sl_rtl_service_cs_inst_t * inst, const sl_rtl_cs_params * params)

Set the CS parameters for an instance.

Thread-safe: acquires the parent context's RTA guard internally.

Returns

• SL_RTL_ERROR_SUCCESS Parameters set successfully.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use, or params is NULL.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_create_cs_estimator

sl_rtl_service_create_cs_estimator#

enum sl_rtl_error_code sl_rtl_service_create_cs_estimator (sl_rtl_service_cs_inst_t * inst)

Create the estimator for an instance.

Thread-safe: acquires the parent context's RTA guard internally. Must be called after sl_rtl_service_set_cs_algo_mode(), sl_rtl_service_set_cs_mode(), and sl_rtl_service_set_cs_params().

Returns

• SL_RTL_ERROR_SUCCESS Estimator created successfully.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library.

sl_rtl_service_set_cs_estimator_param#

enum sl_rtl_error_code sl_rtl_service_set_cs_estimator_param (sl_rtl_service_cs_inst_t * inst, const sl_rtl_cs_estimator_param * param)

Set an estimator parameter for an instance.

Thread-safe: acquires the parent context's RTA guard internally. May be called at any time after the estimator is created, including while processing is in progress.

Returns

• SL_RTL_ERROR_SUCCESS Parameter set successfully.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use, or param is NULL.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library.

sl_rtl_service_enable_cs_log#

enum sl_rtl_error_code sl_rtl_service_enable_cs_log (sl_rtl_service_cs_inst_t * inst)

Enable RTL library structured logging for an instance.

Thread-safe: acquires the parent context's RTA guard internally. Must be called after sl_rtl_service_create_cs_instance() and before sl_rtl_service_create_cs_estimator(). Has no effect unless sl_rtl_log_init() and sl_rtl_log_configure() have been called first.

Returns

• SL_RTL_ERROR_SUCCESS Logging enabled for this instance.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• Other values forwarded from the underlying RTL library (e.g. SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED if called after sl_rtl_service_create_cs_estimator).

sl_rtl_service_process_cs#

enum sl_rtl_error_code sl_rtl_service_process_cs (sl_rtl_service_cs_inst_t * inst, const sl_rtl_cs_procedure * procedure)

Submit CS procedure data for processing on an instance.

Thread-safe: may be called from any task context. The request is queued internally and processed by the RTL processing task. The caller must keep procedure valid until the result callback fires for this instance.

At most one request per instance may be pending at a time. Requests for different instances are independent and may be submitted concurrently.

Note

• In bare-metal mode the callback fires synchronously before this function returns, so stack-allocated procedure data is safe. In RTOS mode the callback fires asynchronously from the RTL task; the data must remain valid beyond the caller's stack frame.

Returns

• SL_RTL_ERROR_SUCCESS Request accepted and queued.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use, or procedure is NULL.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• SL_RTL_ERROR_QUEUE_FULL This instance already has a pending request.

sl_rtl_service_process_ras#

enum sl_rtl_error_code sl_rtl_service_process_ras (sl_rtl_service_cs_inst_t * inst, const sl_rtl_ras_procedure * procedure)

Submit RAS procedure data for processing on an instance.

Thread-safe: may be called from any task context. Behaves identically to sl_rtl_service_process_cs() but accepts Ranging Service (RAS) procedure data. The caller must keep procedure valid until the result callback fires. At most one request per instance may be pending at a time.

Note

• In bare-metal mode the callback fires synchronously before this function returns. In RTOS mode the callback fires asynchronously from the RTL task.

Returns

• SL_RTL_ERROR_SUCCESS Request accepted and queued.

• SL_RTL_ERROR_ARGUMENT inst is NULL or not in use, or procedure is NULL.

• SL_RTL_ERROR_INTERNAL Guard acquisition failed.

• SL_RTL_ERROR_QUEUE_FULL This instance already has a pending request.

See Also

• sl_rtl_service_process_cs

sl_rtl_service_get_cs_distance_estimate#

enum sl_rtl_error_code sl_rtl_service_get_cs_distance_estimate (const sl_rtl_service_cs_result_t * result, sl_rtl_cs_distance_estimate_type estimate_type, sl_rtl_cs_distance_estimate_mode estimate_mode, float * distance)

Get distance estimate from a processing result.

Warnings

• Must only be called from within the result callback. The result handle is valid only for the duration of that callback invocation; behaviour is undefined if called outside.

Returns

• SL_RTL_ERROR_SUCCESS Estimate retrieved successfully.

• SL_RTL_ERROR_ARGUMENT result or distance is NULL.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_cs_result_cb_t

sl_rtl_service_get_cs_distance_estimate_confidence#

enum sl_rtl_error_code sl_rtl_service_get_cs_distance_estimate_confidence (const sl_rtl_service_cs_result_t * result, sl_rtl_cs_distance_estimate_confidence_type confidence_type, sl_rtl_cs_distance_estimate_confidence_mode confidence_mode, float * confidence)

Get distance estimate confidence.

Warnings

• Must only be called from within the result callback. The result handle is valid only for the duration of that callback invocation; behaviour is undefined if called outside.

Returns

• SL_RTL_ERROR_SUCCESS Confidence retrieved successfully.

• SL_RTL_ERROR_ARGUMENT result or confidence is NULL.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_cs_result_cb_t

sl_rtl_service_get_cs_distance_estimate_extended_info#

enum sl_rtl_error_code sl_rtl_service_get_cs_distance_estimate_extended_info (const sl_rtl_service_cs_result_t * result, sl_rtl_cs_distance_estimate_extended_info_type extended_info_type, float * extended_info)

Get distance estimate extended information.

Warnings

• Must only be called from within the result callback. The result handle is valid only for the duration of that callback invocation; behaviour is undefined if called outside.

Returns

• SL_RTL_ERROR_SUCCESS Information retrieved successfully.

• SL_RTL_ERROR_ARGUMENT result or extended_info is NULL.

• Other values forwarded from the underlying RTL library.

See Also

• sl_rtl_service_cs_result_cb_t