This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Core

The core provides functionality for managing the state of a generic Bluetooth Mesh.

Low-Power Node

The Low Power Node (LPN) role allows battery-powered devices to participate in a mesh network as leaf nodes. LPNs interact with the mesh network through Friend nodes, which relay any messages directed to the LPN. LPNs save power by keeping their radios off and only waking up to send messages or poll Friend Nodes for any incoming messages.

The radio control and polling are managed automatically by the mesh stack, but the LPN API allows the applications to trigger polling at any time through the function bt_mesh_lpn_poll(). The LPN operation parameters, including polling intervals, polling event timing, and Friend requirements, are controlled through the CONFIG_BT_MESH_LOW_POWER option and related configuration options.

When using the LPN feature with logging, it is strongly recommended to only use the CONFIG_LOG_MODE_DEFERRED option. Log modes other than the Deferred may cause unexpected delays during processing of log messages. This will affect receive delays and the scheduling of receive windows. The same limitation applies to the CONFIG_BT_MESH_FRIEND option.

Replay Protection List

The Replay Protection List (RPL) is used to store the sequence numbers of messages recently received from elements in the mesh network to perform protection against replay attacks6n.

To protect the node from replay attacks after a restart, it needs to store the entire RPL in persistent storage before power is lost. Depending on the traffic in the mesh network, storing the recently seen sequence numbers can wear out flash memory sooner or later. To mitigate this,the :c:macro:CONFIG_BT_MESH_RPL_STORE_TIMEOUT can be used. This option postpones storing of RPL entries in the persistent storage.

However, this option does not completely solve the problem, as the node may shut down before the timer that triggers the storage of the RPL is reached. To ensure that messages cannot be replayed, the node can initiate the storage of pending RPL entries at any time (or sufficient time before power is lost) by calling bt_mesh_rpl_pending_store(). This is up to the node to decide, which RPL entries are to be stored in this case.

Setting CONFIG_BT_MESH_RPL_STORE_TIMEOUT to -1 allows completely turning off the timer, which helps significantly reduce flash wear. This shifts the responsibility of storing the RPL to the user application and requires enough power backup from the time the API is called until all RPL entries are written to flash memory.

Finding the right balance between CONFIG_BT_MESH_RPL_STORE_TIMEOUT and calling bt_mesh_rpl_pending_store() may reduce a risk of security vulnerability and flash wear out.

Persistent storage

The mesh stack uses the Settings Subsystem for storing the device configuration persistently. When a stack configuration changes and the change needs to be stored persistently, the stack schedules a work item. The delay between scheduling the work item and submitting it to the work queue is defined by the :c:macro: CONFIG_BT_MESH_STORE_TIMEOUT option. Once the storage of data is scheduled, it can not be rescheduled until the work item is processed. Exceptions are made in certain cases as described below.

When it is necessary to store the IV Index, Sequence Number, or CDB configuration, the work item is submitted to the work queue without the delay. If a work item was previously scheduled, it will be rescheduled without the delay.

The Replay Protection List uses the same work item to store RPL entries. If storing an RPL entry is requested and there are no other configurations pending storage, the delay is set by the :c:macro:CONFIG_BT_MESH_RPL_STORE_TIMEOUT. If other stack configuration has to be stored, the delay defined by the :c:macro:CONFIG_BT_MESH_STORE_TIMEOUT option is less than :c:macro:CONFIG_BT_MESH_RPL_STORE_TIMEOUT, and the work item was scheduled by the Replay Protection List, the work item will be rescheduled.

When the work item is being executed, the stack will store all pending configuration, including the RPL entries.

Work Item Execution Context

The:c:macro:CONFIG_BT_MESH_SETTINGS_WORKQ option configures the context from which work items are executed. This option is enabled by default and results in a dedicated cooperative thread being used for handling stack work items. This allows the stack to process other incoming and outgoing messages and work items submitted to the system work queue while storing stack configurations.

When this option is disabled, the work item is submitted to the system workqueue. This means that the system workqueue is blocked for the time it takes to store the stack’s configuration. It is not recommended to disable this option as this will make the device non-responsive for a noticeable amount of time.

API Reference

group bt_mesh

Bluetooth mesh.

Defines

BT_MESH_NET_PRIMARY

Primary Network Key index

BT_MESH_FEAT_RELAY

Relay feature

BT_MESH_FEAT_PROXY

GATT Proxy feature

BT_MESH_FEAT_FRIEND

Friend feature

BT_MESH_FEAT_LOW_POWER

Low Power Node feature

BT_MESH_FEAT_SUPPORTED

