1.. _bluetooth_mesh_brg_cfg:
2
3Subnet Bridge
4#############
5
6With Bluetooth Mesh Protocol Specification version 1.1, the Bluetooth Mesh Subnet Bridge feature was
7introduced.
8This feature allows mesh networks to use subnets for area isolation, but to also allow communication
9between specific devices in different, adjacent subnets without compromising security.
10
11The Bluetooth Mesh Subnet Bridge feature makes it possible for selected nodes in the network to act
12as Subnet Bridges, allowing controlled communication by relaying messages between nodes in adjacent
13subnets.
14
15The Subnet Bridge feature includes two models:
16
17- :ref:`bluetooth_mesh_models_brg_cfg_srv`
18- :ref:`bluetooth_mesh_models_brg_cfg_cli`
19
20The Bridge Configuration Server model is mandatory for supporting the Subnet Bridge feature.
21The Bridge Configuration Client model is optional and allows nodes to configure the Subnet Bridge on
22other nodes.
23These models define the necessary states, messages, and behaviors for configuring and managing the
24Subnet Bridge feature.
25
26The configuration and management of the Subnet Bridge feature are handled using the Bridge
27Configuration Server and Client models.
28A node implementing the Bridge Configuration Client model can act as a *Configuration Manager* for
29the Subnet Bridge feature.
30
31Concepts
32********
33
34To get a better understanding of the Subnet Bridge feature and its capabilities, an overview of a
35few concepts is needed.
36
37Subnet
38======
39
40A subnet is a group of nodes within a mesh network that share a common network key, enabling them to
41communicate securely at the network layer.
42Each subnet operates independently, with nodes exchanging messages exclusively within that group.
43A node may belong to multiple subnets at the same time.
44
45Subnet Bridge node
46==================
47
48A Subnet Bridge node is a node in a Bluetooth Mesh network that belongs to multiple subnets and has
49a Subnet Bridge functionality enabled. Subnet bridging can be performed only by such a node. The
50Subnet Bridge node connects the subnets, and allows communication between them by relaying
51messages across the subnet groups.
52
53The Subnet Bridge node has a primary subnet, based on the primary NetKey, which handles the
54IV Update procedure and propagates updates to other subnets.
55The secondary subnets, on which messages are relayed, are referred to as *bridged subnets*.
56
57Bridging Table
58==============
59
60The Bridging Table contains the entries for the subnets that are bridged by the node, and is managed
61by the Bridge Configuration Server model.
62
63The maximum number of entries in the bridging table is defined by the
64:kconfig:option:`CONFIG_BT_MESH_BRG_TABLE_ITEMS_MAX` option, which defaults to the minimum value of
6516, with a maximum possible size of 255.
66
67Enabling or disabling the Subnet Bridge feature
68***********************************************
69
70The Bridge Configuration Client (or Configuration Manager) can enable or disable the Subnet Bridge
71feature on a node by sending a **Subnet Bridge Set** message to the Bridge Configuration
72Server model on the target node, using the :c:func:`bt_mesh_brg_cfg_cli_set` function.
73
74Adding or removing subnets
75**************************
76
77The Bridge Configuration Client can add or remove an entry from the Bridging Table by sending a
78**Bridging Table Add** or **Bridging Table Remove** message to the Bridge Configuration
79Server model on the target node, calling the :c:func:`bt_mesh_brg_cfg_cli_table_add` or
80:c:func:`bt_mesh_brg_cfg_cli_table_remove` functions.
81
82.. _bluetooth_mesh_brg_cfg_states:
83
84Subnet Bridge states
85********************
86
87The Subnet Bridge has the following states:
88
89- *Subnet Bridge*: This state indicates whether the Subnet Bridge feature is enabled or disabled on
90  the node.
91  The Bridge Configuration Client can retrieve this information by sending a **Subnet Bridge Get**
92  message to the Bridge Configuration Server using the :c:func:`bt_mesh_brg_cfg_cli_get` function.
93
94- *Bridging Table*: This state holds the bridging table. The Client can request a list of
95  entries from a Bridging Table by sending a **Bridging Table Get** message to the target node using
96  the :c:func:`bt_mesh_brg_cfg_cli_table_get` function.
97
98  The Client can get a list of subnets currently bridged by a Subnet Bridge by sending a
99  **Bridged Subnets Get** message to the target Server by calling the
100  :c:func:`bt_mesh_brg_cfg_cli_subnets_get` function.
101
102- *Bridging Table Size*: This state reports the maximum number of entries the Bridging Table can
103  store. The Client can retrieve this information by sending a **Bridging Table Size Get** message
104  using the :c:func:`bt_mesh_brg_cfg_cli_table_size_get` function.
105  This is a read-only state.
106
107Subnet bridging and replay protection
108*************************************
109
110The Subnet Bridge feature enables message relaying between subnets and requires effective replay
111protection to ensure network security. Key considerations to take into account are described below.
112
113Relay buffer considerations
114===========================
115
116When a message is relayed between subnets by a Subnet Bridge, it is allocated from the relay buffer
117pool. The number of relay buffers are configurable using the
118:kconfig:option:`CONFIG_BT_MESH_RELAY_BUF_COUNT` Kconfig option.
119
120When :kconfig:option:`CONFIG_BT_MESH_ADV_EXT` is enabled, messages will be transmitted using the
121relay advertising sets. The number of advertising sets are configurable using the
122:kconfig:option:`CONFIG_BT_MESH_RELAY_ADV_SETS` Kconfig option.
123
124Both the relay buffer pool and advertising sets can be used even if the relay feature
125:kconfig:option:`CONFIG_BT_MESH_RELAY` is disabled.
126
127Replay protection and Bridging Table
128====================================
129
130A Subnet Bridge node must implement replay protection for all Access and Transport Control messages
131sent to bridged subnets.
132
133The Replay Protection List (RPL) works with the Bridging Table to ensure security:
134
135- The Subnet Bridge stores the latest IVISeq for each source address authorized to send messages to
136  bridged subnets.
137
138- Messages with an IVISeq less than or equal to the stored value are discarded, while valid messages
139  update the stored IVISeq before being relayed.
140
141To ensure proper operation, it is important that the RPL and Bridging Table are synchronized,
142as every bridged message must pass through the replay protection mechanism before being relayed.
143
144.. note::
145
146   The RPL size should scale with the Bridging Table. As the number of bridged subnets grows,
147   more source addresses and IVISeq values must be tracked, requiring a larger RPL to maintain
148   effective replay protection.
149
150Subnet Bridge and Directed Forwarding
151*************************************
152
153Bluetooth Mesh Directed Forwarding (MDF) enables efficient routing between nodes across subnets by
154optimizing relay paths. While MDF can enhance Subnet Bridging by handling path discovery and
155forwarding, the current implementation does not support this feature.
156
157API reference
158*************
159
160This section contains types and defines common to the Bridge Configuration models.
161
162.. doxygengroup:: bt_mesh_brg_cfg
163