Generic Property Servers

A Generic Property Server holds a list of Device Properties. The following property servers are supported:

  • Generic Manufacturer Property Server - Provides access to Manufacturer Properties, which are read-only properties set by the device manufacturer.

  • Generic Admin Property Server - Provides access to Admin Properties, which can be read and written to.

  • Generic User Property Server - Provides access to both Admin and Manufacturer Properties on its element, but only if the property owner allows it.

  • Generic Client Property Server - Provides a list of all properties supported by the Generic Property Client on the same element. The Client Property Server does not actually own any properties, and does not need the user to provide access to any property values.

When developing, take the following into account:

  • Only the administrator of the mesh network should have access to the admin or manufacturer servers.

  • All other mesh nodes should operate on the user server.

  • The manufacturer and admin servers:

    • May change the user property access rights for each individual property they own at runtime.

    • Must provide a list of all properties they own in the initialization of the model.

  • The User Property Server does not own any properties, but relies on Admin Property Server and Manufacturer Property Server on the same element to provide access to their properties. An element with a User Property Server, and no Admin or Manufacturer Property Server is useless.

  • The model keeps the user access field of each Admin and Manufacturer Property in persistent storage. The property values themselves must be stored by the application.

  • Your application should provide access to the property values through the callbacks of server getter (bt_mesh_prop_srv.get) and setter (bt_mesh_prop_srv.set).

  • The set of Property IDs and their order cannot be changed.

States

The Generic Power OnOff Server model contains the following state:

Device Properties: bt_mesh_prop

A single server may own several Device Properties, which are accessed by the Property ID. Each property holds a value and a user access parameter, which controls the property’s availability to a Generic User Property Server on the same element.

The Device Properties have slightly different access restrictions, depending on the type of server that owns them:

  • Manufacturer Property - The value can only be read.

  • Admin Property - The value can be read and written.

  • Client Property - Has no associated value, and is only a listing of the Property IDs supported by the accompanying Generic Property Client.

Extended models

Generic Admin Property Server and Generic Manufacturer Property Server should both extend the Generic User Property Server. This is not handled automatically by the model implementation. For this reason, to ensure compliance with the Bluetooth® mesh model specification, a Generic User Property Server must be instantiated in the same element in the device composition data as the Generic Admin or Generic Manufacturer Property Server.

Persistent storage

The Generic Manufacturer Property Server and Generic Admin Property Server models will store changes to the user access rights of their properties. Any permanent changes to the property values themselves should be stored manually by the application.

If CONFIG_BT_SETTINGS is enabled, the Generic Admin Property Server stores all its states persistently using a configurable storage delay to stagger storing. See CONFIG_BT_MESH_MODEL_SRV_STORE_TIMEOUT.

API documentation

Header file: include/bluetooth/mesh/gen_prop_srv.h
Source file: subsys/bluetooth/mesh/gen_prop_srv.c
group bt_mesh_prop_srv

API for the Generic Property server models.

Defines

BT_MESH_PROP_SRV_INIT(_properties, _property_count, _get, _set)

Initialization parameters for a Generic Property server models instance.

See also

bt_mesh_prop_srv::get.

See also

bt_mesh_prop_srv::set.

Parameters

  • _properties – [in] Array of properties supported by the server.

  • _property_count – [in] Number of properties supported by the server. Cannot be larger than CONFIG_BT_MESH_PROP_MAXCOUNT .

  • _get – [in] Getter handler for property values.

  • _set – [in] Setter handler for property values.

BT_MESH_PROP_SRV_USER_INIT()

Initialization parameters for a Generic Property server models acting as a Generic User Property Server.

BT_MESH_PROP_SRV_ADMIN_INIT(_properties, _get, _set)

Initialization parameters for a Generic Property server models acting as a Generic Admin Property Server.

Parameters

  • _properties – [in] Array of properties exposed by the server.

  • _get – [in] Getter function for property values.

  • _set – [in] Setter function for property values.

BT_MESH_PROP_SRV_MFR_INIT(_properties, _get)

Initialization parameters for a Generic Property server models acting as a Generic Manufacturer Property Server.

