Ranging Core API

The Ranging Core API is the set of public functions the application can use to measure the distance seperating two devices.

Initialization

Normally, the Initiator will have the role of Coordinator in the target SWC connection. The Responder is consequently acting as a Node, thus awaits communication from the Coordinator before taking any action. While being a straightforward configuration, it is not required to assign the roles like so. The user can reverse the roles for the target wireless connection (Initiator acting as Node and Responder acting as Coordinator) but doing so will require the Responder to start the packet exchange, making the process less efficient.

The ranging core uses data provided by the Wireless Core to calculate a distance. To enable this feature, all the wireless connections destined for ranging usage must have their configurations’ ranging_enabled field set to true. Visit the Wireless Connection Configuration section for details. Also, the Initiator device needs to know how many ranging data sets it needs to accumulate on its receiving connection before a Wireless Core callback triggers. The target application function to execute once all samples are acquired must be set with swc_connection_set_ranging_data_ready_callback(). Therefore, this connection’s configuration needs to have its sample_count field within the ranging_settings structure set to a number of samples between 8 and 128 depending on the desired precision and latency.

The user must configure the callback target function through the Wireless Core API by providing an application-level function’s pointer. In this function, the user will be able to get the ranging data sets using swc_get_ranging_data() and pass them to one of the Ranging Core functions. Once the data is completely processed and can be discarded, the user must call swc_ranging_data_complete() to let the Wireless Core know that it can discard the data. Once done, the Wireless Core will automatically restart accumulating new data sets for another ranging measurement.

Moreover, for ranging to work properly, it is mandatory to enable auto-replies by setting the connections’ ack_enabled parameter, just like the ranging parameter ranging_enabled. Automatic acknowledgements from the Responder to the Initiator is necessary to guarantee a deterministic reply delay.

Distance Calibration

Calibration is used to compensate for a fixed delay overhead. This function must be called once for every ranging-enabled connection on the Initiator only.

uint32_t srac_calibrate(srac_data_set_t *ranging_data, uint8_t sample_count, srac_error_t *err);

Note that this function should be called only when both devices (i.e. Initiator and Responder) are exactly 0.5 meters apart from each other.

Distance Processing

Once the required number of samples is accumulated, the following function must be called to process the data set and return a distance value:

uint32_t srac_process_distance(srac_data_set_t *ranging_data, uint8_t sample_count, uint32_t calibration_offset, srac_error_t *err);

Note that a calibration offset must be provided for an accurate distance measurement. A default calibration value can be used (SRAC_DEFAULT_OFFSET_MM), but for optimal results the calibration procedure must be followed first; it will provide an optimal calibration offset value.

Using the API

Once the wireless core callback occurs, the user must take the data and send it to srac_calibrate() or srac_process_distance(). While not mandatory, the the highest possible sample count (128) should be used before calling srac_calibrate() for better calibration accuracy.

Calibration must be done at least once for each Initiator’s receiving connections with ranging_enabled set to true. The resulting calibration offset must be saved and passed to all subsequent calls to srac_process_distance() to obtain calibrated distance measurements.

The Responder device does not need to call any of the Ranging Core functions as its role is only to provide timing information for the Initiator inside its payload. This is managed by the Wireless Core when the ranging_enabled field is set to true in the Responder’s connections configurations.

Note that a ranging data set that was used for calibration using srac_calibrate() can be reused for distance calculation with the newly obtained calibration offset using srac_process_distance().

References

sdk_spark_vx.y.z/
└── core/
    └── ranging/
        └── api/
             ├── srac_api.h
             └── srac_error.h

File name

Description

srac_api.h

The API itself. This header file must be included in the user’s application in order to use the Ranging Core.

srac_error.h

Ranging Core error codes.