API documentation

Distance Measurement interface

Distance Measurement interface 

group nrf_dm

Interface for the Nordic distance measurement library.

Defines

NRF_DM_DEFAULT_SINGLE_ANTENNA_CONFIG

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

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_role_t

Role definition.

Values:

enumerator NRF_DM_ROLE_NONE

enumerator NRF_DM_ROLE_INITIATOR: Act as a 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

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

nrf_dm_quality_t nrf_dm_calc(void)

Estimate the distance Fills nrf_dm_report_t with distance estimates either mcpd or rtt depending on which ranging mode was last executed.

Returns: A quality measure of the estimated distance.

float nrf_dm_high_precision_calc(void)

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

Note

Only works with MCPD ranging mode.

Returns: The estimated distance in meters.

const nrf_dm_report_t *nrf_dm_report_get(void): Get a pointer to output data from distance estimation.

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

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[4]: 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_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

struct nrf_dm_dist_offset_err_t

#include <nrf_dm.h>

Public Members

float ifft: Zero distance error offset - applied for distance evaluated with iFFT method

float phase_slope: Zero distance error offset - applied for distance evaluated with average slope method

float rssi_openspace: Zero distance error offset - applied for distance evaluated with RSSI method for openspace conditions

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 access_address: Access address used for packet exchanges

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_dist_offset_err_t dist_offset_err: Zero distance error offsets for different distance measurement methods

nrf_dm_antenna_composition_t ant_comp: Antenna composition of initiator and reflector.

API documentation

Distance Measurement interface

Distance Measurement interface 