Supported heartbeat publication features

BT_MESH_LPN_CB_DEFINE(_name)

Register a callback structure for Friendship events.

Parameters:

  • _name – Name of callback structure.

BT_MESH_FRIEND_CB_DEFINE(_name)

Register a callback structure for Friendship events.

Registers a callback structure that will be called whenever Friendship gets established or terminated.

Parameters:

  • _name – Name of callback structure.

Functions

int bt_mesh_init(const struct bt_mesh_prov *prov, const struct bt_mesh_comp *comp)

Initialize Mesh support.

After calling this API, the node will not automatically advertise as unprovisioned, rather the bt_mesh_prov_enable() API needs to be called to enable unprovisioned advertising on one or more provisioning bearers.

Parameters:

  • prov – Node provisioning information.

  • comp – Node Composition.

Returns:

Zero on success or (negative) error code otherwise.

void bt_mesh_reset(void)

Reset the state of the local Mesh node.

Resets the state of the node, which means that it needs to be reprovisioned to become an active node in a Mesh network again.

After calling this API, the node will not automatically advertise as unprovisioned, rather the bt_mesh_prov_enable() API needs to be called to enable unprovisioned advertising on one or more provisioning bearers.

int bt_mesh_suspend(void)

Suspend the Mesh network temporarily.

This API can be used for power saving purposes, but the user should be aware that leaving the local node suspended for a long period of time may cause it to become permanently disconnected from the Mesh network. If at all possible, the Friendship feature should be used instead, to make the node into a Low Power Node.

Returns:

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

int bt_mesh_resume(void)

Resume a suspended Mesh network.

This API resumes the local node, after it has been suspended using the bt_mesh_suspend() API.

Returns:

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

void bt_mesh_iv_update_test(bool enable)

Toggle the IV Update test mode.

This API is only available if the IV Update test mode has been enabled in Kconfig. It is needed for passing most of the IV Update qualification test cases.

Parameters:

enable – true to enable IV Update test mode, false to disable it.

bool bt_mesh_iv_update(void)

Toggle the IV Update state.

This API is only available if the IV Update test mode has been enabled in Kconfig. It is needed for passing most of the IV Update qualification test cases.

Returns:

true if IV Update In Progress state was entered, false otherwise.

int bt_mesh_lpn_set(bool enable)

Toggle the Low Power feature of the local device.

Enables or disables the Low Power feature of the local device. This is exposed as a run-time feature, since the device might want to change this e.g. based on being plugged into a stable power source or running from a battery power source.

Parameters:

enable – true to enable LPN functionality, false to disable it.

Returns:

Zero on success or (negative) error code otherwise.

int bt_mesh_lpn_poll(void)

Send out a Friend Poll message.

Send a Friend Poll message to the Friend of this node. If there is no established Friendship the function will return an error.

Returns:

Zero on success or (negative) error code otherwise.

int bt_mesh_friend_terminate(uint16_t lpn_addr)

Terminate Friendship.

Terminated Friendship for given LPN.

Parameters:

lpn_addr – Low Power Node address.

Returns:

Zero on success or (negative) error code otherwise.

void bt_mesh_rpl_pending_store(uint16_t addr)

Store pending RPL entry(ies) in the persistent storage.

This API allows the user to store pending RPL entry(ies) in the persistent storage without waiting for the timeout.

Note

When flash is used as the persistent storage, calling this API too frequently may wear it out.

Parameters:

addr – Address of the node which RPL entry needs to be stored or BT_MESH_ADDR_ALL_NODES to store all pending RPL entries.

const uint8_t *bt_mesh_va_uuid_get(uint16_t addr, const uint8_t *uuid, uint16_t *retaddr)

Iterate stored Label UUIDs.

When addr is BT_MESH_ADDR_UNASSIGNED, this function iterates over all available addresses starting with uuid. In this case, use retaddr to get virtual address representation of the returned Label UUID. When addr is a virtual address, this function returns next Label UUID corresponding to the addr. When uuid is NULL, this function returns the first available UUID. If uuid is previously returned uuid, this function returns following uuid.

Parameters:

  • addr – Virtual address to search for, or BT_MESH_ADDR_UNASSIGNED.

  • uuid – Pointer to the previously returned Label UUID or NULL.

  • retaddr – Pointer to a memory where virtual address representation of the returning UUID is to be stored to.

Returns:

Pointer to Label UUID, or NULL if no more entries found.

struct bt_mesh_lpn_cb

Low Power Node callback functions.

struct bt_mesh_friend_cb

Friend Node callback functions.