Distance Measurement Server

The Distance Measurement Server vendor model provides capabilities to measure distance between Bluetooth® mesh devices within radio proximity. The measurements are conducted through the Distance Measurement library.

At creation, each Distance Measurement Server instance must be initialized with a memory object that can hold one or more measurement results. The maximum allowed number of entries in this memory object is restricted to 127 entries. The Distance Measurement Server populates this memory object whenever a new measurement is conducted. The results can be queried by a Distance Measurement Client.

Note

The current implementation is classified with experimental software maturity.

Sequence diagram for DM procedure

Distance measurement procedure

A Distance measurement procedure is started by issuing a bt_mesh_dm_cli_measurement_start message from a Distance Measurement Client (DM CLI). Within this message, the following needs to be defined by the caller:

  • The target address to a server with which the receiving server will perform the measurement.

  • The desired measurement mode.

  • Parameters to use in the measurement:

    • Time-to-live (TTL) value.

    • Timeout for the measurement procedure.

    • Reflector start delay.

When the Distance Measurement Server 1 (DM SRV 1) receives the start message, it will start a timeout timer with either the default timeout or the timeout defined in the start message. It will also add a distance measurement request in the reflector role using the mode and the reflector start delay defined in the start message. If the reflector start delay is not defined and present in the start message, a default delay is used instead.

DM SRV 1 will then issue a synchronization message to the target address enclosed in the received start message. This target address points to another Distance Measurement Server, DM SRV 2. The synchronization message uses by default the same mode and the same timeout value as the DM SRV 1 received in the start message.

When the DM SRV 2 receives the synchronization message, it starts its own timeout timer and adds a distance measurement request in the initiator role using the mode defined in the start message.

If the ranging procedure is successful, the result is stored on both DM SRV 1 and DM SRV 2. In addition, the DM SRV 1 sends the measured result as a response back to the Distance Measurement Client that initiated the procedure.

If the ranging procedure fails, the result is still stored on both servers. The DM SRV 1 sends the result entry as a response to the client, indicating that something went wrong during the procedure.

Note

Due to size restrictions in the result message format, measurements exceeding 65535 centimeters (UINT16_MAX) will be floored to 65535 centimeters. Clients receiving results with values set to 65535 should interpret the result as 65535 centimeters or higher.

States

None

Extended models

None

Persistent storage

The Distance Measurement Server has following runtime configuration options:

  • Default time to live for sync messages.

  • Default timeout for distance measurement procedure.

  • Default reflector start delay.

If the CONFIG_BT_SETTINGS option is enabled, the Distance Measurement Server stores its configuration states persistently using a configurable storage delay. See option CONFIG_BT_MESH_MODEL_SRV_STORE_TIMEOUT.

API documentation

Header file: include/bluetooth/mesh/vnd/dm_srv.h
Source file: subsys/bluetooth/mesh/vnd/dm_srv.c
group bt_mesh_dm_srv

API for the Distance Measurement Server model.

Defines

BT_MESH_MODEL_DM_SRV_INIT(_mem, _cnt)

Initialization parameters for a Distance Measurement Server model instance.

Parameters:
BT_MESH_MODEL_DM_SRV(_srv)

Distance Measurement Server model entry.

Parameters:
struct bt_mesh_dm_srv
#include <dm_srv.h>

Distance Measurement Server instance.

Public Members

struct bt_mesh_tid_ctx prev_transaction

Transaction ID tracker.

struct bt_mesh_model *model

Access model pointer.

bool is_busy

Flag indicating measurement in progress

struct bt_mesh_dm_cfg cfg

Default configuration

struct k_sem dm_ready_sem

Measurement ready semaphore

uint16_t target_addr

Current measurement target address

struct bt_mesh_msg_ctx rsp_ctx

Current measurement respond ctx

enum dm_dev_role current_role

Current role in measurement

struct k_work_delayable timeout

Timeout work context

struct bt_mesh_dm_res_entry *res

Pointer to result memory object

uint8_t entry_cnt

Total number of entry spaces in memory object

uint8_t last_entry_idx

Last working entry index

uint8_t available_entries

Available valid entries