Distance Measurement

The Distance Measurement module provides an integration of Nordic Distance Measurement library into nRF Connect SDK.

Note

The current implementation is experimental.

Overview 

The Distance Measurement module is independent of the communication protocol used. The Multiprotocol Service Layer library is used to access the radio module. The distance is measured during the allocated timeslot.

Ranging 

When a new ranging request arrives, the module checks if a timeslot for the ranging can be scheduled. It also checks if the request fits in the schedule of rangings. Rangings are not executed immediately, but are scheduled for future execution, which gives additional flexibility. New ranging requests may arrive at any point in time.

If the request can be scheduled, the module performs the ranging after the time set in the CONFIG_DM_RANGING_OFFSET_US option has passed. The ranging is executed within a timeslot. After ranging, a callback is called to store or process the measurement data.

Configuration 

To use the Distance Measurement module, complete the following steps:

Enable the CONFIG_DM_MODULE Kconfig option.
Set the ncs,dm-timer chosen node to the TIMER peripheral you wish this module to use.
Include dm.h in your main.c file.
Call dm_init() to initialize the module.
Call dm_request_add() to perform the measurement.

For example, to use the TIMER2 peripheral, set ncs,dm-timer as follows in a devicetree overlay:

/ {
        chosen {
                ncs,dm-timer = &timer2;
        };
};

After synchronizing, the nodes that perform the measurement with each other will issue the measurement request. The callback function data_ready() is called when the measurement data is available.

Configuring synchronization 

To adjust the synchronization of the nodes, change the values of the following options:

CONFIG_DM_INITIATOR_DELAY_US - Extra delay of the start of the initiator role for the distance measurement. Reducing this value decreases the power consumption, but leads to less successful rangings.
CONFIG_DM_MIN_TIME_BETWEEN_TIMESLOTS_US - Minimum time between two timeslots. This option should account for processing of the ranging data after the timeslot.

Enabling output pin state change

It is possible to enable an output pin state change when an event related to this module occurs. You can use this functionality to determine the synchronization accuracy. A logic analyzer or oscilloscope are helpful for this purpose.

Enabling the CONFIG_DM_GPIO_DEBUG option changes the state of the pins when a new measurement request is added and the timeslot is assigned. To assign the pin numbers, create the appropriate nodes in the devicetree as follows:

/ {
   dm_gpio {
      compatible = "gpio-leds";
      dm_ranging: dm-ranging {
         gpios = <&gpio0 27 GPIO_ACTIVE_LOW>;
         label = "DM Ranging Pin";
      };
      dm_add_request: dm-add-request {
         gpios = <&gpio0 26 GPIO_ACTIVE_LOW>;
         label = "DM Add request Pin";
      };
   };
};

Configuring timeslot queue

Use the following options to configure the timeslot queue:

CONFIG_DM_TIMESLOT_QUEUE_LENGTH - Maximum number of scheduled timeslots.
CONFIG_DM_TIMESLOT_QUEUE_COUNT_SAME_PEER - Maximum number of timeslots with rangings to the same peer.

For optimal performance and scalability, both peers should come to the same decision to range each other. Otherwise, one of the peers tries to range the other peer that is not listening and therefore wastes power and time during this operation.

If you enable the CONFIG_DM_TIMESLOT_RESCHEDULE option, the device will try to range the same peer again if the previous ranging was successful.

Defining ranging offset

The option CONFIG_DM_RANGING_OFFSET_US defines the time between the synchronization (adding a request) and ranging. Increasing this value allows for more rangings to different nodes, but also increases latency.

API documentation 

Header file: include/dm.h

Source files: subsys/dm/

group dm

API for the Distance Measurement (DM).

Enums

enum dm_dev_role

Role definition.

Values:

enumerator DM_ROLE_NONE: Undefined role.

enumerator DM_ROLE_INITIATOR: Act as an initiator.

enumerator DM_ROLE_REFLECTOR: Act as a reflector.

enum dm_ranging_mode

Ranging mode definition.

Values:

enumerator DM_RANGING_MODE_RTT: Round trip timing.

enumerator DM_RANGING_MODE_MCPD: Multi-carrier phase difference.

enum dm_quality

Measurement quality definition.

Values:

enumerator DM_QUALITY_OK: Good measurement quality.

enumerator DM_QUALITY_POOR: Poor measurement quality.

enumerator DM_QUALITY_DO_NOT_USE: Measurements not usable.

enumerator DM_QUALITY_CRC_FAIL: Incorrect measurement CRC.

enumerator DM_QUALITY_NONE: Measurement quality not specified.

Functions

int dm_init(struct dm_init_param *init_param)

Initialize the DM.

Initialize the DM by specifying a list of supported operations.

Parameters:

init_param – [in] Initialization parameters.

Return values:

0 – if the operation was successful. Otherwise, a (negative) error code is returned.

int dm_request_add(struct dm_request *req)

Add measurement request.

Adding a measurement request. This is related to timeslot allocation.

Parameters:

req – [in] Address of the structure with request parameters.

Return values:

0 – if the operation was successful. Otherwise, a (negative) error code is returned.

struct dm_result

#include <dm.h>

Distance Measurement result structure.

Public Members

bool status: Status of the procedure. True if measurement was done correctly, False otherwise.

enum dm_quality quality: Quality indicator

bt_addr_le_t bt_addr: Bluetooth LE device address. The address is used to distinguish peers.

enum dm_ranging_mode ranging_mode: Mode used for ranging.

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.

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

union dm_result.[anonymous] dist_estimates: Container of distance estimate results for a number of different methods, in meters.

struct dm_cb

#include <dm.h>

Event callback structure.

Public Members

void (*data_ready)(struct dm_result *result)

Data ready.

Callback that is executed when the result of the Distance Measurement is available for reading.

Param result:: [out] Pointer to the variable that is used to store the Distance Measurement result.

struct dm_init_param

#include <dm.h>

DM initialization parameters.

Public Members

struct dm_cb *cb: Event callback structure.

struct dm_request

#include <dm.h>

DM request structure.

Public Members

enum dm_dev_role role: Role of the device.

bt_addr_le_t bt_addr: Bluetooth LE device address.

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 each other.

enum dm_ranging_mode ranging_mode: Ranging mode to use in the procedure.

uint32_t start_delay_us: Start delay.

uint32_t extra_window_time_us: Extra time to extend the ranging window.

Distance Measurement

Overview

Ranging

Configuration

Configuring synchronization

Enabling output pin state change

Configuring timeslot queue

Defining ranging offset

API documentation

Overview 

Ranging 

Configuration 

Configuring synchronization 

API documentation 