.. _bluetooth_mesh_core:

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
:c:func:`bt_mesh_lpn_poll`. The LPN operation parameters, including poll
interval, poll event timing and Friend requirements is controlled through the
:kconfig:option:`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 :kconfig:option:`CONFIG_LOG_MODE_DEFERRED` option. Log modes other than the
deferred may cause unintended delays during processing of log messages. This in
turns will affect scheduling of the receive delay and receive window. The same
limitation applies for the :kconfig:option:`CONFIG_BT_MESH_FRIEND` option.

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,
:kconfig:option:`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 :c:func:`bt_mesh_rpl_pending_store`. This is up to the node to decide,
which RPL entries are to be stored in this case.

Setting :kconfig:option:`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 :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` and
calling :c:func:`bt_mesh_rpl_pending_store` may reduce a risk of security
vulnerability and flash wear out.

.. warning:

   Failing to enable :kconfig:option:`CONFIG_BT_SETTINGS`, or setting
   :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` to -1 and not storing
   the RPL between reboots, will make the device vulnerable to replay attacks
   and not perform the replay protection required by the spec.


API reference
**************

.. doxygengroup:: bt_mesh