Line data Source code
1 1 : /** @file
2 : * @brief Runtime configuration APIs.
3 : */
4 :
5 : /*
6 : * Copyright (c) 2020 Nordic Semiconductor
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_
12 :
13 : #include <stdbool.h>
14 : #include <stddef.h>
15 :
16 : #include <sys/types.h>
17 :
18 : /**
19 : * @brief Runtime Configuration
20 : * @defgroup bt_mesh_cfg Runtime Configuration
21 : * @ingroup bt_mesh
22 : * @{
23 : */
24 :
25 : #ifdef __cplusplus
26 : extern "C" {
27 : #endif
28 :
29 : /** Bluetooth Mesh feature states */
30 1 : enum bt_mesh_feat_state {
31 : /** Feature is supported, but disabled. */
32 : BT_MESH_FEATURE_DISABLED,
33 : /** Feature is supported and enabled. */
34 : BT_MESH_FEATURE_ENABLED,
35 : /** Feature is not supported, and cannot be enabled. */
36 : BT_MESH_FEATURE_NOT_SUPPORTED,
37 : };
38 :
39 : /* Key Refresh Phase */
40 0 : #define BT_MESH_KR_NORMAL 0x00
41 0 : #define BT_MESH_KR_PHASE_1 0x01
42 0 : #define BT_MESH_KR_PHASE_2 0x02
43 0 : #define BT_MESH_KR_PHASE_3 0x03
44 :
45 : /* Legacy feature defines */
46 0 : #define BT_MESH_RELAY_DISABLED BT_MESH_FEATURE_DISABLED
47 0 : #define BT_MESH_RELAY_ENABLED BT_MESH_FEATURE_ENABLED
48 0 : #define BT_MESH_RELAY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
49 :
50 0 : #define BT_MESH_BEACON_DISABLED BT_MESH_FEATURE_DISABLED
51 0 : #define BT_MESH_BEACON_ENABLED BT_MESH_FEATURE_ENABLED
52 :
53 0 : #define BT_MESH_PRIV_BEACON_DISABLED BT_MESH_FEATURE_DISABLED
54 0 : #define BT_MESH_PRIV_BEACON_ENABLED BT_MESH_FEATURE_ENABLED
55 :
56 0 : #define BT_MESH_GATT_PROXY_DISABLED BT_MESH_FEATURE_DISABLED
57 0 : #define BT_MESH_GATT_PROXY_ENABLED BT_MESH_FEATURE_ENABLED
58 0 : #define BT_MESH_GATT_PROXY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
59 :
60 0 : #define BT_MESH_PRIV_GATT_PROXY_DISABLED BT_MESH_FEATURE_DISABLED
61 0 : #define BT_MESH_PRIV_GATT_PROXY_ENABLED BT_MESH_FEATURE_ENABLED
62 0 : #define BT_MESH_PRIV_GATT_PROXY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
63 :
64 0 : #define BT_MESH_FRIEND_DISABLED BT_MESH_FEATURE_DISABLED
65 0 : #define BT_MESH_FRIEND_ENABLED BT_MESH_FEATURE_ENABLED
66 0 : #define BT_MESH_FRIEND_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
67 :
68 0 : #define BT_MESH_NODE_IDENTITY_STOPPED BT_MESH_FEATURE_DISABLED
69 0 : #define BT_MESH_NODE_IDENTITY_RUNNING BT_MESH_FEATURE_ENABLED
70 0 : #define BT_MESH_NODE_IDENTITY_NOT_SUPPORTED BT_MESH_FEATURE_NOT_SUPPORTED
71 :
72 : /** @brief Enable or disable sending of the Secure Network Beacon.
73 : *
74 : * @param beacon New Secure Network Beacon state.
75 : */
76 1 : void bt_mesh_beacon_set(bool beacon);
77 :
78 : /** @brief Get the current Secure Network Beacon state.
79 : *
80 : * @returns Whether the Secure Network Beacon feature is enabled.
81 : */
82 1 : bool bt_mesh_beacon_enabled(void);
83 :
84 : /** @brief Enable or disable sending of the Mesh Private beacon.
85 : *
86 : * Support for the Private beacon state must be enabled with @c
87 : * CONFIG_BT_MESH_PRIV_BEACONS.
88 : *
89 : * @param priv_beacon New Mesh Private beacon state. Must be one of
90 : * @ref BT_MESH_FEATURE_ENABLED and
91 : * @ref BT_MESH_FEATURE_DISABLED.
92 : *
93 : * @retval 0 Successfully changed the Mesh Private beacon feature state.
94 : * @retval -ENOTSUP The Mesh Private beacon feature is not supported.
95 : * @retval -EINVAL Invalid parameter.
96 : * @retval -EALREADY Already in the given state.
97 : */
98 1 : int bt_mesh_priv_beacon_set(enum bt_mesh_feat_state priv_beacon);
99 :
100 : /** @brief Get the current Mesh Private beacon state.
101 : *
102 : * @returns The Mesh Private beacon feature state.
103 : */
104 1 : enum bt_mesh_feat_state bt_mesh_priv_beacon_get(void);
105 :
106 : /** @brief Set the current Mesh Private beacon update interval.
107 : *
108 : * The Mesh Private beacon's randomization value is updated regularly to
109 : * maintain the node's privacy. The update interval controls how often
110 : * the beacon is updated, in 10 second increments.
111 : *
112 : * @param interval Private beacon update interval in 10 second steps, or 0 to
113 : * update on every beacon transmission.
114 : */
115 1 : void bt_mesh_priv_beacon_update_interval_set(uint8_t interval);
116 :
117 : /** @brief Get the current Mesh Private beacon update interval.
118 : *
119 : * The Mesh Private beacon's randomization value is updated regularly to
120 : * maintain the node's privacy. The update interval controls how often
121 : * the beacon is updated, in 10 second increments.
122 : *
123 : * @returns The Private beacon update interval in 10 second steps, or 0 if
124 : * the beacon is updated every time it's transmitted.
125 : */
126 1 : uint8_t bt_mesh_priv_beacon_update_interval_get(void);
127 :
128 : /** @brief Set the default TTL value.
129 : *
130 : * The default TTL value is used when no explicit TTL value is set. Models will
131 : * use the default TTL value when @ref bt_mesh_msg_ctx::send_ttl is
132 : * @ref BT_MESH_TTL_DEFAULT.
133 : *
134 : * @param default_ttl The new default TTL value. Valid values are 0x00 and 0x02
135 : * to @ref BT_MESH_TTL_MAX.
136 : *
137 : * @retval 0 Successfully set the default TTL value.
138 : * @retval -EINVAL Invalid TTL value.
139 : */
140 1 : int bt_mesh_default_ttl_set(uint8_t default_ttl);
141 :
142 : /** @brief Get the current default TTL value.
143 : *
144 : * @return The current default TTL value.
145 : */
146 1 : uint8_t bt_mesh_default_ttl_get(void);
147 :
148 : /** @brief Get the current Mesh On-Demand Private Proxy state.
149 : *
150 : * @retval 0 or positive value represents On-Demand Private Proxy feature state
151 : * @retval -ENOTSUP The On-Demand Private Proxy feature is not supported.
152 : */
153 1 : int bt_mesh_od_priv_proxy_get(void);
154 :
155 : /** @brief Set state of Mesh On-Demand Private Proxy.
156 : *
157 : * Support for the On-Demand Private Proxy state must be enabled with @c
158 : * BT_MESH_OD_PRIV_PROXY_SRV.
159 : *
160 : * @param on_demand_proxy New Mesh On-Demand Private Proxy state. Value of 0x00 means that
161 : * advertising with Private Network Identity cannot be enabled on demand.
162 : * Values in range 0x01 - 0xFF set interval of this advertising after
163 : * valid Solicitation PDU is received or client disconnects.
164 : *
165 : * @retval 0 Successfully changed the Mesh On-Demand Private Proxy feature state.
166 : * @retval -ENOTSUP The On-Demand Private Proxy feature is not supported.
167 : * @retval -EINVAL Invalid parameter.
168 : * @retval -EALREADY Already in the given state.
169 : */
170 1 : int bt_mesh_od_priv_proxy_set(uint8_t on_demand_proxy);
171 :
172 : /** @brief Set the Network Transmit parameters.
173 : *
174 : * The Network Transmit parameters determine the parameters local messages are
175 : * transmitted with.
176 : *
177 : * @see BT_MESH_TRANSMIT
178 : *
179 : * @param xmit New Network Transmit parameters. Use @ref BT_MESH_TRANSMIT for
180 : * encoding.
181 : */
182 1 : void bt_mesh_net_transmit_set(uint8_t xmit);
183 :
184 : /** @brief Get the current Network Transmit parameters.
185 : *
186 : * The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be
187 : * used to decode the Network Transmit parameters.
188 : *
189 : * @return The current Network Transmit parameters.
190 : */
191 1 : uint8_t bt_mesh_net_transmit_get(void);
192 :
193 : /** @brief Configure the Relay feature.
194 : *
195 : * Enable or disable the Relay feature, and configure the parameters to
196 : * transmit relayed messages with.
197 : *
198 : * Support for the Relay feature must be enabled through the
199 : * @c CONFIG_BT_MESH_RELAY configuration option.
200 : *
201 : * @see BT_MESH_TRANSMIT
202 : *
203 : * @param relay New Relay feature state. Must be one of
204 : * @ref BT_MESH_FEATURE_ENABLED and
205 : * @ref BT_MESH_FEATURE_DISABLED.
206 : * @param xmit New Relay retransmit parameters. Use @ref BT_MESH_TRANSMIT for
207 : * encoding.
208 : *
209 : * @retval 0 Successfully changed the Relay configuration.
210 : * @retval -ENOTSUP The Relay feature is not supported.
211 : * @retval -EINVAL Invalid parameter.
212 : * @retval -EALREADY Already using the given parameters.
213 : */
214 1 : int bt_mesh_relay_set(enum bt_mesh_feat_state relay, uint8_t xmit);
215 :
216 : /** @brief Get the current Relay feature state.
217 : *
218 : * @returns The Relay feature state.
219 : */
220 1 : enum bt_mesh_feat_state bt_mesh_relay_get(void);
221 :
222 : /** @brief Get the current Relay Retransmit parameters.
223 : *
224 : * The @ref BT_MESH_TRANSMIT_COUNT and @ref BT_MESH_TRANSMIT_INT macros can be
225 : * used to decode the Relay Retransmit parameters.
226 : *
227 : * @return The current Relay Retransmit parameters, or 0 if relay is not
228 : * supported.
229 : */
230 1 : uint8_t bt_mesh_relay_retransmit_get(void);
231 :
232 : /** @brief Enable or disable the GATT Proxy feature.
233 : *
234 : * Support for the GATT Proxy feature must be enabled through the
235 : * @c CONFIG_BT_MESH_GATT_PROXY configuration option.
236 : *
237 : * @note The GATT Proxy feature only controls a Proxy node's ability to relay
238 : * messages to the mesh network. A node that supports GATT Proxy will
239 : * still advertise Connectable Proxy beacons, even if the feature is
240 : * disabled. The Proxy feature can only be fully disabled through compile
241 : * time configuration.
242 : *
243 : * @param gatt_proxy New GATT Proxy state. Must be one of
244 : * @ref BT_MESH_FEATURE_ENABLED and
245 : * @ref BT_MESH_FEATURE_DISABLED.
246 : *
247 : * @retval 0 Successfully changed the GATT Proxy feature state.
248 : * @retval -ENOTSUP The GATT Proxy feature is not supported.
249 : * @retval -EINVAL Invalid parameter.
250 : * @retval -EALREADY Already in the given state.
251 : */
252 1 : int bt_mesh_gatt_proxy_set(enum bt_mesh_feat_state gatt_proxy);
253 :
254 : /** @brief Get the current GATT Proxy state.
255 : *
256 : * @returns The GATT Proxy feature state.
257 : */
258 1 : enum bt_mesh_feat_state bt_mesh_gatt_proxy_get(void);
259 :
260 : /** @brief Enable or disable the Private GATT Proxy feature.
261 : *
262 : * Support for the Private GATT Proxy feature must be enabled through the
263 : * @kconfig{CONFIG_BT_MESH_PRIV_BEACONS} and @kconfig{CONFIG_BT_MESH_GATT_PROXY}
264 : * configuration options.
265 : *
266 : * @param priv_gatt_proxy New Private GATT Proxy state. Must be one of
267 : * @ref BT_MESH_FEATURE_ENABLED and
268 : * @ref BT_MESH_FEATURE_DISABLED.
269 : *
270 : * @retval 0 Successfully changed the Private GATT Proxy feature state.
271 : * @retval -ENOTSUP The Private GATT Proxy feature is not supported.
272 : * @retval -EINVAL Invalid parameter.
273 : * @retval -EALREADY Already in the given state.
274 : */
275 1 : int bt_mesh_priv_gatt_proxy_set(enum bt_mesh_feat_state priv_gatt_proxy);
276 :
277 : /** @brief Get the current Private GATT Proxy state.
278 : *
279 : * @returns The Private GATT Proxy feature state.
280 : */
281 1 : enum bt_mesh_feat_state bt_mesh_priv_gatt_proxy_get(void);
282 :
283 : /** @brief Enable or disable the Friend feature.
284 : *
285 : * Any active friendships will be terminated immediately if the Friend feature
286 : * is disabled.
287 : *
288 : * Support for the Friend feature must be enabled through the
289 : * @c CONFIG_BT_MESH_FRIEND configuration option.
290 : *
291 : * @param friendship New Friend feature state. Must be one of
292 : * @ref BT_MESH_FEATURE_ENABLED and
293 : * @ref BT_MESH_FEATURE_DISABLED.
294 : *
295 : * @retval 0 Successfully changed the Friend feature state.
296 : * @retval -ENOTSUP The Friend feature is not supported.
297 : * @retval -EINVAL Invalid parameter.
298 : * @retval -EALREADY Already in the given state.
299 : */
300 1 : int bt_mesh_friend_set(enum bt_mesh_feat_state friendship);
301 :
302 : /** @brief Get the current Friend state.
303 : *
304 : * @returns The Friend feature state.
305 : */
306 1 : enum bt_mesh_feat_state bt_mesh_friend_get(void);
307 :
308 : /**
309 : * @brief Subnet Configuration
310 : * @defgroup bt_mesh_cfg_subnet Subnet Configuration
311 : * @{
312 : */
313 :
314 : /** @brief Add a Subnet.
315 : *
316 : * Adds a subnet with the given network index and network key to the list of
317 : * known Subnets. All messages sent on the given Subnet will be processed by
318 : * this node, and the node may send and receive Network Beacons on the given
319 : * Subnet.
320 : *
321 : * @param net_idx Network index.
322 : * @param key Root network key of the Subnet. All other keys are derived
323 : * from this.
324 : *
325 : * @retval STATUS_SUCCESS The Subnet was successfully added.
326 : * @retval STATUS_INSUFF_RESOURCES No room for this Subnet.
327 : * @retval STATUS_UNSPECIFIED The Subnet couldn't be created for some reason.
328 : */
329 1 : uint8_t bt_mesh_subnet_add(uint16_t net_idx, const uint8_t key[16]);
330 :
331 : /** @brief Update the given Subnet.
332 : *
333 : * Starts the Key Refresh procedure for this Subnet by adding a second set of
334 : * encryption keys. The Subnet will continue sending with the old key (but
335 : * receiving messages using both) until the Subnet enters Key Refresh phase 2.
336 : *
337 : * This allows a network configurator to replace old network and application
338 : * keys for the entire network, effectively removing access for all nodes that
339 : * aren't given the new keys.
340 : *
341 : * @param net_idx Network index.
342 : * @param key New root network key of the Subnet.
343 : *
344 : * @retval STATUS_SUCCESS The Subnet was updated with a second key.
345 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
346 : * @retval STATUS_IDX_ALREADY_STORED The @c key value is the same as the
347 : * current key.
348 : * @retval STATUS_CANNOT_UPDATE The Subnet cannot be updated for some reason.
349 : */
350 1 : uint8_t bt_mesh_subnet_update(uint16_t net_idx, const uint8_t key[16]);
351 :
352 : /** @brief Delete a Subnet.
353 : *
354 : * Removes the Subnet with the given network index from the node. The node will
355 : * stop sending Network Beacons with the given Subnet, and can no longer
356 : * process messages on this Subnet.
357 : *
358 : * All Applications bound to this Subnet are also deleted.
359 : *
360 : * @param net_idx Network index.
361 : *
362 : * @retval STATUS_SUCCESS The Subnet was deleted.
363 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
364 : */
365 1 : uint8_t bt_mesh_subnet_del(uint16_t net_idx);
366 :
367 : /** @brief Check whether a Subnet is known.
368 : *
369 : * @param net_idx Network index
370 : *
371 : * @return true if a Subnet with the given index exists, false otherwise.
372 : */
373 1 : bool bt_mesh_subnet_exists(uint16_t net_idx);
374 :
375 : /** @brief Set the Subnet's Key Refresh phase.
376 : *
377 : * The Key Refresh procedure is started by updating the Subnet keys through
378 : * @ref bt_mesh_subnet_update. This puts the Subnet in Key Refresh Phase 1.
379 : * Once all nodes have received the new Subnet key, Key Refresh Phase 2 can be
380 : * activated through this function to start transmitting with the new network
381 : * key. Finally, to revoke the old key, set the Key Refresh Phase to 3. This
382 : * removes the old keys from the node, and returns the Subnet back to normal
383 : * single-key operation with the new key set.
384 : *
385 : * @param net_idx Network index.
386 : * @param phase Pointer to the new Key Refresh phase. Will return the actual
387 : * Key Refresh phase after updating.
388 : *
389 : * @retval STATUS_SUCCESS The Key Refresh phase of the Subnet was successfully
390 : * changed.
391 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
392 : * @retval STATUS_CANNOT_UPDATE The given phase change is invalid.
393 : */
394 1 : uint8_t bt_mesh_subnet_kr_phase_set(uint16_t net_idx, uint8_t *phase);
395 :
396 : /** @brief Get the Subnet's Key Refresh phase.
397 : *
398 : * @param net_idx Network index.
399 : * @param phase Pointer to the Key Refresh variable to fill.
400 : *
401 : * @retval STATUS_SUCCESS Successfully populated the @c phase variable.
402 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
403 : */
404 1 : uint8_t bt_mesh_subnet_kr_phase_get(uint16_t net_idx, uint8_t *phase);
405 :
406 : /** @brief Set the Node Identity state of the Subnet.
407 : *
408 : * The Node Identity state of a Subnet determines whether the Subnet advertises
409 : * connectable Node Identity beacons for Proxy Clients to connect to.
410 : * Once started, the Node Identity beacon runs for 60 seconds, or until it is
411 : * stopped.
412 : *
413 : * This function serves the same purpose as @ref bt_mesh_proxy_identity_enable,
414 : * but only acts on a single Subnet.
415 : *
416 : * GATT Proxy support must be enabled through
417 : * @kconfig{CONFIG_BT_MESH_GATT_PROXY}.
418 : *
419 : * @param net_idx Network index.
420 : * @param node_id New Node Identity state, must be either @ref
421 : * BT_MESH_FEATURE_ENABLED or @ref BT_MESH_FEATURE_DISABLED.
422 : *
423 : * @retval STATUS_SUCCESS Successfully set the Node Identity state of the
424 : * Subnet.
425 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
426 : * @retval STATUS_FEAT_NOT_SUPP The Node Identity feature is not supported.
427 : * @retval STATUS_CANNOT_SET Couldn't set the Node Identity state.
428 : */
429 1 : uint8_t bt_mesh_subnet_node_id_set(uint16_t net_idx,
430 : enum bt_mesh_feat_state node_id);
431 :
432 : /** @brief Get the Node Identity state of the Subnet.
433 : *
434 : * @param net_idx Network index.
435 : * @param node_id Node Identity variable to fill.
436 : *
437 : * @retval STATUS_SUCCESS Successfully populated the @c node_id variable.
438 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
439 : */
440 1 : uint8_t bt_mesh_subnet_node_id_get(uint16_t net_idx,
441 : enum bt_mesh_feat_state *node_id);
442 :
443 : /** @brief Set the Private Node Identity state of the Subnet.
444 : *
445 : * The Private Node Identity state of a Subnet determines whether the Subnet
446 : * advertises connectable Private Node Identity beacons for Proxy Clients to
447 : * connect to. Once started, the Node Identity beacon runs for 60 seconds,
448 : * or until it is stopped.
449 : *
450 : * Private Node Identity can only be enabled if regular Node Identity is not
451 : * enabled for any subnet.
452 : *
453 : * GATT Proxy and Private Beacon support must be enabled through
454 : * @kconfig{CONFIG_BT_MESH_GATT_PROXY} and
455 : * @kconfig{CONFIG_BT_MESH_PRIV_BEACONS}.
456 : *
457 : * @param net_idx Network index.
458 : * @param priv_node_id New Private Node Identity state, must be either @ref
459 : * BT_MESH_FEATURE_ENABLED or @ref BT_MESH_FEATURE_DISABLED.
460 : *
461 : * @retval STATUS_SUCCESS Successfully set the Private Node Identity state of the Subnet.
462 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
463 : * @retval STATUS_FEAT_NOT_SUPP The Private Node Identity feature is not supported.
464 : * @retval STATUS_TEMP_STATE_CHG_FAIL The Private Node Identity state cannot be enabled, because
465 : * Node Identity state is already enabled.
466 : * @retval STATUS_CANNOT_SET Couldn't set the Private Node Identity state.
467 : */
468 1 : uint8_t bt_mesh_subnet_priv_node_id_set(uint16_t net_idx,
469 : enum bt_mesh_feat_state priv_node_id);
470 :
471 : /** @brief Get the Private Node Identity state of the Subnet.
472 : *
473 : * @param net_idx Network index.
474 : * @param priv_node_id Private Node Identity variable to fill.
475 : *
476 : * @retval STATUS_SUCCESS Successfully populated the @c priv_node_id variable.
477 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
478 : */
479 1 : uint8_t bt_mesh_subnet_priv_node_id_get(uint16_t net_idx,
480 : enum bt_mesh_feat_state *priv_node_id);
481 :
482 : /** @brief Get a list of all known Subnet indexes.
483 : *
484 : * Builds a list of all known Subnet indexes in the @c net_idxs array.
485 : * If the @c net_idxs array is smaller than the list of known Subnets, this
486 : * function fills all available entries and returns @c -ENOMEM. In this
487 : * case, the next @c max entries of the list can be read out by calling
488 : * @code
489 : * bt_mesh_subnets_get(list, max, max);
490 : * @endcode
491 : *
492 : * Note that any changes to the Subnet list between calls to this function
493 : * could change the order and number of entries in the list.
494 : *
495 : * @param net_idxs Array to fill.
496 : * @param max Max number of indexes to return.
497 : * @param skip Number of indexes to skip. Enables batched processing of the
498 : * list.
499 : *
500 : * @return The number of indexes added to the @c net_idxs array, or @c -ENOMEM
501 : * if the number of known Subnets exceeds the @c max parameter.
502 : */
503 1 : ssize_t bt_mesh_subnets_get(uint16_t net_idxs[], size_t max, off_t skip);
504 :
505 : /**
506 : * @}
507 : */
508 :
509 : /**
510 : * @brief Application Configuration
511 : * @defgroup bt_mesh_cfg_app Application Configuration
512 : * @{
513 : */
514 :
515 : /** @brief Add an Application key.
516 : *
517 : * Adds the Application with the given index to the list of known applications.
518 : * Allows the node to send and receive model messages encrypted with this
519 : * Application key.
520 : *
521 : * Every Application is bound to a specific Subnet. The node must know the
522 : * Subnet the Application is bound to before it can add the Application.
523 : *
524 : * @param app_idx Application index.
525 : * @param net_idx Network index the Application is bound to.
526 : * @param key Application key value.
527 : *
528 : * @retval STATUS_SUCCESS The Application was successfully added.
529 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
530 : * @retval STATUS_INSUFF_RESOURCES There's no room for storing this
531 : * Application.
532 : * @retval STATUS_INVALID_BINDING This AppIdx is already bound to another
533 : * Subnet.
534 : * @retval STATUS_IDX_ALREADY_STORED This AppIdx is already stored with a
535 : * different key value.
536 : * @retval STATUS_CANNOT_SET Cannot set the Application key for some reason.
537 : */
538 1 : uint8_t bt_mesh_app_key_add(uint16_t app_idx, uint16_t net_idx,
539 : const uint8_t key[16]);
540 :
541 : /** @brief Update an Application key.
542 : *
543 : * Update an Application with a second Application key, as part of the
544 : * Key Refresh procedure of the bound Subnet. The node will continue
545 : * transmitting with the old application key (but receiving on both) until the
546 : * Subnet enters Key Refresh phase 2. Once the Subnet enters Key Refresh phase
547 : * 3, the old application key will be deleted.
548 : *
549 : * @note The Application key can only be updated if the bound Subnet is in Key
550 : * Refresh phase 1.
551 : *
552 : * @param app_idx Application index.
553 : * @param net_idx Network index the Application is bound to, or
554 : * @ref BT_MESH_KEY_ANY to skip the binding check.
555 : * @param key New key value.
556 : *
557 : * @retval STATUS_SUCCESS The Application key was successfully updated.
558 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
559 : * @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx.
560 : * @retval STATUS_CANNOT_UPDATE The Application key cannot be updated for some
561 : * reason.
562 : * @retval STATUS_IDX_ALREADY_STORED This AppIdx is already updated with a
563 : * different key value.
564 : */
565 1 : uint8_t bt_mesh_app_key_update(uint16_t app_idx, uint16_t net_idx,
566 : const uint8_t key[16]);
567 :
568 : /** @brief Delete an Application key.
569 : *
570 : * All models bound to this application will remove this binding.
571 : * All models publishing with this application will stop publishing.
572 : *
573 : * @param app_idx Application index.
574 : * @param net_idx Network index.
575 : *
576 : * @retval STATUS_SUCCESS The Application key was successfully deleted.
577 : * @retval STATUS_INVALID_NETKEY The NetIdx is unknown.
578 : * @retval STATUS_INVALID_BINDING This AppIdx is not bound to the given NetIdx.
579 : */
580 1 : uint8_t bt_mesh_app_key_del(uint16_t app_idx, uint16_t net_idx);
581 :
582 : /** @brief Check if an Application key is known.
583 : *
584 : * @param app_idx Application index.
585 : *
586 : * @return true if the Application is known, false otherwise.
587 : */
588 1 : bool bt_mesh_app_key_exists(uint16_t app_idx);
589 :
590 : /** @brief Get a list of all known Application key indexes.
591 : *
592 : * Builds a list of all Application indexes for the given network index in the
593 : * @c app_idxs array. If the @c app_idxs array cannot fit all bound
594 : * Applications, this function fills all available entries and returns @c
595 : * -ENOMEM. In this case, the next @c max entries of the list can be read out
596 : * by calling
597 : * @code
598 : * bt_mesh_app_keys_get(net_idx, list, max, max);
599 : * @endcode
600 : *
601 : * Note that any changes to the Application key list between calls to this
602 : * function could change the order and number of entries in the list.
603 : *
604 : * @param net_idx Network Index to get the Applications of, or @ref
605 : * BT_MESH_KEY_ANY to get all Applications.
606 : * @param app_idxs Array to fill.
607 : * @param max Max number of indexes to return.
608 : * @param skip Number of indexes to skip. Enables batched processing of the
609 : * list.
610 : *
611 : * @return The number of indexes added to the @c app_idxs array, or @c -ENOMEM
612 : * if the number of known Applications exceeds the @c max parameter.
613 : */
614 1 : ssize_t bt_mesh_app_keys_get(uint16_t net_idx, uint16_t app_idxs[], size_t max,
615 : off_t skip);
616 :
617 : /**
618 : * @}
619 : */
620 :
621 : #ifdef __cplusplus
622 : }
623 : #endif
624 :
625 : /**
626 : * @}
627 : */
628 :
629 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_CFG_H_ */
|
