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

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.