The latest development version of this page may be more current than this released 2.2.1 version.

Configuration Client

Configuration Client model is a foundation model defined by the Bluetooth Mesh specification. It provides functionality for configuring most parameters of a mesh node, including encryption keys, model configuration and feature enabling.

The Configuration Client model communicates with a Configuration Server model using the device key of the target node. The Configuration Client model may communicate with servers on other nodes or self-configure through the local Configuration Server model.

All configuration functions in the Configuration Client API have net_idx and addr as their first parameters. These should be set to the network index and primary unicast address that the target node was provisioned with.

The Configuration Client model is optional, but should be instantiated on the first element if it is present in the composition data.

API reference

group bt_mesh_cfg_cli

Bluetooth Mesh.

Defines

BT_MESH_MODEL_CFG_CLI(cli_data)

Generic Configuration Client model composition data entry.

Parameters

BT_MESH_PUB_PERIOD_100MS(steps)

Helper macro to encode model publication period in units of 100ms.

Return

Encoded value that can be assigned to bt_mesh_cfg_mod_pub.period

Parameters

  • steps: Number of 100ms steps.

BT_MESH_PUB_PERIOD_SEC(steps)

Helper macro to encode model publication period in units of 1 second.

Return

Encoded value that can be assigned to bt_mesh_cfg_mod_pub.period

Parameters

  • steps: Number of 1 second steps.

BT_MESH_PUB_PERIOD_10SEC(steps)

Helper macro to encode model publication period in units of 10 seconds.

Return

Encoded value that can be assigned to bt_mesh_cfg_mod_pub.period

Parameters

  • steps: Number of 10 second steps.

BT_MESH_PUB_PERIOD_10MIN(steps)

Helper macro to encode model publication period in units of 10 minutes.

Return

Encoded value that can be assigned to bt_mesh_cfg_mod_pub.period

Parameters

  • steps: Number of 10 minute steps.

Functions

int bt_mesh_cfg_comp_data_get(u16_t net_idx, u16_t addr, u8_t page, u8_t *status, struct net_buf_simple *comp)

Get the target node’s composition data.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • page: Composition data page, or 0xff to request the first available page.

  • status: Status response parameter.

  • comp: Composition data buffer to fill.

int bt_mesh_cfg_beacon_get(u16_t net_idx, u16_t addr, u8_t *status)

Get the target node’s network beacon state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • status: Status response parameter, returns one of BT_MESH_BEACON_DISABLED or BT_MESH_BEACON_ENABLED on success.

int bt_mesh_cfg_beacon_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)

Set the target node’s network beacon state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • val: New network beacon state, should be one of BT_MESH_BEACON_DISABLED or BT_MESH_BEACON_ENABLED.

  • status: Status response parameter. Returns one of BT_MESH_BEACON_DISABLED or BT_MESH_BEACON_ENABLED on success.

int bt_mesh_cfg_ttl_get(u16_t net_idx, u16_t addr, u8_t *ttl)

Get the target node’s Time To Live value.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • ttl: TTL response buffer.

int bt_mesh_cfg_ttl_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *ttl)

Set the target node’s Time To Live value.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • val: New Time To Live value.

  • ttl: TTL response buffer.

int bt_mesh_cfg_friend_get(u16_t net_idx, u16_t addr, u8_t *status)

Get the target node’s Friend feature status.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • status: Status response parameter. Returns one of BT_MESH_FRIEND_DISABLED, BT_MESH_FRIEND_ENABLED or BT_MESH_FRIEND_NOT_SUPPORTED on success.

int bt_mesh_cfg_friend_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)

Set the target node’s Friend feature state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • val: New Friend feature state. Should be one of BT_MESH_FRIEND_DISABLED or BT_MESH_FRIEND_ENABLED.

  • status: Status response parameter. Returns one of BT_MESH_FRIEND_DISABLED, BT_MESH_FRIEND_ENABLED or BT_MESH_FRIEND_NOT_SUPPORTED on success.

int bt_mesh_cfg_gatt_proxy_get(u16_t net_idx, u16_t addr, u8_t *status)

Get the target node’s Proxy feature state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • status: Status response parameter. Returns one of BT_MESH_GATT_PROXY_DISABLED, BT_MESH_GATT_PROXY_ENABLED or BT_MESH_GATT_PROXY_NOT_SUPPORTED on success.

int bt_mesh_cfg_gatt_proxy_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)

