1 /*
2  * SPDX-FileCopyrightText: 2017-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ESP_BLE_MESH_BLE_API_H_
8 #define _ESP_BLE_MESH_BLE_API_H_
9 
10 #include "esp_ble_mesh_defs.h"
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 /** This enum value is the event of BLE operations */
17 typedef enum {
18     ESP_BLE_MESH_START_BLE_ADVERTISING_COMP_EVT, /*!< Start BLE advertising completion event */
19     ESP_BLE_MESH_STOP_BLE_ADVERTISING_COMP_EVT,  /*!< Stop BLE advertising completion event */
20     ESP_BLE_MESH_START_BLE_SCANNING_COMP_EVT,    /*!< Start BLE scanning completion event */
21     ESP_BLE_MESH_STOP_BLE_SCANNING_COMP_EVT,     /*!< Stop BLE scanning completion event */
22     ESP_BLE_MESH_SCAN_BLE_ADVERTISING_PKT_EVT,   /*!< Scanning BLE advertising packets event */
23     ESP_BLE_MESH_BLE_EVT_MAX,
24 } esp_ble_mesh_ble_cb_event_t;
25 
26 /** BLE operation callback parameters */
27 typedef union {
28     /**
29      * @brief ESP_BLE_MESH_START_BLE_ADVERTISING_COMP_EVT
30      */
31     struct {
32         int err_code;             /*!< Indicate the result of starting BLE advertising */
33         uint8_t index;            /*!< Index of the BLE advertising */
34     } start_ble_advertising_comp; /*!< Event parameters of ESP_BLE_MESH_START_BLE_ADVERTISING_COMP_EVT */
35     /**
36      * @brief ESP_BLE_MESH_STOP_BLE_ADVERTISING_COMP_EVT
37      */
38     struct {
39         int err_code;            /*!< Indicate the result of stopping BLE advertising */
40         uint8_t index;           /*!< Index of the BLE advertising */
41     } stop_ble_advertising_comp; /*!< Event parameters of ESP_BLE_MESH_STOP_BLE_ADVERTISING_COMP_EVT */
42     /**
43      * @brief ESP_BLE_MESH_START_BLE_SCANNING_COMP_EVT
44      */
45     struct {
46         int err_code;      /*!< Indicate the result of starting BLE scanning */
47     } start_ble_scan_comp; /*!< Event parameters of ESP_BLE_MESH_START_BLE_SCANNING_COMP_EVT */
48     /**
49      * @brief ESP_BLE_MESH_STOP_BLE_SCANNING_COMP_EVT
50      */
51     struct {
52         int err_code;     /*!< Indicate the result of stopping BLE scanning */
53     } stop_ble_scan_comp; /*!< Event parameters of ESP_BLE_MESH_STOP_BLE_SCANNING_COMP_EVT */
54     /**
55      * @brief ESP_BLE_MESH_SCAN_BLE_ADVERTISING_PKT_EVT
56      */
57     struct {
58         uint8_t  addr[6];   /*!< Device address */
59         uint8_t  addr_type; /*!< Device address type */
60         uint8_t  adv_type;  /*!< Advertising data type */
61         uint8_t *data;      /*!< Advertising data */
62         uint16_t length;    /*!< Advertising data length */
63         int8_t   rssi;      /*!< RSSI of the advertising packet */
64     } scan_ble_adv_pkt;     /*!< Event parameters of ESP_BLE_MESH_SCAN_BLE_ADVERTISING_PKT_EVT */
65 } esp_ble_mesh_ble_cb_param_t;
66 
67 /**
68  * @brief   BLE scanning callback function type
69  *
70  * @param   event: BLE scanning callback event type
71  * @param   param: BLE scanning callback parameter
72  */
73 typedef void (* esp_ble_mesh_ble_cb_t)(esp_ble_mesh_ble_cb_event_t event,
74                                        esp_ble_mesh_ble_cb_param_t *param);
75 
76 /**
77  * @brief       Register BLE scanning callback.
78  *
79  * @param[in]   callback: Pointer to the BLE scaning callback function.
80  *
81  * @return      ESP_OK on success or error code otherwise.
82  *
83  */
84 esp_err_t esp_ble_mesh_register_ble_callback(esp_ble_mesh_ble_cb_t callback);
85 
86 /** Count for sending BLE advertising packet infinitely */
87 #define ESP_BLE_MESH_BLE_ADV_INFINITE   0xFFFF
88 
89 /*!< This enum value is the priority of BLE advertising packet */
90 typedef enum {
91     ESP_BLE_MESH_BLE_ADV_PRIO_LOW,
92     ESP_BLE_MESH_BLE_ADV_PRIO_HIGH,
93 } esp_ble_mesh_ble_adv_priority_t;
94 
95 /** Context of BLE advertising parameters. */
96 typedef struct {
97     uint16_t interval;               /*!< BLE advertising interval */
98     uint8_t  adv_type;               /*!< BLE advertising type */
99     uint8_t  own_addr_type;          /*!< Own address type */
100     uint8_t  peer_addr_type;         /*!< Peer address type */
101     uint8_t  peer_addr[BD_ADDR_LEN]; /*!< Peer address */
102     uint16_t duration;               /*!< Duration is milliseconds */
103     uint16_t period;                 /*!< Period in milliseconds */
104     uint16_t count;                  /*!< Number of advertising duration */
105     uint8_t  priority:2;             /*!< Priority of BLE advertising packet */
106 } esp_ble_mesh_ble_adv_param_t;
107 
108 /** Context of BLE advertising data. */
109 typedef struct {
110     uint8_t adv_data_len;      /*!< Advertising data length */
111     uint8_t adv_data[31];      /*!< Advertising data */
112     uint8_t scan_rsp_data_len; /*!< Scan response data length */
113     uint8_t scan_rsp_data[31]; /*!< Scan response data */
114 } esp_ble_mesh_ble_adv_data_t;
115 
116 /**
117  * @brief         This function is called to start BLE advertising with the corresponding data
118  *                and parameters while BLE Mesh is working at the same time.
119  *
120  * @note          1. When this function is called, the BLE advertising packet will be posted to
121  *                the BLE mesh adv queue in the mesh stack and waited to be sent.
122  *                2. In the BLE advertising parameters, the "duration" means the time used for
123  *                sending the BLE advertising packet each time, it shall not be smaller than the
124  *                advertising interval. When the packet is sent successfully, it will be posted
125  *                to the adv queue again after the "period" time if the "count" is bigger than 0.
126  *                The "count" means how many durations the packet will be sent after it is sent
127  *                successfully for the first time. And if the "count" is set to 0xFFFF, which
128  *                means the packet will be sent infinitely.
129  *                3. The "priority" means the priority of BLE advertising packet compared with
130  *                BLE Mesh packets. Currently two options (i.e. low/high) are provided. If the
131  *                "priority" is high, the BLE advertising packet will be posted to the front of
132  *                adv queue. Otherwise it will be posted to the back of adv queue.
133  *
134  * @param[in]     param: Pointer to the BLE advertising parameters
135  * @param[in]     data:  Pointer to the BLE advertising data and scan response data
136  *
137  * @return        ESP_OK on success or error code otherwise.
138  *
139  */
140 esp_err_t esp_ble_mesh_start_ble_advertising(const esp_ble_mesh_ble_adv_param_t *param,
141                                              const esp_ble_mesh_ble_adv_data_t *data);
142 
143 /**
144  * @brief         This function is called to stop BLE advertising with the corresponding index.
145  *
146  * @param[in]     index: Index of BLE advertising
147  *
148  * @return        ESP_OK on success or error code otherwise.
149  *
150  */
151 esp_err_t esp_ble_mesh_stop_ble_advertising(uint8_t index);
152 
153 /** Context of BLE scanning parameters. */
154 typedef struct {
155     uint32_t duration; /*!< Duration used to scan normal BLE advertising packets */
156 } esp_ble_mesh_ble_scan_param_t;
157 
158 /**
159  * @brief         This function is called to start scanning normal BLE advertising packets
160  *                and notifying the packets to the application layer.
161  *
162  * @param[in]     param: Pointer to the BLE scanning parameters
163  *
164  * @return        ESP_OK on success or error code otherwise.
165  *
166  */
167 esp_err_t esp_ble_mesh_start_ble_scanning(esp_ble_mesh_ble_scan_param_t *param);
168 
169 /**
170  * @brief         This function is called to stop notifying normal BLE advertising packets
171  *                to the application layer.
172  *
173  * @return        ESP_OK on success or error code otherwise.
174  *
175  */
176 esp_err_t esp_ble_mesh_stop_ble_scanning(void);
177 
178 #ifdef __cplusplus
179 }
180 #endif
181 
182 #endif /* _ESP_BLE_MESH_BLE_API_H_ */
183