Core API¶
The Bluetooth Mesh Core API 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
CONFIG_BT_MESH_LOW_POWER option and related configuration options.
API reference¶
-
group
bt_mesh Bluetooth Mesh.
Defines
-
BT_MESH_NET_PRIMARY¶
-
BT_MESH_RELAY_DISABLED¶
-
BT_MESH_RELAY_ENABLED¶
-
BT_MESH_RELAY_NOT_SUPPORTED¶
-
BT_MESH_BEACON_DISABLED¶
-
BT_MESH_BEACON_ENABLED¶
-
BT_MESH_GATT_PROXY_DISABLED¶
-
BT_MESH_GATT_PROXY_ENABLED¶
-
BT_MESH_GATT_PROXY_NOT_SUPPORTED¶
-
BT_MESH_FRIEND_DISABLED¶
-
BT_MESH_FRIEND_ENABLED¶
-
BT_MESH_FRIEND_NOT_SUPPORTED¶
-
BT_MESH_NODE_IDENTITY_STOPPED¶
-
BT_MESH_NODE_IDENTITY_RUNNING¶
-
BT_MESH_NODE_IDENTITY_NOT_SUPPORTED¶
-
BT_MESH_FEAT_RELAY¶
-
BT_MESH_FEAT_PROXY¶
-
BT_MESH_FEAT_FRIEND¶
-
BT_MESH_FEAT_LOW_POWER¶
-
BT_MESH_FEAT_SUPPORTED¶
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.
- Return
Zero on success or (negative) error code otherwise.
- Parameters
prov: Node provisioning information.comp: Node Composition.
-
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.
- Return
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.
- Return
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.
- Return
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.
- Return
Zero on success or (negative) error code otherwise.
- Parameters
enable: true to enable LPN functionality, false to disable it.
-
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.
- Return
Zero on success or (negative) error code otherwise.
-
void
bt_mesh_lpn_set_cb(void (*cb)(u16_t friend_addr, bool established))¶ Register a callback for Friendship changes.
Registers a callback that will be called whenever Friendship gets established or is lost.
- Parameters
cb: Function to call when the Friendship status changes.
-