This is the documentation for the latest (main) development branch of Zephyr. 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 general Bluetooth mesh state.

Low Power Node

The Low Power Node (LPN) role allows battery powered devices to participate in a mesh network as a leaf node. An LPN interacts with the mesh network through a Friend node, which is responsible for relaying any messages directed to the LPN. The LPN saves power by keeping its radio turned off, and only wakes up to either send messages or poll the Friend node for any incoming messages.

The radio control and polling is managed automatically by the mesh stack, but the LPN API allows the application to trigger the polling at any time through bt_mesh_lpn_poll(). The LPN operation parameters, including poll interval, poll event timing and Friend requirements is controlled through the :kconfig:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.

Replay Protection List

The Replay Protection List (RPL) is used to hold recently received sequence numbers from elements within the mesh network to perform protection against replay attacks.

To keep a node protected against replay attacks after reboot, it needs to store the entire RPL in the persistent storage before it is powered off. Depending on the amount of traffic in a mesh network, storing recently seen sequence numbers can make flash wear out sooner or later. To mitigate this, @ref CONFIG_BT_MESH_RPL_STORE_TIMEOUT can be used. This option postpones storing of RPL entries in the persistent storage.

This option, however, doesn’t completely solve the issue as the node may get powered off before the timer to store the RPL is fired. To ensure that messages can not be replayed, the node can initiate storage of the pending RPL entry (or entries) at any time (or sufficiently before power loss) by calling @ref bt_mesh_rpl_pending_store. This is up to the node to decide, which RPL entries are to be stored in this case.

Setting @ref CONFIG_BT_MESH_RPL_STORE_TIMEOUT to -1 allows to completely switch off the timer, which can help to significantly reduce flash wear out. This moves the responsibility of storing RPL to the user application and requires that sufficient power backup is available from the time this API is called until all RPL entries are written to the flash.

Finding the right balance between @ref CONFIG_BT_MESH_RPL_STORE_TIMEOUT and calling @ref bt_mesh_rpl_pending_store may reduce a risk of security volnurability and flash wear out.

API reference

group bt_mesh

Bluetooth mesh.

Defines

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

struct bt_mesh_lpn_cb
#include <main.h>

Low Power Node callback functions.

Public Members

void (*established)(uint16_t net_idx, uint16_t friend_addr, uint8_t queue_size, uint8_t recv_window)

Friendship established.

This callback notifies the application that friendship has been successfully established.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • friend_addr – Friend address.

  • queue_size – Friend queue size.

  • recv_window – Low Power Node’s listens duration for Friend response.

void (*terminated)(uint16_t net_idx, uint16_t friend_addr)

Friendship terminated.

This callback notifies the application that friendship has been terminated.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • friend_addr – Friend address.

void (*polled)(uint16_t net_idx, uint16_t friend_addr, bool retry)

Local Poll Request.

This callback notifies the application that the local node has polled the friend node.

This callback will be called before bt_mesh_lpn_cb::established when attempting to establish a friendship.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • friend_addr – Friend address.

  • retry – Retry or first poll request for each transaction.

struct bt_mesh_friend_cb
#include <main.h>

Friend Node callback functions.

Public Members

void (*established)(uint16_t net_idx, uint16_t lpn_addr, uint8_t recv_delay, uint32_t polltimeout)

Friendship established.

This callback notifies the application that friendship has been successfully established.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • lpn_addr – Low Power Node address.

  • recv_delay – Receive Delay in units of 1 millisecond.

  • polltimeout – PollTimeout in units of 1 millisecond.

void (*terminated)(uint16_t net_idx, uint16_t lpn_addr)

Friendship terminated.

This callback notifies the application that friendship has been terminated.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • lpn_addr – Low Power Node address.

void (*polled)(uint16_t net_idx, uint16_t lpn_addr)

Friend Poll Request.

This callback notifies the application that the low power node has polled the friend node.

This callback will be called before bt_mesh_friend_cb::established when attempting to establish a friendship.

Parameters

  • net_idx – NetKeyIndex used during friendship establishment.

  • lpn_addr – LPN address.