API documentation

Distance Measurement interface 

group nrf_dm

Interface for the Nordic distance measurement library.

Defines

NRF_DM_DEFAULT_SINGLE_ANTENNA_CONFIG

NRF_DM_DEFAULT_ANTENNA_COMP

NRF_DM_DEFAULT_CONFIG: Default configuration define, note that both role and rng_seed needs to be configured even when using the default config.

NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US: Maximum overhead duration in microseconds for pre- and post-processing in nrf_dm_proc_execute when executing in initiator role.The full (expected) duration of the call to nrf_dm_proc_execute is given by: nrf_dm_get_duration_us(&config) + NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US.

NRF_DM_CHANNEL_MAP_LEN: This is the length, in number of channels, of the channel map used within the library.

Enums

enum nrf_dm_quality_t

Quality of the procedure.

Values:

enumerator NRF_DM_QUALITY_OK

enumerator NRF_DM_QUALITY_POOR

enumerator NRF_DM_QUALITY_DO_NOT_USE

enumerator NRF_DM_QUALITY_CRC_FAIL

enum nrf_dm_sinr_indicator_t

SINR indicator for IQ measurements.

Values:

enumerator NRF_DM_SINR_INDICATOR_HIGH

enumerator NRF_DM_SINR_INDICATOR_MEDIUM

enumerator NRF_DM_SINR_INDICATOR_LOW

enumerator NRF_DM_SINR_INDICATOR_VERY_LOW

enum nrf_dm_role_t

Role definition.

Values:

enumerator NRF_DM_ROLE_NONE

enumerator NRF_DM_ROLE_INITIATOR: Act as an initiator

enumerator NRF_DM_ROLE_REFLECTOR: Act as a reflector

enum nrf_dm_status_t

Status of the procedure.

Values:

enumerator NRF_DM_STATUS_SUCCESS

enumerator NRF_DM_STATUS_FAIL_SYNC

enumerator NRF_DM_STATUS_EVENT_FAIL_TIMEOUT

enumerator NRF_DM_STATUS_CONF_INVALID

enum nrf_dm_ranging_mode_t

Ranging modes.

Values:

enumerator NRF_DM_RANGING_MODE_RTT

enumerator NRF_DM_RANGING_MODE_MCPD

enum nrf_dm_antenna_composition_t

Configuration options for antenna configurations.

Note

Only NRF_DM_ANTENNA_COMP_1_1 is supported.

Values:

enumerator NRF_DM_ANTENNA_COMP_1_1: Initiator uses 1 antenna, reflector uses 1 antenna.

enumerator NRF_DM_ANTENNA_COMP_2_1: Initiator uses 2 antenna, reflector uses 1 antenna.

enumerator NRF_DM_ANTENNA_COMP_3_1: Initiator uses 3 antenna, reflector uses 1 antenna.

enumerator NRF_DM_ANTENNA_COMP_4_1: Initiator uses 4 antenna, reflector uses 1 antenna.

enumerator NRF_DM_ANTENNA_COMP_1_2: Initiator uses 1 antenna, reflector uses 2 antenna.

enumerator NRF_DM_ANTENNA_COMP_1_3: Initiator uses 1 antenna, reflector uses 3 antenna.

enumerator NRF_DM_ANTENNA_COMP_1_4: Initiator uses 1 antenna, reflector uses 4 antenna.

enumerator NRF_DM_ANTENNA_COMP_2_2: Initiator uses 2 antenna, reflector uses 2 antenna.

Functions

void nrf_dm_init(const nrf_dm_ppi_config_t *ppi_cfg, const nrf_dm_antenna_config_t *antenna_cfg, NRF_TIMER_Type *timer)

Initialize the distance measurement procedure.

Parameters:

ppi_cfg – [in] PPI channels to be used by the library. The required amount of PPI channels is defined by the maximum hamming distance between two successive patterns in nrf_dm_antenna_config_t::switch_pattern divided by two. On the nrf53 series, only 2 DPPI channels are used. A minimum of 2 PPI channels need to be supplied, even if a single antenna is used.
antenna_cfg – [in] The configuration to use for antenna switching
timer – [in] What timer do you want me to use?

