Generic Property Client

The Generic Property Client model can access properties from a Property Server remotely. The Property Client can talk directly to all types of Property Servers, but only if it shares an application key with the target server.

Generally, the Property Client should only target User Property Servers, unless it is part of a network administrator node that is responsible for configuring the other mesh nodes.

To ease the configuration, the Property Client can be paired with a Client Property Server that lists which properties this Property Client will request.

Extended models

None.

Shell commands

The Bluetooth Mesh shell subsystem provides a set of commands to interact with the Generic Property Client model instantiated on a device.

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

mesh models prop instance get-all

Print all instances of the Generic Property Client model on the device.

mesh models prop instance set <ElemIdx>

Select the Generic Property 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 prop cli-props-get <ID>

Get the list of Generic Client Properties of the bound server.

  • ID - A starting Client Property ID present within an element.

mesh models prop props-get <Kind>

Get the list of properties of the bound server.

  • Kind - Kind of Property Server to query. Allowed values:

    • 0 - Manufacturer Property Server.

    • 1 - Admin Property Server.

    • 2 - User Property Server.

mesh models prop prop-get <Kind> <ID>

Get the value of a property of a server.

  • Kind - Kind of Property Server to query. Allowed values:

    • 0 - Manufacturer Property Server.

    • 1 - Admin Property Server.

    • 2 - User Property Server.

    • 3 - Client Property Server.

  • ID - ID of the property.

mesh models prop user-prop-set <ID> <HexStrVal>

Set a property value of the User Property Server and wait for response.

  • ID - Property ID.

  • HexStrVal - Property value.

mesh models prop user-prop-set-unack <ID> <HexStrVal>

Set a property value of the User Property Server without requesting a response.

  • ID - Property ID.

  • HexStrVal - Property value.

mesh models prop admin-prop-set <ID> <Access> <HexStrVal>

Set a property value of the Admin Property Server and wait for response.

  • ID - Property ID.

  • Access - User access flags for the property. Allowed values:

    • 0 - Access to the property is prohibited.

    • 1 - Property may be read.

    • 2 - Property may be written.

    • 3 - Property may be read or written.

  • HexStrVal - Property value.

mesh models prop admin-prop-set-unack <ID> <Access> <HexStrVal>

Set a property value of the Admin Property Server without requesting a response.

  • ID - Property ID.

  • Access - User access flags for the property. Allowed values:

    • 0 - Access to the property is prohibited.

    • 1 - Property may be read.

    • 2 - Property may be written.

    • 3 - Property may be read or written.

  • HexStrVal - Property value.

mesh models prop mfr-prop-set <ID> <Access>

Set the user access of a property of the Manufacturer Property Server and wait for response.

  • ID - Property ID.

  • Access - User access flags for the property. Allowed values:

    • 0 - Access to the property is prohibited.

    • 1 - Property may be read.

    • 2 - Property may be written.

    • 3 - Property may be read or written.

mesh models prop mfr-prop-set-unack <ID> <Access>

Set the user access of a property of the Manufacturer Property Server without requesting a response.

  • ID - Property ID.

  • Access - User access flags for the property. Allowed values:

    • 0 - Access to the property is prohibited.

    • 1 - Property may be read.

    • 2 - Property may be written.

    • 3 - Property may be read or written.

API documentation

Header file: include/bluetooth/mesh/gen_prop_cli.h
Source file: subsys/bluetooth/mesh/gen_prop_cli.c
group bt_mesh_prop_cli

API for the Generic Property Client model.

Defines

BT_MESH_PROP_CLI_INIT(_prop_list_handler, _prop_status_handler)

Initialization parameters for the Generic Property Client model.

See also

bt_mesh_prop_cli::prop_list

See also

bt_mesh_prop_cli::prop_status

Parameters:

  • _prop_list_handler – [in] Optional status message handler.

  • _prop_status_handler – [in] Optional status message handler.

BT_MESH_MODEL_PROP_CLI(_cli)

Generic Property Client model composition data entry.

Parameters:

Functions

int bt_mesh_prop_cli_client_props_get(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t id, struct bt_mesh_prop_list *rsp)

Get the list of Generic Client Properties of the bound server.

To get the list of other property states, use :ref:bt_mesh_prop_cli_props_get.

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_prop_cli::prop_list callback.

Parameters:

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

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

  • id – [in] A starting Client Property ID present within an element.

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