Set the target node’s Proxy feature state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • val: New Proxy feature state. Must be one of BT_MESH_GATT_PROXY_DISABLED or BT_MESH_GATT_PROXY_ENABLED.

  • status: Status response parameter. Returns one of BT_MESH_GATT_PROXY_DISABLED, BT_MESH_GATT_PROXY_ENABLED or BT_MESH_GATT_PROXY_NOT_SUPPORTED on success.

int bt_mesh_cfg_relay_get(u16_t net_idx, u16_t addr, u8_t *status, u8_t *transmit)

Get the target node’s Relay feature state.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • status: Status response parameter. Returns one of BT_MESH_RELAY_DISABLED, BT_MESH_RELAY_ENABLED or BT_MESH_RELAY_NOT_SUPPORTED on success.

  • transmit: Transmit response parameter. Returns the encoded relay transmission parameters on success. Decoded with BT_MESH_TRANSMIT_COUNT and BT_MESH_TRANSMIT_INT.

int bt_mesh_cfg_relay_set(u16_t net_idx, u16_t addr, u8_t new_relay, u8_t new_transmit, u8_t *status, u8_t *transmit)

Set the target node’s Relay parameters.

See

BT_MESH_TRANSMIT.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • new_relay: New relay state. Must be one of BT_MESH_RELAY_DISABLED or BT_MESH_RELAY_ENABLED.

  • new_transmit: New encoded relay transmit parameters.

Parameters

  • status: Status response parameter. Returns one of BT_MESH_RELAY_DISABLED, BT_MESH_RELAY_ENABLED or BT_MESH_RELAY_NOT_SUPPORTED on success.

  • transmit: Transmit response parameter. Returns the encoded relay transmission parameters on success. Decoded with BT_MESH_TRANSMIT_COUNT and BT_MESH_TRANSMIT_INT.

int bt_mesh_cfg_net_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, const u8_t net_key[16], u8_t *status)

Add a network key to the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • key_net_idx: Network key index.

  • net_key: Network key.

  • status: Status response parameter.

int bt_mesh_cfg_app_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, u16_t key_app_idx, const u8_t app_key[16], u8_t *status)

Add an application key to the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • key_net_idx: Network key index the application key belongs to.

  • key_app_idx: Application key index.

  • app_key: Application key.

  • status: Status response parameter.

int bt_mesh_cfg_mod_app_bind(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u8_t *status)

Bind an application to a SIG model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_app_idx: Application index to bind.

  • mod_id: Model ID.

  • status: Status response parameter.

int bt_mesh_cfg_mod_app_bind_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u16_t cid, u8_t *status)

Bind an application to a vendor model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_app_idx: Application index to bind.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • status: Status response parameter.

int bt_mesh_cfg_mod_pub_get(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)

Get publish parameters for a SIG model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_id: Model ID.

  • pub: Publication parameter return buffer.

  • status: Status response parameter.

int bt_mesh_cfg_mod_pub_get_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)

Get publish parameters for a vendor model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • pub: Publication parameter return buffer.

  • status: Status response parameter.

int bt_mesh_cfg_mod_pub_set(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)

Set publish parameters for a SIG model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_id: Model ID.

  • pub: Publication parameters.

  • status: Status response parameter.

int bt_mesh_cfg_mod_pub_set_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)

Set publish parameters for a vendor model on the target node.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • pub: Publication parameters.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_add(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)

Add a group address to a SIG model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)

Add a group address to a vendor model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_del(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)

Delete a group address in a SIG model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)

Delete a group address in a vendor model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)

Overwrite all addresses in a SIG model’s subscription list with a group address.

Deletes all subscriptions in the model’s subscription list, and adds a single group address instead.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)

Overwrite all addresses in a vendor model’s subscription list with a group address.

Deletes all subscriptions in the model’s subscription list, and adds a single group address instead.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • sub_addr: Group address to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_add(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)

Add a virtual address to a SIG model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address label to add to the subscription list.

  • mod_id: Model ID.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)

Add a virtual address to a vendor model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address label to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_del(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)

Delete a virtual address in a SIG model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address parameter to add to the subscription list.

  • mod_id: Model ID.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)

Delete a virtual address in a vendor model’s subscription list.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address label to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)

Overwrite all addresses in a SIG model’s subscription list with a virtual address.

Deletes all subscriptions in the model’s subscription list, and adds a single group address instead.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address label to add to the subscription list.

  • mod_id: Model ID.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_mod_sub_va_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)

Overwrite all addresses in a vendor model’s subscription list with a virtual address.

