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_NRF_DM
Kconfig option.Include
dm.h
in yourmain.c
file.Call
dm_init()
to initialize the module.Call
dm_request_add()
to perform the measurement.
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, use the options CONFIG_DM_RANGING_PIN
and CONFIG_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
include/dm.h
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.
-
enumerator DM_ROLE_NONE
-
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.
-
enumerator DM_RANGING_MODE_RTT
-
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.
-
enumerator DM_QUALITY_OK
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.
-
bool status
-
struct dm_cb
- #include <dm.h>
Event callback structure.
-
struct dm_init_param
- #include <dm.h>
DM initialization parameters.
-
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.
-
enum dm_dev_role role
-
enum dm_dev_role