nrf_dm_status_t nrf_dm_configure(const nrf_dm_config_t *config)

Configures the distance measurement procedure.

Parameters:

config – [in] Pointer to configuration instance

uint32_t nrf_dm_get_duration_us(const nrf_dm_config_t *config)

Get the duration in microseconds that it will take to execute the distance measurement in initiator role with the given configuration. A reflector needs to reserve more time because it needs to be waiting for the initiators initial sync packet.

Note

A call to nrf_dm_proc_execute will take more time to execute for a given config, since that also includes some pre-processing and post-processing. To get the full expected duration use the constant defined below NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US: nrf_dm_get_duration_us(&config) + NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US

Parameters:

config – [in] Pointer to configuration instance

Returns:

Duration in microseconds.

nrf_dm_status_t nrf_dm_proc_execute(uint32_t timeout_us)

Start the distance measurement.

Note

Reflector will wait for sync, while initiator will start immediately. After completion it’s possible to request distance with nrf_dm_calc.

Parameters:

timeout_us – [in] If the distance measurement is not complete within this time the measurment will be aborted. For the measurement to complete the timeout must be at least the duration given by nrf_dm_get_duration_us for the used configuration nrf_dm_config_t plus the overhead given by the constant NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US. A reflector should typically use a larger timeout because it needs to wait for the initial sync packet sent by the initiator.

Returns:

A status code, NRF_DM_STATUS_SUCCESS if the measurement is successful, otherwise an appropriate failure status.

void nrf_dm_populate_report(nrf_dm_report_t *p_report)

Partially populate the report. This populates the report but does not set the distance estimates and the quality.

Parameters:

p_report – [out] Report populated with the raw data from the last ranging.

void nrf_dm_get_hopping_sequence(const nrf_dm_config_t *config, uint8_t hopping_sequence[75])

Get the channel hopping sequence used for a given configuration instance.

Note

The hopping sequence is given as a sequence of indexes, where the corresponding RF frequency is 2.4GHz + (index * 1MHz).

Parameters:

config – [in] Pointer to configuration instance
hopping_sequence – [out] Array to which the hopping sequence will be written. needs to be of length NRF_DM_CHANNEL_MAP_LEN

nrf_dm_quality_t nrf_dm_calc(nrf_dm_report_t *p_report)

Estimate the distance Fills nrf_dm_report_t with distance estimates either mcpd or rtt according to the raw data in the report.

Note

The report needs to be populated using nrf_dm_populate_report before nrf_dm_calc can be called.

Parameters:

p_report – [inout] Report containing the raw data where the result is written into.

Returns:

A quality measure of the estimated distance.

float nrf_dm_high_precision_calc(nrf_dm_report_t *p_report)

Estimate the distance with more computation-intensive higher precision algorithm.

Note

Only works with MCPD ranging mode.

Note

The report needs to be populated using nrf_dm_populate_report before nrf_dm_high_precision_calc can be called.

Parameters:

p_report – [inout] Report containing the raw data where the result is written into.

Returns:

The estimated distance in meters.

const char *nrf_dm_version_string_get(void): Get a null-terminated string containing the library revision.

struct nrf_dm_iq_tones_t

#include <nrf_dm.h>

Container of IQ values for local and remote measured tones.

Public Members

float i_local[80]: In-phase measurements of tones on this device

float q_local[80]: Quadrature-phase measurement of tones on this device

float i_remote[80]: In-phase measurements of tones from remote device

float q_remote[80]: Quadrature-phase measurements of tones from remote device

struct nrf_dm_iq_tones_sinr_indicator_t

#include <nrf_dm.h>

Public Members

nrf_dm_sinr_indicator_t sinr_indicator_local[80]: SINR-Indicator for tones on this device

