Sensor Server

Note

A new sensor API is introduced as of nRF Connect SDK v2.6.0. The old API is deprecated, but still available by enabling the Kconfig option CONFIG_BT_MESH_SENSOR_USE_LEGACY_SENSOR_VALUE. The Kconfig option is enabled by default in the deprecation period. See the documentation for nRF Connect SDK versions prior to v2.6.0 for documentation about the old sensor API.

The Sensor Server model holds a list of sensors, and exposes them to the mesh network. There may be multiple Sensor Server models on a single mesh node, and each model may hold up to 47 sensors.

The Sensor Server model adds two model instances in the composition data:

  • Sensor Server

  • Sensor Setup Server

The two model instances share the states of the Sensor Server, but accept different messages. This allows for a fine-grained control of the access rights for the Sensor Server states, as the two model instances can be bound to different application keys.

  • Sensor Server is the user-facing model in the pair. It provides access to read-only states Sensor Descriptors, Sensor Data, and Sensor Series.

  • Sensor Setup Server provides access to Sensor Cadence and Sensor Settings, allowing configurator devices to set up the publish rate and parameters for each sensor.

Configuration

The Sensor Server model requires a list of bt_mesh_sensor pointers at compile time. The list of sensors cannot be changed at runtime, and only one of each type of sensors can be held by a Sensor Server. To expose multiple sensors of the same type, multiple Sensor Servers must be instantiated on different elements.

The initialization of the Sensor Server can look like this:

extern struct bt_mesh_sensor temperature_sensor;
extern struct bt_mesh_sensor motion_sensor;
extern struct bt_mesh_sensor light_sensor;

static struct bt_mesh_sensor* const sensors[] = {
    &temperature_sensor,
    &motion_sensor,
    &light_sensor,
};
static struct bt_mesh_sensor_srv sensor_srv = BT_MESH_SENSOR_SRV_INIT(sensors, ARRAY_SIZE(sensors));

Each sensor can be implemented in its own separate module by exposing the sensor instance as an external variable and pointing to it in the server’s sensor list.

Note

The list of pointers can be const, while the sensor instances themselves cannot.

All sensors exposed by the Sensor Server must be present in the Server’s list. Passing unlisted sensor instances to the Server API results in undefined behavior.

States

The Sensor Server does not hold any states on its own. Instead, it exposes the states of all its sensors.

Extended models

None.

Persistent storage

The Sensor Server stores the cadence state of each sensor instance persistently, including:

  • Minimum interval

  • Delta thresholds

  • Fast period divisor

  • Fast cadence range

Any other data is managed by the application and must be stored separately. This applies for example to sensor settings or sample data.

If CONFIG_BT_SETTINGS is enabled, the Sensor Server stores all its states persistently using a configurable storage delay to stagger storing. See CONFIG_BT_MESH_STORE_TIMEOUT.

API documentation

Header file: include/bluetooth/mesh/sensor_srv.h
Source file: subsys/bluetooth/mesh/sensor_srv.c
group bt_mesh_sensor_srv

API for the Sensor Server.

Defines

BT_MESH_SENSOR_SRV_INIT(_sensors, _count)

Initialization parameters for Sensor Server model.

Note

A sensor server can only represent one sensor instance of each sensor type. Duplicate sensors will be ignored.

Parameters:
BT_MESH_MODEL_SENSOR_SRV(_srv)

Sensor Server model composition data entry.

Parameters:

Functions

int bt_mesh_sensor_srv_pub(struct bt_mesh_sensor_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_sensor *sensor, const struct bt_mesh_sensor_value *value)

Publish a sensor value.

Immediately publishes the given sensor value, without checking thresholds or intervals.

See also

bt_mesh_sensor_srv_pub

Parameters:

  • srv – [in] Sensor server instance.

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

  • sensor – [in] Sensor to publish with.

  • value – [in] Sensor value to publish, interpreted as an array of sensor channel values matching the sensor channels specified by the sensor type. The length of the array must match the sensor channel count.

Returns:

0 on success, or (negative) error code otherwise.

int bt_mesh_sensor_srv_sample(struct bt_mesh_sensor_srv *srv, struct bt_mesh_sensor *sensor)

Make the server to take a sample of the sensor, and publish if the value changed sufficiently.

Works the same way as bt_mesh_sensor_srv_pub(), except that the server makes a decision on whether to publish the value based on the delta from the previous publication and the sensor’s threshold parameters. Only single channel sensor values will be considered.

Parameters:

  • srv – [in] Sensor server instance.

  • sensor – [in] Sensor instance to sample.

Return values:

  • 0 – The sensor value was published.

  • -EBUSY – Failed sampling the sensor value.

  • -EALREADY – The sensor value has not changed sufficiently to require a publication.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_sensor_srv
#include <sensor_srv.h>

Sensor server instance.

Public Members

struct bt_mesh_sensor *const *sensor_array

Sensors owned by this server.

sys_slist_t sensors

Ordered linked list of sensors.

uint16_t seq

Publish sequence counter

uint8_t sensor_count

Number of sensors.

struct bt_mesh_model_pub pub

Publish parameters.

struct bt_mesh_model_pub setup_pub

Publish parameters for the setup server.

const struct bt_mesh_model *model

Composition data model pointer.