Distance Measurement Client

The Distance Measurement Client vendor model remotely controls the state of a Distance Measurement Server model.

At creation, each Distance Measurement client instance must be initialized with a memory object that can hold one or more measurement results.

Note

The current implementation is classified with experimental software maturity.

Extended models

None.

Persistent storage

None.

Shell commands

The Bluetooth® mesh shell subsystem provides a set of commands to interact with the Distance Measurement Client model instantiated on a device.

To make these commands available, enable the following Kconfig options:

mesh models dm instance get-all

Print all instances of the Distance Measurement Client model on the device.

mesh models dm instance set <ElemIdx>

Select the Distance Measurement Client model instantiated on the specified element ID. This instance will be used in message sending. If no model instance is selected, the first model instance found on the device will be used by default.

  • ElemIdx - Element index where the model instance is found.

mesh models dm cfg [<TTL> <Timeout(100ms steps)> <Delay(µs)>]

If no parameters are provided, get the current configuration state parameters of the server and wait for a response. If parameters are provided, set the configuration state parameters of the server and wait for a response.

  • TTL - Default time to live for sync messages on the target server.

  • Timeout - Default timeout for distance measurement procedure on the target server in 100 ms per step.

  • Delay - Default reflector start delay for the server in microseconds.

mesh models dm start <Mode> <Addr> [<ReuseTransaction> [<TTL> <Timeout(100ms steps)> <Delay(µs)>]]

Start a distance measurement procedure.

  • Mode - Mode used for ranging.

  • Addr - Unicast address of the node to measure distance with.

  • ReuseTransaction - Flag indicating if the previous transaction should be used.

  • TTL - Time to live for the sync message.

  • Timeout - Timeout for distance measurement procedure in 100 ms per step.

  • Delay - Reflector start delay in microseconds.

mesh models dm result-get <EntryCnt>

Get the last distance measurement results from the server. The returned results will start with the most recent measurement.

  • EntryCnt - Number of entries the user wish to receive.

API documentation

Header file: include/bluetooth/mesh/vnd/dm_cli.h
Source file: subsys/bluetooth/mesh/vnd/dm_cli.c
group bt_mesh_dm_cli

API for the Distance Measurement Client model.

Defines

BT_MESH_MODEL_DM_CLI_INIT(_mem, _cnt, _handlers)

Initialization parameters for a Distance Measurement Client model instance.

Parameters:
BT_MESH_MODEL_DM_CLI(_cli)

Distance measurement Client model entry.

Parameters:

Functions

int bt_mesh_dm_cli_config(struct bt_mesh_dm_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_dm_cfg *set, struct bt_mesh_dm_cli_cfg_status *rsp)

Set or get the config state in the Distance Measurement server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_dm_cli_handlers::cfg_status_handler callback.

Parameters:

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • set – [in] New configuration parameters, or NULL to get the current parameters.

  • rsp – [out] Status response buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

  • -EBADMSG – The supplied configuration parameters are invalid.

int bt_mesh_dm_cli_measurement_start(struct bt_mesh_dm_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_dm_cli_start *start, struct bt_mesh_dm_cli_results *rsp)

Start a distance measurement on a Distance Measurement server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_dm_cli_handlers::result_handler callback.

Parameters:

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • start – [in] Distance measurement Start parameters.

  • rsp – [out] Status response buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

  • -EBADMSG – The supplied configuration parameters are invalid or the address is not a unicast address.

int bt_mesh_dm_cli_results_get(struct bt_mesh_dm_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t entry_cnt, struct bt_mesh_dm_cli_results *rsp)

Get measurement results from a Distance Measurement server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_dm_cli_handlers::result_handler callback.

Parameters:

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • entry_cnt – [in] Number of entries the user wish to receive.

  • rsp – [out] Status response buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

  • -EBADMSG – Invalid entry count provided.

struct bt_mesh_dm_cli_results
#include <dm_cli.h>

Parameters for the Distance Measurement Result Status message.

Public Members

uint8_t status

Message status code.

uint8_t entry_cnt

Number of entries in the result.

struct bt_mesh_dm_res_entry *res

Result memory object.

struct bt_mesh_dm_cli_cfg_status
#include <dm_cli.h>

Parameters for the Distance Measurement Config Status message.

Public Members

uint8_t status

Message status code.

bool is_in_progress

Measurement in progress flag.

uint8_t result_entry_cnt

Maximum number of result entries available.

struct bt_mesh_dm_cfg def

Default parameter values.

struct bt_mesh_dm_cli_start
#include <dm_cli.h>

Parameters for the Distance Measurement Start message.

Public Members

bool reuse_transaction

Use previous transaction id.

enum dm_ranging_mode mode

Mode used for ranging.

uint16_t addr

Unicast address of the node to measure distance with.

struct bt_mesh_dm_cfg *cfg

Desired configuration parameter values.

struct bt_mesh_dm_cli_handlers
#include <dm_cli.h>

Handler functions for the Distance Measurement Client.

Public Members

void (*const cfg_status_handler)(struct bt_mesh_dm_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_dm_cli_cfg_status *status)

Config status message handler.

Note

This handler is optional.

Param cli:

[in] Client that received the status message.

Param ctx:

[in] Context of the message.

Param status:

[in] Config status contained in the message.

void (*const result_handler)(struct bt_mesh_dm_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_dm_cli_results *results)

Result status message handler.

Note

This handler is optional.

Param cli:

[in] Client that received the status message.

Param ctx:

[in] Context of the message.

Param results:

[in] Results contained in the message.

struct bt_mesh_dm_cli
#include <dm_cli.h>

Distance Measurement Client instance.

Public Members

const struct bt_mesh_dm_cli_handlers *const handlers

Application handler functions.

uint8_t tid

Transaction ID.

struct bt_mesh_model *model

Access model pointer.

struct bt_mesh_msg_ack_ctx ack_ctx

Response context for tracking acknowledged messages.

struct bt_mesh_model_pub pub

Publish parameters.

struct net_buf_simple pub_buf

Publication buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_DM_START_OP, BT_MESH_DM_START_MSG_LEN_MAX)]

Publication data

struct bt_mesh_dm_res_entry *res_arr

Pointer to Distance measurement Result memory object

uint8_t entry_cnt

Total number of entry spaces in result memory object