nrf_dm_sinr_indicator_t sinr_indicator_remote[80]: SINR-Indicator for tones on peer device

union nrf_dm_dist_estimates_t

#include <nrf_dm.h>

Container of distance estimate results for a number of different methods, in meters.

Public Members

struct nrf_dm_dist_estimates_t._mcpd mcpd

struct nrf_dm_dist_estimates_t._rtt rtt

struct _mcpd

#include <nrf_dm.h>

Public Members

float ifft: MCPD: Distance estimate based on IFFT of spectrum

float phase_slope: MCPD: Distance estimate based on average phase slope estimation

float rssi_openspace: RSSI: Distance estimate based on Friis path loss formula

float best: Best effort distance estimate

struct _rtt

#include <nrf_dm.h>

Public Members

float rtt: RTT: Distance estimate based on RTT measurement

struct nrf_dm_report_t

#include <nrf_dm.h>

Output data for distance estimation.

Public Members

nrf_dm_iq_tones_t iq_tones[(1)]: IQ values for local and remote measured tones. NOTE: make sure to only read data from the antennas that were configured in nrf_dm_configure(). If the device uses N antennas, then the local values for N entries of iq_tones are valid. If the peer uses M antennas, then the remote values for M entries of iq_tones are valid.

nrf_dm_iq_tones_sinr_indicator_t tone_sinr_indicators: SINR-Indicators for the tones in iq_tones[0]

nrf_dm_ranging_mode_t ranging_mode: Mode used for ranging

nrf_dm_dist_estimates_t distance_estimates: Distance estimate results

nrf_dm_status_t status: Status of procedure

uint8_t link_loss: Computed link loss (TX power - RSSI)

uint8_t rssi_local: RSSI measured on this device on packets from remote

uint8_t rssi_remote: RSSI measured on remote devices on packets from this device

int8_t txpwr_local: TX power on this device

int8_t txpwr_remote: TX power on remote device

nrf_dm_quality_t quality: Quality indicator

int32_t rtt_accumulated_ns: Total time measured during RTT measurements

uint8_t rtt_count: Number of RTT measurements taken

struct nrf_dm_antenna_gpio_t

#include <nrf_dm.h>

Public Members

uint8_t gpio: GPIO pin attached to antenna switch.

uint8_t gpio_te: GPIO_TE channel used for the antenna switching.

struct nrf_dm_antenna_config_t

#include <nrf_dm.h>

Public Members

uint8_t antenna_gpios_count: Number of used GPIO pins defined in antenna_gpios

nrf_dm_antenna_gpio_t *antenna_gpios: GPIO pins for the antenna switching

uint8_t switch_pattern_count: Number of antenna patterns defined in switch_pattern

uint32_t *switch_pattern: Switch pattern to be used for antenna switching. Expected to be an array of length switch_pattern_count. Each entry in the array defines an antenna configuration. If bit N is set in a configuration, GPIO pin N in antenna_gpios is set. NOTE: to limit the amount of PPI channels used, minimise the hamming distance between two successive patterns

struct nrf_dm_ppi_config_t

#include <nrf_dm.h>

Public Members

uint8_t ppi_chan_count: Number of PPI channels passed to the library

uint8_t *ppi_chan: PPI channels passed to the library.

struct nrf_dm_config_t

#include <nrf_dm.h>

Public Members

nrf_dm_role_t role: Role of the device

nrf_dm_ranging_mode_t ranging_mode: Ranging mode to use in the procedure

uint32_t rng_seed: Seed used in pseudo random number generation. Needs to be the same for an initiator and a reflector that will range with eachother.

uint32_t tx_power_dbm: Radio transmit power, given in dBm. Valid values defined in nrfXXXXX_bitfields.h, as RADIO_TXPOWER_TXPOWER_YYYYdBm

nrf_dm_antenna_composition_t ant_comp: Antenna composition of initiator and reflector.

API documentation

Distance Measurement interface

Distance Measurement interface 