Distance Measurement

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

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. This 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.

Using Distance Measurement

To use the Distance Measurement module, enable it using the CONFIG_NRF_DM Kconfig option and initialize it in your application. After synchronizing, the nodes that should perform the measurement with each other issue the measurement request. The callback function data_ready() is called when the measurement data is available.

Complete the following steps:

1. Enable the CONFIG_NRF_DM Kconfig option.

2. Include dm.h in your main.c file.

3. Call dm_init() to initialize the module.

4. Call dm_request_add() to perform the measurement.

Configuration

To use the Distance Measurement module, enable the CONFIG_NRF_DM Kconfig option.

Synchronization

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

• CONFIG_DM_INITIATOR_DELAY_US - Extra delay of start of initiator role in distance measurement. Reducing this decreases power consumption but leads to less successful rangings.

• CONFIG_DM_REFLECTOR_DELAY_US - Extra delay of start of reflector role in distance measurement.

• CONFIG_DM_MIN_TIME_BETWEEN_TIMESLOTS_US - Minimum time between two timeslots. This should account for processing of the ranging data after the timeslot.

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 will be 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, use the options CONFIG_DM_RANGING_PIN and CONFIG_DM_ADD_REQUEST_PIN.

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.

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

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.

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

enumerator DM_ROLE_INITIATOR

enumerator DM_ROLE_REFLECTOR

enum dm_ranging_mode

Ranging mode definition.

Values:

enumerator DM_RANGING_MODE_RTT

enumerator DM_RANGING_MODE_MCPD

enum dm_quality

Measurement quality definition.

Values:

enumerator DM_QUALITY_OK

enumerator DM_QUALITY_POOR

enumerator DM_QUALITY_DO_NOT_USE

enumerator DM_QUALITY_CRC_FAIL

enumerator DM_QUALITY_NONE

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 – 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 – 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>

Measurement structure.

struct dm_cb

#include <dm.h>

Event callback structure.

Public Members

void (*data_ready)(struct dm_result *result)

Data ready.

Param result

Measurement data.

struct dm_init_param

#include <dm.h>

DM initialization parameters.

struct dm_request

#include <dm.h>

DM request structure.