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
