Sensor Client

The Sensor Client model reads and configures the sensors exposed by Sensor Server models.

Unlike the Sensor Server model, the Sensor Client only creates a single model instance in the mesh composition data. The Sensor Client can send messages to both the Sensor Server and the Sensor Setup Server, as long as it has the right application keys.

Configuration

The Sensor Client will receive data from the Sensor Servers asynchronously. In most cases, the incoming data needs to be interpreted differently based on the type of sensor that produced it.

When parsing incoming messages, the Sensor Client is required to do a lookup of the sensor type of the data so it can decode it correctly. For this purpose, the Sensor types module includes the list of available sensor types.

By default, all sensor types are available when the Sensor Client model is compiled in, but this behavior can be overridden to reduce flash consumption by explicitly disabling CONFIG_BT_MESH_SENSOR_ALL_TYPES. In this case, only the referenced sensor types will be available.

Note

Whenever the Sensor Client receives a sensor type that it is unable to interpret, it calls its bt_mesh_sensor_cli_handlers.unknown_type callback. The Sensor Client API is designed to force the application to reference any sensor types it wants to communicate with, so this issue will commonly not occur.

The Sensor Client API supports both blocking functions and asynchronous callbacks for accessing the Sensor Server data.

API documentation

Header file: include/bluetooth/mesh/sensor_cli.h
Source file: subsys/bluetooth/mesh/sensor_cli.c
group bt_mesh_sensor_cli

API for the Sensor Client.

Defines

BT_MESH_SENSOR_CLI_INIT(_handlers)

Initialization parameters for Sensor Client model.

See

bt_mesh_sensor_cli_handlers

Parameters

  • _handlers – [in] Optional message handler structure.

BT_MESH_MODEL_SENSOR_CLI(_cli)

Sensor Client model composition data entry.

Parameters

Functions

int bt_mesh_sensor_cli_desc_all_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_sensor_info *sensors, uint32_t *count)

Retrieve all sensor descriptors in a sensor server.

This call is blocking if the sensors buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_sensor_cli_handlers::sensor callback as a list of sensor descriptors.

If a sensors array is provided and the client received a response, the array will be filled with as many of the response sensors as it can fit, even if the buffer isn’t big enough. If the call fails in a way that results in no response, count is set to 0.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensors – [out] Array of sensors to fill with the response, or NULL to keep from blocking.

  • count – [inout] The number of elements in the sensors array. Will be changed to reflect the resulting number of sensors.

Returns 0

Successfully received the full list of sensors. The sensors array and count has been changed to reflect the response contents.

Returns -EALREADY

A blocking request is already in progress.

Returns -E2BIG

The list of sensors in the response was too big to fit in the sensors array. The sensors array has been filled up to the original count, and count has been changed to the number of sensors in the response.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_desc_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, struct bt_mesh_sensor_descriptor *rsp)

Get the descriptor for the given sensor.

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_sensor_cli_handlers::sensor callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

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

Returns 0

Successfully received the descriptor. The rsp buffer has been filled.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_cadence_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, struct bt_mesh_sensor_cadence_status *rsp)

Get the cadence state.

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_sensor_cli_handlers::cadence callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor to get the cadence of.

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

Returns 0

Successfully received the cadence. The rsp buffer has been filled.

Returns -ENOTSUP

The sensor doesn’t support cadence settings.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_cadence_set(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_cadence_status *cadence, struct bt_mesh_sensor_cadence_status *rsp)

Set the cadence state for the given sensor.

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_sensor_cli_handlers::cadence callback.

Note

Only single-channel sensors support cadence.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • cadence – [in] New sensor cadence for the sensor.

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

Returns 0

Successfully received the cadence. The rsp buffer has been filled.

Returns -ENOTSUP

The sensor doesn’t support cadence settings.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_cadence_set_unack(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_cadence_status *cadence)

Set the cadence state for the given sensor without requesting a response.

Note

Only single-channel sensors support cadence.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • cadence – [in] New sensor cadence for the sensor.

Returns 0

Successfully received the cadence.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_settings_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, uint16_t *ids, uint32_t *count)

Get the list of settings for the given sensor.

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

If an ids array is provided and the client received a response, the array will be filled with as many of the response ids as it can fit, even if the buffer isn’t big enough. If the call fails in a way that results in no response, count is set to 0.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • ids – [out] Array of sensor setting IDs to fill with the response, or NULL to keep from blocking.

  • count – [inout] The number of elements in the ids array. Will be changed to reflect the resulting number of IDs.

Returns 0

Successfully received the full list of sensor setting IDs. The ids array and count has been changed to reflect the response contents.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -E2BIG