Return values:

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

  • -EINVAL – The rsp::ids list was NULL.

  • -ENOBUFS – The client received a response, but the supplied response buffer was too small to hold all the properties. All property IDs that could fit in the response buffers were copied into it, and the rsp::count field was left unchanged.

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

  • -ENOTSUP – A message context was not provided and publishing is not supported.

  • -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.

int bt_mesh_prop_cli_props_get(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_prop_srv_kind kind, struct bt_mesh_prop_list *rsp)

Get the list of properties of the bound 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_prop_cli::prop_list callback.

Parameters:

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

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

  • kind – [in] Kind of Property Server to query. Use with every property kind except for BT_MESH_PROP_SRV_KIND_CLIENT. To get the list of client property states, use :ref:bt_mesh_prop_cli_client_props_get.

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

Return values:

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

  • -EINVAL – The rsp::ids list was NULL.

  • -ENOBUFS – The client received a response, but the supplied response buffer was too small to hold all the properties. All property IDs that could fit in the response buffers were copied into it, and the rsp::count field was left unchanged.

  • -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.

int bt_mesh_prop_cli_prop_get(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_prop_srv_kind kind, uint16_t id, struct bt_mesh_prop_val *rsp)

Get the value of a property in 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_prop_cli::prop_status callback.

Parameters:

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

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

  • kind – [in] Kind of Property Server to query.

  • id – [in] ID of the property to get.

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

Return values:

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

  • -EINVAL – The rsp::ids list was NULL.

  • -ENOBUFS – The client received a response, but the supplied response buffer was too small to hold all the properties. All property IDs that could fit in the response buffers were copied into it, and the rsp::count field was left unchanged.

  • -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.

int bt_mesh_prop_cli_user_prop_set(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop_val *val, struct bt_mesh_prop_val *rsp)

Set a property value in a User Property Server.

The User Property may only be set if the server enabled user write access to it. If this is not the case, the server will only respond with the set user access mode for the given property.

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_prop_cli::prop_status callback.

Note

The val::meta::user_access level will be ignored.

Parameters:

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

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

  • val – [in] New property value to set. Note that the user_access mode will be ignored.

  • rsp – [out] Response status 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.

int bt_mesh_prop_cli_user_prop_set_unack(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop_val *val)

Set a property value in a User Property Server without requesting a response.

The User Property may only be set if the server enabled user write access to it. If this is not the case, the server will only respond with the set user access mode for the given property.

Note

The val::meta::user_access level will be ignored.

Parameters:

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

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

  • val – [in] New property value to set. Note that the user_access mode will be ignored.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_prop_cli_admin_prop_set(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop_val *val, struct bt_mesh_prop_val *rsp)

Set a property value in an Admin Property 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_prop_cli::prop_status callback.

Parameters:

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

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

  • val – [in] New property value to set.

  • rsp – [out] Response status 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.

int bt_mesh_prop_cli_admin_prop_set_unack(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop_val *val)

Set a property value in an Admin Property server without requesting a response.

Parameters:

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

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

  • val – [in] New property value to set.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_prop_cli_mfr_prop_set(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop *prop, struct bt_mesh_prop_val *rsp)

Set the user access of a property in a Manufacturer Property 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_prop_cli::prop_status callback.

Parameters:

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

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

  • prop – [in] New property value to set.

  • rsp – [out] Response status 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.

int bt_mesh_prop_cli_mfr_prop_set_unack(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_prop *prop)

Set the user access of a property in a Manufacturer Property server without requesting a response.

Parameters:

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

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

  • prop – [in] New property value to set.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_prop_list
#include <gen_prop_cli.h>

List of property IDs.

Public Members

uint8_t count

Number of IDs in the list.

uint16_t *ids

Available Property IDs.

struct bt_mesh_prop_cli
#include <gen_prop_cli.h>

Generic Property Client instance. Should be initialized with BT_MESH_PROP_CLI_INIT.

Public Members

const struct bt_mesh_model *model

Model entry.

struct bt_mesh_model_pub pub

Publish parameters.

struct bt_mesh_msg_ack_ctx ack_ctx

Acknowledged message tracking.

void (*const prop_list)(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_prop_srv_kind kind, const struct bt_mesh_prop_list *list)

Property list message handler.

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param kind:

[in] Kind of Property Server that sent the message.

Param list:

[in] List of properties supported by the server.

void (*const prop_status)(struct bt_mesh_prop_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_prop_srv_kind kind, const struct bt_mesh_prop_val *prop)

Property status message handler.

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param kind:

[in] Kind of Property Server that sent the message.

Param prop:

[in] Property value.