1.. _bluetooth_mesh_core:
2
3Core
4####
5
6The core provides functionality for managing the general Bluetooth Mesh
7state.
8
9.. _bluetooth_mesh_lpn:
10
11Low Power Node
12**************
13
14The Low Power Node (LPN) role allows battery powered devices to participate in
15a mesh network as a leaf node. An LPN interacts with the mesh network through
16a Friend node, which is responsible for relaying any messages directed to the
17LPN. The LPN saves power by keeping its radio turned off, and only wakes up to
18either send messages or poll the Friend node for any incoming messages.
19
20The radio control and polling is managed automatically by the mesh stack, but
21the LPN API allows the application to trigger the polling at any time through
22:c:func:`bt_mesh_lpn_poll`. The LPN operation parameters, including poll
23interval, poll event timing and Friend requirements is controlled through the
24:kconfig:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.
25
26When using the LPN feature with logging, it is strongly recommended to only use
27the :kconfig:option:`CONFIG_LOG_MODE_DEFERRED` option. Log modes other than the
28deferred may cause unintended delays during processing of log messages. This in
29turns will affect scheduling of the receive delay and receive window. The same
30limitation applies for the :kconfig:option:`CONFIG_BT_MESH_FRIEND` option.
31
32Replay Protection List
33**********************
34
35The Replay Protection List (RPL) is used to hold recently received sequence
36numbers from elements within the mesh network to perform protection against
37replay attacks.
38
39To keep a node protected against replay attacks after reboot, it needs to store
40the entire RPL in the persistent storage before it is powered off. Depending on
41the amount of traffic in a mesh network, storing recently seen sequence numbers
42can make flash wear out sooner or later. To mitigate this,
43:kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` can be used. This option postpones
44storing of RPL entries in the persistent storage.
45
46This option, however, doesn't completely solve the issue as the node may
47get powered off before the timer to store the RPL is fired. To ensure that
48messages can not be replayed, the node can initiate storage of the pending
49RPL entry (or entries) at any time (or sufficiently before power loss)
50by calling :c:func:`bt_mesh_rpl_pending_store`. This is up to the node to decide,
51which RPL entries are to be stored in this case.
52
53Setting :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` to -1 allows to completely
54switch off the timer, which can help to significantly reduce flash wear out.
55This moves the responsibility of storing RPL to the user application and
56requires that sufficient power backup is available from the time this API
57is called until all RPL entries are written to the flash.
58
59Finding the right balance between :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` and
60calling :c:func:`bt_mesh_rpl_pending_store` may reduce a risk of security
61vulnerability and flash wear out.
62
63.. warning:
64
65   Failing to enable :kconfig:option:`CONFIG_BT_SETTINGS`, or setting
66   :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT` to -1 and not storing
67   the RPL between reboots, will make the device vulnerable to replay attacks
68   and not perform the replay protection required by the spec.
69
70.. _bluetooth_mesh_persistent_storage:
71
72Persistent storage
73******************
74
75The mesh stack uses the :ref:`Settings Subsystem <settings_api>` for storing the
76device configuration persistently. When the stack configuration changes and
77the change needs to be stored persistently, the stack schedules a work item.
78The delay between scheduling the work item and submitting it to the workqueue
79is defined by the :kconfig:option:`CONFIG_BT_MESH_STORE_TIMEOUT` option. Once
80storing of data is scheduled, it can not be rescheduled until the work item is
81processed. Exceptions are made in certain cases as described below.
82
83When IV index, Sequence Number or CDB configuration have to be stored, the work
84item is submitted to the workqueue without the delay. If the work item was
85previously scheduled, it will be rescheduled without the delay.
86
87The Replay Protection List uses the same work item to store RPL entries. If
88storing of RPL entries is requested and no other configuration is pending to be
89stored, the delay is set to :kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT`.
90If other stack configuration has to be stored, the delay defined by
91the :kconfig:option:`CONFIG_BT_MESH_STORE_TIMEOUT` option is less than
92:kconfig:option:`CONFIG_BT_MESH_RPL_STORE_TIMEOUT`, and the work item was
93scheduled by the Replay Protection List, the work item will be rescheduled.
94
95When the work item is running, the stack will store all pending configuration,
96including the RPL entries.
97
98Work item execution context
99===========================
100
101The :kconfig:option:`CONFIG_BT_MESH_SETTINGS_WORKQ` option configures the
102context from which the work item is executed. This option is enabled by
103default, and results in stack using a dedicated cooperative thread to
104process the work item. This allows the stack to process other incoming and
105outgoing messages, as well as other work items submitted to the system
106workqueue, while the stack configuration is being stored.
107
108When this option is disabled, the work item is submitted to the system workqueue.
109This means that the system workqueue is blocked for the time it takes to store
110the stack's configuration. It is not recommended to disable this option as this
111will make the device non-responsive for a noticeable amount of time.
112
113.. _bluetooth_mesh_adv_identity:
114
115Advertisement identity
116**********************
117
118All mesh stack bearers advertise data with the :c:macro:`BT_ID_DEFAULT` local identity.
119The value is preset in the mesh stack implementation. When Bluetooth® Low Energy (LE)
120and Bluetooth Mesh coexist on the same device, the application should allocate and
121configure another local identity for Bluetooth LE purposes before starting the communication.
122
123API reference
124**************
125
126.. doxygengroup:: bt_mesh
127