1 /** @file
2  *  @brief Bluetooth Mesh Profile APIs.
3  */
4 
5 /*
6  * Copyright (c) 2017 Intel Corporation
7  * Additional Copyright (c) 2018 Espressif Systems (Shanghai) PTE LTD
8  *
9  * SPDX-License-Identifier: Apache-2.0
10  */
11 #ifndef _BLE_MESH_MAIN_H_
12 #define _BLE_MESH_MAIN_H_
13 
14 #include "mesh_access.h"
15 
16 /**
17  * @brief Bluetooth Mesh Provisioning
18  * @defgroup bt_mesh_prov Bluetooth Mesh Provisioning
19  * @ingroup bt_mesh
20  * @{
21  */
22 
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26 
27 typedef enum {
28     BLE_MESH_NO_OUTPUT       = 0,
29     BLE_MESH_BLINK           = BIT(0),
30     BLE_MESH_BEEP            = BIT(1),
31     BLE_MESH_VIBRATE         = BIT(2),
32     BLE_MESH_DISPLAY_NUMBER  = BIT(3),
33     BLE_MESH_DISPLAY_STRING  = BIT(4),
34 } bt_mesh_output_action_t;
35 
36 typedef enum {
37     BLE_MESH_NO_INPUT      = 0,
38     BLE_MESH_PUSH          = BIT(0),
39     BLE_MESH_TWIST         = BIT(1),
40     BLE_MESH_ENTER_NUMBER  = BIT(2),
41     BLE_MESH_ENTER_STRING  = BIT(3),
42 } bt_mesh_input_action_t;
43 
44 typedef enum {
45     BLE_MESH_PROV_ADV   = BIT(0),
46     BLE_MESH_PROV_GATT  = BIT(1),
47 } bt_mesh_prov_bearer_t;
48 
49 typedef enum {
50     BLE_MESH_PROV_OOB_OTHER     = BIT(0),
51     BLE_MESH_PROV_OOB_URI       = BIT(1),
52     BLE_MESH_PROV_OOB_2D_CODE   = BIT(2),
53     BLE_MESH_PROV_OOB_BAR_CODE  = BIT(3),
54     BLE_MESH_PROV_OOB_NFC       = BIT(4),
55     BLE_MESH_PROV_OOB_NUMBER    = BIT(5),
56     BLE_MESH_PROV_OOB_STRING    = BIT(6),
57     /* 7 - 10 are reserved */
58     BLE_MESH_PROV_OOB_ON_BOX    = BIT(11),
59     BLE_MESH_PROV_OOB_IN_BOX    = BIT(12),
60     BLE_MESH_PROV_OOB_ON_PAPER  = BIT(13),
61     BLE_MESH_PROV_OOB_IN_MANUAL = BIT(14),
62     BLE_MESH_PROV_OOB_ON_DEV    = BIT(15),
63 } bt_mesh_prov_oob_info_t;
64 
65 #define BLE_MESH_PROV_STATIC_OOB_MAX_LEN    16
66 #define BLE_MESH_PROV_OUTPUT_OOB_MAX_LEN    8
67 #define BLE_MESH_PROV_INPUT_OOB_MAX_LEN     8
68 
69 /** Provisioning properties & capabilities. */
70 struct bt_mesh_prov {
71 #if CONFIG_BLE_MESH_NODE
72     /** The UUID that's used when advertising as unprovisioned */
73     const uint8_t *uuid;
74 
75     /** Optional URI. This will be advertised separately from the
76      *  unprovisioned beacon, however the unprovisioned beacon will
77      *  contain a hash of it so the two can be associated by the
78      *  provisioner.
79      */
80     const char *uri;
81 
82     /** Out of Band information field. */
83     bt_mesh_prov_oob_info_t oob_info;
84 
85     /** Flag indicates whether unprovisioned devices support OOB public key */
86     bool oob_pub_key;
87 
88     /** @brief Set device OOB public key.
89      *
90      *  This callback notifies the application to
91      *  set OOB public key & private key pair.
92      */
93     void (*oob_pub_key_cb)(void);
94 
95     /** Static OOB value */
96     const uint8_t *static_val;
97     /** Static OOB value length */
98     uint8_t        static_val_len;
99 
100     /** Maximum size of Output OOB supported */
101     uint8_t        output_size;
102     /** Supported Output OOB Actions */
103     uint16_t       output_actions;
104 
105     /* Maximum size of Input OOB supported */
106     uint8_t        input_size;
107     /** Supported Input OOB Actions */
108     uint16_t       input_actions;
109 
110     /** @brief Output of a number is requested.
111      *
112      *  This callback notifies the application to
113      *  output the given number using the given action.
114      *
115      *  @param act Action for outputting the number.
116      *  @param num Number to be out-put.
117      *
118      *  @return Zero on success or negative error code otherwise
119      */
120     int         (*output_number)(bt_mesh_output_action_t act, uint32_t num);
121 
122     /** @brief Output of a string is requested.
123      *
124      *  This callback notifies the application to
125      *  display the given string to the user.
126      *
127      *  @param str String to be displayed.
128      *
129      *  @return Zero on success or negative error code otherwise
130      */
131     int         (*output_string)(const char *str);
132 
133     /** @brief Input is requested.
134      *
135      *  This callback notifies the application to request
136      *  input from the user using the given action. The
137      *  requested input will either be a string or a number, and
138      *  the application needs to consequently call the
139      *  bt_mesh_input_string() or bt_mesh_input_number() functions
140      *  once the data has been acquired from the user.
141      *
142      *  @param act Action for inputting data.
143      *  @param num Maximum size of the in-put data.
144      *
145      *  @return Zero on success or negative error code otherwise
146      */
147     int         (*input)(bt_mesh_input_action_t act, uint8_t size);
148 
149     /** @brief Provisioning link has been opened.
150      *
151      *  This callback notifies the application that a provisioning
152      *  link has been opened on the given provisioning bearer.
153      *
154      *  @param bearer Provisioning bearer.
155      */
156     void        (*link_open)(bt_mesh_prov_bearer_t bearer);
157 
158     /** @brief Provisioning link has been closed.
159      *
160      *  This callback notifies the application that a provisioning
161      *  link has been closed on the given provisioning bearer.
162      *
163      *  @param bearer Provisioning bearer.
164      */
165     void        (*link_close)(bt_mesh_prov_bearer_t bearer);
166 
167     /** @brief Provisioning is complete.
168      *
169      *  This callback notifies the application that provisioning has
170      *  been successfully completed, and that the local node has been
171      *  assigned the specified NetKeyIndex and primary element address.
172      *
173      *  @param net_idx  NetKeyIndex given during provisioning.
174      *  @param net_key  NetKey given during provisioning.
175      *  @param addr     Primary element address.
176      *  @param flags    Key Refresh & IV Update flags
177      *  @param iv_index IV Index.
178      */
179     void        (*complete)(uint16_t net_idx, const uint8_t net_key[16], uint16_t addr, uint8_t flags, uint32_t iv_index);
180 
181     /** @brief Node has been reset.
182      *
183      *  This callback notifies the application that the local node
184      *  has been reset and needs to be reprovisioned. The node will
185      *  not automatically advertise as unprovisioned, rather the
186      *  bt_mesh_prov_enable() API needs to be called to enable
187      *  unprovisioned advertising on one or more provisioning bearers.
188      */
189     void        (*reset)(void);
190 #endif /* CONFIG_BLE_MESH_NODE */
191 
192 #if CONFIG_BLE_MESH_PROVISIONER
193     /* Provisioner device uuid */
194     const uint8_t *prov_uuid;
195 
196     /*
197      * Primary element address of the provisioner.
198      * No need to initialize it for fast provisioning.
199      */
200     const uint16_t prov_unicast_addr;
201 
202     /*
203      * Starting unicast address going to assigned.
204      * No need to initialize it for fast provisioning.
205      */
206     uint16_t prov_start_address;
207 
208     /* Attention timer contained in Provisioning Invite */
209     uint8_t  prov_attention;
210 
211     /* Provisioner provisioning Algorithm */
212     uint8_t  prov_algorithm;
213 
214     /* Provisioner public key oob */
215     uint8_t  prov_pub_key_oob;
216 
217     /** @brief Input is requested.
218      *
219      *  This callback notifies the application that it should
220      *  read device's public key with OOB
221      *
222      *  @param link_idx: The provisioning link index
223      *
224      *  @return Zero on success or negative error code otherwise
225      */
226     int  (*prov_pub_key_oob_cb)(uint8_t link_idx);
227 
228     /* Provisioner static oob value */
229     uint8_t *prov_static_oob_val;
230 
231     /* Provisioner static oob value length */
232     uint8_t  prov_static_oob_len;
233 
234     /** @brief Provisioner input a number read from device output
235      *
236      *  This callback notifies the application that it should
237      *  input the number given by the device.
238      *
239      *  @param method:   The OOB authentication method
240      *  @param act:      The output action of the device
241      *  @param size:     The output size of the device
242      *  @param link_idx: The provisioning link index
243      *
244      *  @return Zero on success or negative error code otherwise
245      */
246     int  (*prov_input_num)(uint8_t method, bt_mesh_output_action_t act, uint8_t size, uint8_t link_idx);
247 
248     /** @brief Provisioner output a number to the device
249      *
250      *  This callback notifies the application that it should
251      *  output the number to the device.
252      *
253      *  @param method:   The OOB authentication method
254      *  @param act:      The input action of the device
255      *  @param data:     The input number/string of the device
256      *  @param size:     The input size of the device
257      *  @param link_idx: The provisioning link index
258      *
259      *  @return Zero on success or negative error code otherwise
260      */
261     int  (*prov_output_num)(uint8_t method, bt_mesh_input_action_t act, void *data, uint8_t size, uint8_t link_idx);
262 
263     /*
264      * Key refresh and IV update flag.
265      * No need to initialize it for fast provisioning.
266      */
267     uint8_t  flags;
268 
269     /*
270      * IV index. No need to initialize it for fast provisioning.
271      */
272     uint32_t iv_index;
273 
274     /** @brief Provisioner has opened a provisioning link.
275      *
276      *  This callback notifies the application that a provisioning
277      *  link has been opened on the given provisioning bearer.
278      *
279      *  @param bearer Provisioning bearer.
280      */
281     void (*prov_link_open)(bt_mesh_prov_bearer_t bearer);
282 
283     /** @brief Provisioner has closed a provisioning link.
284      *
285      *  This callback notifies the application that a provisioning
286      *  link has been closed on the given provisioning bearer.
287      *
288      *  @param bearer Provisioning bearer.
289      *  @param reason Provisioning link close reason(disconnect reason)
290      */
291     void (*prov_link_close)(bt_mesh_prov_bearer_t bearer, uint8_t reason);
292 
293     /** @brief Provision one device is complete.
294      *
295      *  This callback notifies the application that provisioner has
296      *  successfully provisioned a device, and the node has been assigned
297      *  the specified NetKeyIndex and primary element address.
298      *
299      *  @param node_idx     Node index within the node(provisioned device) queue.
300      *  @param device_uuid  Provisioned device uuid pointer.
301      *  @param unicast_addr Provisioned device assigned unicast address.
302      *  @param element_num  Provisioned device element number.
303      *  @param netkey_idx   Provisioned device assigned netkey index.
304      */
305     void (*prov_complete)(uint16_t node_idx, const uint8_t device_uuid[16],
306                           uint16_t unicast_addr, uint8_t element_num,
307                           uint16_t netkey_idx);
308 #endif /* CONFIG_BLE_MESH_PROVISIONER */
309 };
310 
311 enum ble_mesh_role {
312     NODE = 0,
313     PROVISIONER,
314     FAST_PROV,
315     ROLE_NVAL,
316 };
317 
318 /* The following APIs are for BLE Mesh Node */
319 
320 /** @brief Provide provisioning input OOB string.
321  *
322  *  This is intended to be called after the bt_mesh_prov input callback
323  *  has been called with BLE_MESH_ENTER_STRING as the action.
324  *
325  *  @param str String.
326  *
327  *  @return Zero on success or (negative) error code otherwise.
328  */
329 int bt_mesh_input_string(const char *str);
330 
331 /** @brief Provide provisioning input OOB number.
332  *
333  *  This is intended to be called after the bt_mesh_prov input callback
334  *  has been called with BLE_MESH_ENTER_NUMBER as the action.
335  *
336  *  @param num Number.
337  *
338  *  @return Zero on success or (negative) error code otherwise.
339  */
340 int bt_mesh_input_number(uint32_t num);
341 
342 /** @brief Enable specific provisioning bearers
343  *
344  *  Enable one or more provisioning bearers.
345  *
346  *  @param Bit-wise OR of provisioning bearers.
347  *
348  *  @return Zero on success or (negative) error code otherwise.
349  */
350 int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers);
351 
352 /** @brief Disable specific provisioning bearers
353  *
354  *  Disable one or more provisioning bearers.
355  *
356  *  @param Bit-wise OR of provisioning bearers.
357  *
358  *  @return Zero on success or (negative) error code otherwise.
359  */
360 int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers);
361 
362 /* The following APIs are for BLE Mesh Provisioner */
363 
364 /** @brief Provide provisioning input OOB string.
365  *
366  *  This is intended to be called after the bt_mesh_prov input callback
367  *  has been called with BLE_MESH_ENTER_STRING as the action.
368  *
369  *  @param str String.
370  *
371  *  @return Zero on success or (negative) error code otherwise.
372  */
373 int bt_mesh_prov_input_string(const char *str);
374 
375 /** @brief Provide provisioning input OOB number.
376  *
377  *  This is intended to be called after the bt_mesh_prov input callback
378  *  has been called with BLE_MESH_ENTER_NUMBER as the action.
379  *
380  *  @param num Number.
381  *
382  *  @return Zero on success or (negative) error code otherwise.
383  */
384 int bt_mesh_prov_input_number(uint32_t num);
385 
386 /** @brief Enable specific provisioning bearers
387  *
388  *  Enable one or more provisioning bearers.
389  *
390  *  @param bearers Bit-wise OR of provisioning bearers.
391  *
392  *  @return Zero on success or (negative) error code otherwise.
393  */
394 int bt_mesh_provisioner_enable(bt_mesh_prov_bearer_t bearers);
395 
396 /** @brief Disable specific provisioning bearers
397  *
398  *  Disable one or more provisioning bearers.
399  *
400  *  @param bearers Bit-wise OR of provisioning bearers.
401  *
402  *  @return Zero on success or (negative) error code otherwise.
403  */
404 int bt_mesh_provisioner_disable(bt_mesh_prov_bearer_t bearers);
405 
406 /**
407  * @}
408  */
409 
410 /**
411  * @brief Bluetooth Mesh
412  * @defgroup bt_mesh Bluetooth Mesh
413  * @ingroup bluetooth
414  * @{
415  */
416 
417 /* Primary Network Key index */
418 #define BLE_MESH_NET_PRIMARY                 0x000
419 
420 #define BLE_MESH_RELAY_DISABLED              0x00
421 #define BLE_MESH_RELAY_ENABLED               0x01
422 #define BLE_MESH_RELAY_NOT_SUPPORTED         0x02
423 
424 #define BLE_MESH_BEACON_DISABLED             0x00
425 #define BLE_MESH_BEACON_ENABLED              0x01
426 
427 #define BLE_MESH_GATT_PROXY_DISABLED         0x00
428 #define BLE_MESH_GATT_PROXY_ENABLED          0x01
429 #define BLE_MESH_GATT_PROXY_NOT_SUPPORTED    0x02
430 
431 #define BLE_MESH_FRIEND_DISABLED             0x00
432 #define BLE_MESH_FRIEND_ENABLED              0x01
433 #define BLE_MESH_FRIEND_NOT_SUPPORTED        0x02
434 
435 #define BLE_MESH_NODE_IDENTITY_STOPPED       0x00
436 #define BLE_MESH_NODE_IDENTITY_RUNNING       0x01
437 #define BLE_MESH_NODE_IDENTITY_NOT_SUPPORTED 0x02
438 
439 /* Features */
440 #define BLE_MESH_FEAT_RELAY                  BIT(0)
441 #define BLE_MESH_FEAT_PROXY                  BIT(1)
442 #define BLE_MESH_FEAT_FRIEND                 BIT(2)
443 #define BLE_MESH_FEAT_LOW_POWER              BIT(3)
444 #define BLE_MESH_FEAT_SUPPORTED              (BLE_MESH_FEAT_RELAY |     \
445                                               BLE_MESH_FEAT_PROXY |     \
446                                               BLE_MESH_FEAT_FRIEND |    \
447                                               BLE_MESH_FEAT_LOW_POWER)
448 
449 /** @brief Check if the mesh stack is initialized.
450  *
451  *  @return true - yes, false - no.
452  */
453 bool bt_mesh_is_initialized(void);
454 
455 /** @brief Initialize Mesh support
456  *
457  *  After calling this API, the node will not automatically advertise as
458  *  unprovisioned, rather the bt_mesh_prov_enable() API needs to be called
459  *  to enable unprovisioned advertising on one or more provisioning bearers.
460  *
461  *  @param prov Node provisioning information.
462  *  @param comp Node Composition.
463  *
464  *  @return Zero on success or (negative) error code otherwise.
465  */
466 int bt_mesh_init(const struct bt_mesh_prov *prov,
467                  const struct bt_mesh_comp *comp);
468 
469 /* BLE Mesh deinit parameters */
470 struct bt_mesh_deinit_param {
471     bool erase; /* Indicate if erasing flash when deinit mesh stack */
472 };
473 
474 /** @brief De-initialize Mesh support
475  *
476  *  @param param BLE Mesh deinit parameters.
477  *
478  *  @return Zero on success or (negative) error code otherwise.
479  */
480 int bt_mesh_deinit(struct bt_mesh_deinit_param *param);
481 
482 /** @brief Reset the state of the local Mesh node.
483  *
484  *  Resets the state of the node, which means that it needs to be
485  *  reprovisioned to become an active node in a Mesh network again.
486  *
487  *  After calling this API, the node will not automatically advertise as
488  *  unprovisioned, rather the bt_mesh_prov_enable() API needs to be called
489  *  to enable unprovisioned advertising on one or more provisioning bearers.
490  *
491  */
492 void bt_mesh_node_reset(void);
493 
494 /** @brief Suspend the Mesh network temporarily.
495  *
496  *  This API can be used for power saving purposes, but the user should be
497  *  aware that leaving the local node suspended for a long period of time
498  *  may cause it to become permanently disconnected from the Mesh network.
499  *  If at all possible, the Friendship feature should be used instead, to
500  *  make the node into a Low Power Node.
501  *
502  *  @return 0 on success, or (negative) error code on failure.
503  */
504 int bt_mesh_suspend(void);
505 
506 /** @brief Resume a suspended Mesh network.
507  *
508  *  This API resumes the local node, after it has been suspended using the
509  *  bt_mesh_suspend() API.
510  *
511  *  @return 0 on success, or (negative) error code on failure.
512  */
513 int bt_mesh_resume(void);
514 
515 /** @brief Provision the local Mesh Node.
516  *
517  *  This API should normally not be used directly by the application. The
518  *  only exception is for testing purposes where manual provisioning is
519  *  desired without an actual external provisioner.
520  *
521  *  @param net_key  Network Key
522  *  @param net_idx  Network Key Index
523  *  @param flags    Provisioning Flags
524  *  @param iv_index IV Index
525  *  @param addr     Primary element address
526  *  @param dev_key  Device Key
527  *
528  *  @return Zero on success or (negative) error code otherwise.
529  */
530 int bt_mesh_provision(const uint8_t net_key[16], uint16_t net_idx,
531                       uint8_t flags, uint32_t iv_index, uint16_t addr,
532                       const uint8_t dev_key[16]);
533 
534 /** @brief Check if the device is an unprovisioned device
535  *         and will act as a node once provisioned.
536  *
537  *  @return true - yes, false - no.
538  */
539 bool bt_mesh_is_node(void);
540 
541 /** @brief Check if the local node has been provisioned.
542  *
543  *  This API can be used to check if the local node has been provisioned
544  *  or not. It can e.g. be helpful to determine if there was a stored
545  *  network in flash, i.e. if the network was restored after calling
546  *  settings_load().
547  *
548  *  @return True if the node is provisioned. False otherwise.
549  */
550 bool bt_mesh_is_provisioned(void);
551 
552 /** @brief Check if the device is a Provisioner.
553  *
554  *  @return true - yes, false - no.
555  */
556 bool bt_mesh_is_provisioner(void);
557 
558 /** @brief Check if the Provisioner is enabled
559  *
560  *  @return true - enabled, false - disabled.
561  */
562 bool bt_mesh_is_provisioner_en(void);
563 
564 /** @brief Toggle the IV Update test mode
565  *
566  *  This API is only available if the IV Update test mode has been enabled
567  *  in Kconfig. It is needed for passing most of the IV Update qualification
568  *  test cases.
569  *
570  *  @param enable true to enable IV Update test mode, false to disable it.
571  */
572 void bt_mesh_iv_update_test(bool enable);
573 
574 /** @brief Toggle the IV Update state
575  *
576  *  This API is only available if the IV Update test mode has been enabled
577  *  in Kconfig. It is needed for passing most of the IV Update qualification
578  *  test cases.
579  *
580  *  @return true if IV Update In Progress state was entered, false otherwise.
581  */
582 bool bt_mesh_iv_update(void);
583 
584 /** @brief Toggle the Low Power feature of the local device
585  *
586  *  Enables or disables the Low Power feature of the local device. This is
587  *  exposed as a run-time feature, since the device might want to change
588  *  this e.g. based on being plugged into a stable power source or running
589  *  from a battery power source.
590  *
591  *  @param enable  true to enable LPN functionality, false to disable it.
592  *  @param force   when disable LPN functionality, use this flag to indicate
593  *                 whether directly clear corresponding information or sending
594  *                 friend clear to disable it.
595  *
596  *  @return Zero on success or (negative) error code otherwise.
597  */
598 int bt_mesh_lpn_set(bool enable, bool force);
599 
600 /** @brief Send out a Friend Poll message.
601  *
602  *  Send a Friend Poll message to the Friend of this node. If there is no
603  *  established Friendship the function will return an error.
604  *
605  *  @return Zero on success or (negative) error code otherwise.
606  */
607 int bt_mesh_lpn_poll(void);
608 
609 /** @brief Register a callback for Friendship changes.
610  *
611  *  Registers a callback that will be called whenever Friendship gets
612  *  established or is lost.
613  *
614  *  @param cb Function to call when the Friendship status changes.
615  */
616 void bt_mesh_lpn_set_cb(void (*cb)(uint16_t friend_addr, bool established));
617 
618 /** @brief Register a callback for Friendship changes of friend node.
619  *
620  *  Registers a callback that will be called whenever Friendship gets
621  *  established or is terminated.
622  *
623  *  @param cb Function to call when the Friendship status of friend node changes.
624  */
625 void bt_mesh_friend_set_cb(void (*cb)(bool establish, uint16_t lpn_addr, uint8_t reason));
626 
627 #ifdef __cplusplus
628 }
629 #endif
630 
631 /**
632  * @}
633  */
634 
635 #endif /* _BLE_MESH_MAIN_H_ */
636