ranging_algorithm.h

Enhance ranging performance.

Copyright

Copyright (C) 2020 SPARK Microsystems International Inc. All rights reserved.

License

This source code is proprietary and subject to the SPARK Microsystems Software EULA found in this package in file EULA.txt.

Author

SPARK FW Team.

Defines

RANGING_MAX_SIZE 256

Typedefs

typedef void (*fptr_algorithm_t)(algorithm_param_t *ranging_instance_parameter, void *distance)

Function pointer for internal ranging calculation.

Enums

enum ranging_algo_sel_t

Ranging algorithm selection enumeration.

Values:

enumerator RANGING_RAW = 0

No algorithm applied, return raw data

enumerator RANGING_DATA_CORRECTED = 1

SPARK algorithm for correction of ranging data

enumerator RANGING_DATA_FIXED_POINT_RAW = 2

No algorithm applied, return raw data using fixed point only

enumerator RANGING_DATA_FIXED_POINT_CORRECTED = 3

SPARK fixed point algorithm for correction of ranging data

Functions

void ranging_algorithm_init(ranging_instance_t *self, ranging_algo_sel_t algo_selection, uint16_t max_size, int32_t offset, uint8_t fixed_point_precision)

Ranging initialization.

Note

max_size must be scale with RANGING_SCALING to ensure uniformity between fixed and floating point arithmetic.

Parameters

  • self – [in] Ranging handler.

  • algo_selection – [in] Selection of the algorithm.

  • max_size – [in] Size of the array.

  • offset – [in] Data offset for accurate measurement.

  • fixed_point_precision – [in] Precision bits when using fixed point based algorithm.

Returns

Ranging instance.

bool ranging_algorithm_append(ranging_instance_t *self, ranging_info_t *master_info, ranging_info_t *slave_info)

Append data for ranging calculation.

Parameters

  • self – [in] Ranging handler.

  • master_info – [in] Master ranging information.

  • slave_info – [in] Slave_ranging information.

Returns True

At least avg_size new data have been added.

Returns False

Less than avg_size data have been added.

float ranging_algorithm_calculate_float(ranging_instance_t *self)

Calculate distance in float.

This method will compute the distance based on multiple measurement of ranging, base on the user settings. Regardless of the chosen algorithm, the returned distance is in floating point.

Note

This method can be call even if the ranging algorithm instance has been initialize using fixed point. All of the computation is still done using fixed point but the distance is converted to float at the very end.

Parameters

self – [in] Ranging handler.

Returns

Distance in meters.

q_num_t ranging_algorithm_calculate_qnum(ranging_instance_t *self)

Calculate distance in fixed point.

This method will compute the distance based on multiple measurement of ranging, base on the user settings. The computation are all done using fixed point arithmetic.

Note

This method always returned -1 if the chosen algorithm is not using fixed point arithmetic.

Parameters

self – [in] Ranging handler.

Returns

Distance in meters.

bool ranging_algorithm_is_buffer_full(ranging_instance_t *self)

Verify if module have accumulated it’s average size data.

Parameters

self – [in] Ranging handler.

Returns

bool True if the buffer is full.

void ranging_algorithm_set_avg_size(ranging_instance_t *self, uint16_t avg_size)

Set a new ranging average size.

Parameters

  • self – [in] Ranging handler.

  • avg_size – [in] Average size to be set.

void ranging_algorithm_clear(ranging_instance_t *self)

Clear ranging algorithm and ranging dev buffers.

Parameters

self – [in] Ranging handler.

uint8_t ranging_algorithm_update_powerup_delay(ranging_instance_t *self, uint8_t *packet_count)

Update power-up delay value based on packet count and average size.

Parameters

  • self – [in] Ranging handler.

  • packet_count – [in] Packet count.

Returns

Power-up delay value.

union ranging_distance_t
#include <ranging_algorithm.h>

Ranging distance union.

Public Members

float floating_point

Distance, in floating point.

q_num_t q_rep

Distance, in Q representation.

struct ranging_fp_struct_t
#include <ranging_algorithm.h>

Ranging algorithm fixed point elements structure.

Public Members

fp_format_t fp_parameters

Fixed point precision and integer bits value

ranging_dynamic_constants_t fp_constants

Dynamic constants used for fixed point calculation

struct algorithm_param_t
#include <ranging_algorithm.h>

Function pointer structure parameter.

Public Members

ranging_master_slave_info_t ranging_data[RANGING_MAX_SIZE]

Master and slave ranging info structure.

ranging_fp_struct_t fixed_point_inst

Fixed point elements needed for ranging

float pwrup_delay_step

Increase step of the power-up delay

int32_t offset

Offset to be applied

uint16_t current_avg_size

Current average size

uint16_t avg_size

Maximum size of sample

uint8_t pwrup_delay_sequence_length

Length of the power-up delay sequence

struct ranging_instance_t
#include <ranging_algorithm.h>

Ranging algorithm parameters structure.

Public Members

fptr_algorithm_t calculate_ranging

Function that will calculate distance based on ranging value

ranging_algo_sel_t ranging_algorithm_sel

Ranging algorithm to be used

algorithm_param_t algorithm_parameter

Parameter needed for ranging calculation depending on chosen algorithm