Parameters

  • _properties – [in] Array of properties exposed by the server.

  • _get – [in] Getter function for property values.

BT_MESH_PROP_SRV_CLIENT_INIT(_properties)

Initialization parameters for a Generic Property server models acting as a Generic Client Property Server.

Parameters

  • _properties – [in] Array of properties exposed by the server. May be constant.

BT_MESH_MODEL_PROP_SRV_USER(_srv)

Generic User Property Server model composition data entry.

BT_MESH_MODEL_PROP_SRV_ADMIN(_srv)

Generic Admin Property Server model composition data entry.

Parameters
BT_MESH_MODEL_PROP_SRV_MFR(_srv)

Generic Manufacturer Property Server model data entry.

Parameters
BT_MESH_MODEL_PROP_SRV_CLIENT(_srv)

Generic Client Property Server model data entry.

Parameters

Enums

enum bt_mesh_prop_srv_state

Enumeration of all property server states.

Values:

enumerator BT_MESH_PROP_SRV_STATE_NONE

No state.

enumerator BT_MESH_PROP_SRV_STATE_LIST

Property List.

enumerator BT_MESH_PROP_SRV_STATE_PROP

Property value.

Functions

int bt_mesh_prop_srv_pub_list(struct bt_mesh_prop_srv *srv, struct bt_mesh_msg_ctx *ctx)

Publish a list of all properties on the server.

Parameters

  • srv – [in] Server that owns the property.

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

Return values

  • 0 – Successfully publish a Generic Level Status message.

  • -EMSGSIZE – The given property size is not supported.

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

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_prop_srv_pub(struct bt_mesh_prop_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop_val *val)

Publish a property value.

Parameters

  • srv – [in] Server that owns the property.

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

  • val – [in] Value of the property.

Return values

  • 0 – Successfully publish a Generic Level Status message.

  • -EINVAL – The server is a Client Property server, which does not support publishing of property values.

  • -EMSGSIZE – The given property size is not supported.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_prop_srv
#include <gen_prop_srv.h>

Generic Property Server instance. Should be initialized with the BT_MESH_PROP_SRV_INIT, BT_MESH_PROP_SRV_ADMIN_INIT, BT_MESH_PROP_SRV_MFR_INIT or BT_MESH_PROP_SRV_CLIENT_INIT macro.

Public Members

struct bt_mesh_model *model

Pointer to the mesh model entry.

struct bt_mesh_model_pub pub

Model publication parameters.

uint16_t pub_id

Property ID currently being published.

enum bt_mesh_prop_srv_state pub_state

Which state is currently being published.

struct bt_mesh_prop *const properties

List of properties supported by the server.

const uint32_t property_count

Number of properties supported by the server.

void (*const set)(struct bt_mesh_prop_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_prop_val *val)

Set a property value.

The handler may reject the value change with two levels of severity:

To indicate data format errors and permanently illegal values, change the val::meta::id field to BT_MESH_PROP_ID_PROHIBITED before returning. This will cancel the response message sending, indicating a protocol violation.

To indicate that the new value is temporarily unable to change, but not in violation of the protocol, replace the contents of buf and size with the current property value and size. Note that buf can only fit a value of size CONFIG_GEN_PROP_MAXSIZE.

Note

This handler is mandatory if the server is acting as an Admin Property Server, and ignored if the server is acting as a Manufacturer Property Server.

Param srv

[in] Property Server instance whose property to set.

Param ctx

[in] Message context for the message that triggered the change, or NULL if the change is not coming from a messge.

Param val

[inout] Property value to set. Any changes to the value will be reflected in the response message.

void (*const get)(struct bt_mesh_prop_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_prop_val *val)

Get a property value.

Note that buf can only fit a value of size CONFIG_GEN_PROP_MAXSIZE.

Note

This handler is mandatory.

Param srv

[in] Property Server instance whose property to set.

Param ctx

[in] Message context for the message that triggered the change, or NULL if the change is not coming from a messge.

Param val

[inout] Property value to get. Any changes to the value will be reflected in the response message.