The list of IDs in the response was too big to fit in the ids array. The ids array has been filled up to the original count, and count has been changed to the number of IDs in the response.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_setting_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_type *setting, struct bt_mesh_sensor_setting_status *rsp)

Get a setting value for a sensor.

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_sensor_cli_handlers::setting_status callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • setting – [in] Setting to read.

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

Returns 0

Successfully received the setting value. The rsp buffer has been filled.

Returns -ENOENT

The sensor doesn’t have the given setting.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_setting_set(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_type *setting, const struct sensor_value *value, struct bt_mesh_sensor_setting_status *rsp)

Set a setting value for a sensor.

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_sensor_cli_handlers::setting_status callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • setting – [in] Setting to change.

  • value – [in] New setting value. Must contain values for all channels described by setting.

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

Returns 0

Successfully changed the setting. The rsp buffer has been filled.

Returns -ENOENT

The sensor doesn’t have the given setting.

Returns -EACCES

The setting can’t be written to.

Returns -EALREADY

A blocking request is already in progress.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_setting_set_unack(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_type *setting, const struct sensor_value *value)

Set a setting value for a sensor without requesting a response.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • setting – [in] Setting to change.

  • value – [in] New setting value. Must contain values for all channels described by setting.

Returns 0

Successfully changed the setting.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_all_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_sensor_data *sensors, uint32_t *count)

Read sensor data from all sensors on a 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_sensor_cli_handlers::data callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensors – [in] List of sensor data values.

  • count – [inout] The number of elements in the sensors array. Will be changed to reflect the resulting number of elements in a list.

Returns 0

Successfully received the sensor data.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, struct sensor_value *rsp)

Read sensor data from a sensor instance.

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_sensor_cli_handlers::data callback.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • rsp – [out] Response value buffer, or NULL to keep from blocking. Must be able to fit all channels described by the sensor type.

Returns 0

Successfully received the sensor data.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_series_entry_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_column *column, struct bt_mesh_sensor_series_entry *rsp)

Read a single sensor series data entry.

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_sensor_cli_handlers::series_entry callback as a list of sensor descriptors.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • column – [in] Column to read. The start value must match the start value of a series column on the sensor. The end value is ignored.

  • rsp – [out] Response value buffer, or NULL to keep from blocking. Must be able to fit all channels described by the sensor type.

Returns 0

Successfully received the sensor data.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -ENOENT

The sensor doesn’t have the given column.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

int bt_mesh_sensor_cli_series_entries_get(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_column *range, struct bt_mesh_sensor_series_entry *rsp, uint32_t *count)

Get multiple sensor series data entries.

Retrieves all data series columns starting within the given range (inclusive), or all data series entries if range is NULL. For instance, requesting range [1, 5] from a sensor with columns [0, 2], [1, 4], [4, 5] and [5, 8] will return all columns except [0, 2].

If a rsp array is provided and the client received a response, the array will be filled with as many of the response columns as it can fit, even if the buffer isn’t big enough. If the call fails in a way that results in no response, count is set to 0.

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_sensor_cli_handlers::series_entry callback as a list of sensor descriptors.

Parameters

  • cli – [in] Sensor client instance.

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

  • sensor – [in] Sensor instance present on the targeted sensor server.

  • range – [in] Range of columns to get, or NULL to get all columns.

  • rsp – [out] Array of entries to copy the response into, or NULL to keep from blocking.

  • count – [inout] The number of entries in rsp. Is changed to reflect the number of entries in the response.

Returns 0

Successfully received the full list of sensor series columns. The rsp array and count has been changed to reflect the response contents.

Returns -ENODEV

The sensor server doesn’t have the given sensor.

Returns -E2BIG

The list of sensor columns in the response was too big to fit in the rsp array. The rsp array has been filled up to the original count, and count has been changed to the number of columns in the response.

Returns -ENOTSUP

The sensor doesn’t support series data.

Returns -EADDRNOTAVAIL

A message context was not provided and publishing is not configured.

Returns -EAGAIN

The device has not been provisioned.

struct bt_mesh_sensor_cli
#include <sensor_cli.h>

Sensor client instance.

Should be initialized with BT_MESH_SENSOR_CLI_INIT.

Public Members

struct bt_mesh_model *model

Composition data model instance.

struct bt_mesh_model_pub pub

Model publication parameters.

struct bt_mesh_msg_ack_ctx ack_ctx

Response context for acknowledged messages.

const struct bt_mesh_sensor_cli_handlers *cb

Client callback functions.

struct bt_mesh_sensor_cadence_status
#include <sensor_cli.h>