Deletes all subscriptions in the model’s subscription list, and adds a single group address instead.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • elem_addr: Element address the model is in.

  • label: Virtual address label to add to the subscription list.

  • mod_id: Model ID.

  • cid: Company ID of the model.

  • virt_addr: Virtual address response parameter.

  • status: Status response parameter.

int bt_mesh_cfg_hb_sub_set(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status)

Set the target node’s Heartbeat subscription parameters.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • sub: New Heartbeat subscription parameters.

  • status: Status response parameter.

int bt_mesh_cfg_hb_sub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status)

Get the target node’s Heartbeta subscription parameters.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • sub: Heartbeat subscription parameter return buffer.

  • status: Status response parameter.

int bt_mesh_cfg_hb_pub_set(u16_t net_idx, u16_t addr, const struct bt_mesh_cfg_hb_pub *pub, u8_t *status)

Set the target node’s Heartbeat publication parameters.

Note

The target node must already have received the specified network key.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • pub: New Heartbeat publication parameters.

  • status: Status response parameter.

int bt_mesh_cfg_hb_pub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_pub *pub, u8_t *status)

Get the target node’s Heartbeat publication parameters.

Return

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

Parameters

  • net_idx: Network index to encrypt with.

  • addr: Target node address.

  • pub: Heartbeat publication parameter return buffer.

  • status: Status response parameter.

s32_t bt_mesh_cfg_cli_timeout_get(void)

Get the current transmission timeout value.

Return

The configured transmission timeout.

void bt_mesh_cfg_cli_timeout_set(s32_t timeout)

Set the transmission timeout value.

Parameters

  • timeout: The new transmission timeout.

struct bt_mesh_cfg_cli
#include <cfg_cli.h>

Mesh Configuration Client Model Context

Public Members

struct bt_mesh_model *model

Composition data model entry pointer.

struct bt_mesh_cfg_mod_pub
#include <cfg_cli.h>

Model publication configuration parameters.

Public Members

u16_t addr

Publication destination address.

u16_t app_idx

Application index to publish with.

bool cred_flag

Friendship credential flag.

u8_t ttl

Time To Live to publish with.

u8_t period

Encoded publish period.

See

BT_MESH_PUB_PERIOD_100MS, BT_MESH_PUB_PERIOD_SEC, BT_MESH_PUB_PERIOD_10SEC, BT_MESH_PUB_PERIOD_10MIN

u8_t transmit

Encoded transmit parameters.

See

BT_MESH_TRANSMIT

struct bt_mesh_cfg_hb_sub
#include <cfg_cli.h>

Heartbeat subscription configuration parameters.

Public Members

u16_t src

Source address to receive Heartbeat messages from.

u16_t dst

Destination address to receive Heartbeat messages on.

u8_t period

Logarithmic subscription period to keep listening for. The decoded subscription period is (1 << (period - 1)), or 0 if period is 0.

u8_t count

Logarithmic Heartbeat subscription receive count. The decoded Heartbeat count is (1 << (count - 1)) if count is between 1 and 0xfe, 0 if count is 0 and 0xffff if count is 0xff.

Ignored in Heartbeat subscription set.

u8_t min

Minimum hops in received messages, ie the shortest registered path from the publishing node to the subscribing node. A Heartbeat received from an immediate neighbor has hop count = 1.

Ignored in Heartbeat subscription set.

u8_t max

Maximum hops in received messages, ie the longest registered path from the publishing node to the subscribing node. A Heartbeat received from an immediate neighbor has hop count = 1.

Ignored in Heartbeat subscription set.

struct bt_mesh_cfg_hb_pub
#include <cfg_cli.h>

Heartbeat publication configuration parameters.

Public Members

u16_t dst

Heartbeat destination address.

u8_t count

Logarithmic Heartbeat count. Decoded as (1 << (count - 1)) if count is between 1 and 0x11, 0 if count is 0, or “indefinitely” if count is 0xff.

When used in Heartbeat publication set, this parameter denotes the number of Heartbeat messages to send.

When returned from Heartbeat publication get, this parameter denotes the number of Heartbeat messages remaining to be sent.

u8_t period

Logarithmic Heartbeat publication transmit interval in seconds. Decoded as (1 << (period - 1)) if period is between 1 and 0x11. If period is 0, Heartbeat publication is disabled.

u8_t ttl

Publication message Time To Live value.

u16_t feat

Bitmap of features that trigger Heartbeat publications. Legal values are BT_MESH_FEAT_RELAY, BT_MESH_FEAT_PROXY, BT_MESH_FEAT_FRIEND and BT_MESH_FEAT_LOW_POWER

u16_t net_idx

Network index to publish with.