Sensor cadence status parameters

Public Members

uint8_t fast_period_div

Logarithmic fast publish period divisor value.

The sensor’s fast period interval is publish_period / (1 << fast_period_div).

uint8_t min_int

Logarithmic minimum publish period.

The sensor’s fast period interval is never lower than (1 << min_int).

struct bt_mesh_sensor_threshold threshold

Sensor threshold values.

struct bt_mesh_sensor_setting_status
#include <sensor_cli.h>

Sensor settings parameters.

Public Members

const struct bt_mesh_sensor_type *type

Setting type

struct sensor_value value[CONFIG_BT_MESH_SENSOR_CHANNELS_MAX]

Setting value.

bool writable

Whether the setting can be written to.

struct bt_mesh_sensor_series_entry
#include <sensor_cli.h>

Sensor series entry

Public Members

struct bt_mesh_sensor_column column

Sensor column descriptor.

struct sensor_value value[CONFIG_BT_MESH_SENSOR_CHANNELS_MAX]

Sensor column value.

struct bt_mesh_sensor_info
#include <sensor_cli.h>

Sensor info structure.

Public Members

uint16_t id

Sensor Device Property ID

struct bt_mesh_sensor_descriptor descriptor

Sensor descriptor.

struct bt_mesh_sensor_data
#include <sensor_cli.h>

Public Members

const struct bt_mesh_sensor_type *type

Sensor type.

struct sensor_value value[CONFIG_BT_MESH_SENSOR_CHANNELS_MAX]

Sensor value.

struct bt_mesh_sensor_cli_handlers
#include <sensor_cli.h>

Sensor client handler functions.

Public Members

void (*data)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct sensor_value *value)

Sensor data callback.

Called when the client receives sensor sample data, either as a result of calling bt_mesh_sensor_cli_get, or as an unsolicited message.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor instance.

  • value – [in] The interpreted sensor data value as an array of channels. The length of the array matches the sensor channel count.

void (*sensor)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_info *sensor)

Sensor description callback.

Called when the client receives sensor descriptors, either as a result of calling bt_mesh_sensor_cli_all_get or bt_mesh_sensor_cli_desc_get, or as an unsolicited message.

The sensor description does not reference the sensor type directly, to allow discovery of sensor types unknown to the client. To get the sensor type of a known sensor, call bt_mesh_sensor_type_get.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor information for a single sensor.

void (*cadence)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_cadence_status *cadence)

Sensor cadence callback.

Called when the client receives the cadence of a sensor, either as a result of calling one of bt_mesh_sensor_cli_cadence_get, bt_mesh_sensor_cli_cadence_set or bt_mesh_sensor_cli_cadence_set_unack, or as an unsolicited message.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor instance.

  • cadence – [in] Sensor cadence information.

void (*settings)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const uint16_t *ids, uint32_t count)

Sensor settings list callback.

Called when the client receives the full list of sensor settings, as a result of calling bt_mesh_sensor_cli_settings_get or as an unsolicited message.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor instance.

  • ids – [in] Available sensor setting IDs.

  • count – [in] The number of sensor setting IDs.

void (*setting_status)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, const struct bt_mesh_sensor_setting_status *setting)

Sensor setting status callback.

Called when the client receives a sensor setting status, either as result of calling bt_mesh_sensor_cli_setting_get, bt_mesh_sensor_cli_setting_set, bt_mesh_sensor_cli_setting_set_unack, or as an unsolicited message.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor instance.

  • setting – [in] Sensor setting information.

void (*series_entry)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_sensor_type *sensor, uint8_t index, uint8_t count, const struct bt_mesh_sensor_series_entry *entry)

Series entry callback.

Called when the client receives series entries, either as result of calling one of bt_mesh_sensor_cli_series_entry_get or bt_mesh_sensor_cli_series_entries_get, or as a result of an unsolicited message.

If the received series entry message contains several entries, this callback is called once per entry, with the index and count parameters indicating the progress.

Note

The index and count parameters does not necessarily match the total number of series entries of the sensor, as the callback may be the result of a filtered query.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • sensor – [in] Sensor instance.

  • index – [in] Index of this entry in the list of entries received.

  • count – [in] Total number of entries received.

  • entry – [in] Single sensor series entry.

void (*unknown_type)(struct bt_mesh_sensor_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t id, uint32_t opcode)

Unknown type callback.

Called when the client receives a message with a sensor type it doesn’t have type information for.

Parameters

  • cli – [in] Sensor client receiving the message.

  • ctx – [in] Message context.

  • id – [in] Sensor type ID.

  • opcode – [in] The opcode of the message containing the unknown sensor type.