ble.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble.h
5 *
6 * @brief include all ble sdk header files
7 *
8 ****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37
38 /**
39 * @addtogroup BLE
40 * @{
41 */
42
43 /**
44 @addtogroup BLE_COMMEN BLE Common
45 @{
46 @brief BLE Common interface.
47 */
48
49 #ifndef __BLE_H__
50 #define __BLE_H__
51
52 #include "ble_att.h"
53 #include "ble_error.h"
54 #include "ble_gapc.h"
55 #include "ble_gapm.h"
56 #include "ble_gatt.h"
57 #include "ble_gattc.h"
58 #include "ble_gatts.h"
59 #include "ble_l2cap.h"
60 #include "ble_prf.h"
61 #include "ble_sec.h"
62
63 #include <stdio.h>
64
65 /** @addtogroup BLE_COMMEN_ENUM Enumerations
66 * @{
67 */
68 /**
69 * @brief RF TX mode.
70 */
71 typedef enum
72 {
73 BLE_RF_TX_MODE_INVALID = 0,
74 BLE_RF_TX_MODE_LP_MODE = 1,
75 BLE_RF_TX_MODE_ULP_MODE = 2,
76 } ble_rf_tx_mode_t;
77
78 /**
79 * @brief The resistance value (ohm) of the RF match circuit.
80 */
81 typedef enum
82 {
83 BLE_RF_MATCH_CIRCUIT_25OHM = 25,
84 BLE_RF_MATCH_CIRCUIT_100OHM = 100,
85 } ble_rf_match_circuit_t;
86
87 /** @} */
88
89 /** @addtogroup BLE_COMMEN_STRUCTURES Structures
90 * @{
91 */
92 /**@brief The app callbacks for GAP, GATT, SM and L2CAP. */
93 typedef struct
94 {
95 app_ble_init_cmp_cb_t app_ble_init_cmp_callback; /**< Callback function for BLE initialization completed */
96 gap_cb_fun_t *app_gap_callbacks; /**< Callback function for GAP */
97 const gatt_common_cb_fun_t *app_gatt_common_callback; /**< Callback function for GATT common */
98 const gattc_cb_fun_t *app_gattc_callback; /**< Callback function for GATT Client */
99 sec_cb_fun_t *app_sec_callback; /**< Callback function for SM*/
100 }app_callback_t;
101
102 /**@brief The table contains the pointers to four arrays which are used
103 * as heap memory by BLE stack in ROM. The size of four arrays depends on
104 * the number of connections and the number of attributes of profiles. */
105 typedef struct
106 {
107 uint32_t *env_ret; /**< Pointer to the array for environment heap */
108 uint32_t *db_ret; /**< Pointer to the array for ATT DB heap */
109 uint32_t *msg_ret; /**< Pointer to the array for message heap */
110 uint32_t *non_ret; /**< Pointer to the array for non-retention heap */
111 uint16_t env_ret_size; /**< The size of the array for environment heap */
112 uint16_t db_ret_size; /**< The size of the array for ATT DB heap */
113 uint16_t msg_ret_size; /**< The size of the array for message heap */
114 uint16_t non_ret_size; /**< The size of the array for non-retention heap */
115 uint8_t *prf_buf; /**< Pointer to the array for profile heap */
116 uint32_t buf_size; /**< The size of the array for profile heap */
117 uint8_t *bm_buf; /**< Pointer to the array for bond manager heap */
118 uint32_t bm_size; /**< The size of the array for bond manager heap */
119 uint8_t *conn_buf; /**< Pointer to the array for connection heap */
120 uint32_t conn_size; /**< The size of the array for connection heap */
121 }stack_heaps_table_t;
122
123 /**@brief The function pointers for HCI UART. */
124 typedef struct
125 {
126 void (*init)(void); /**< Initialize UART. */
127 void (*flow_on)(void); /**< Flow control on. */
128 bool (*flow_off)(void); /**< Flow control off. */
129 void (*finish_transfers)(void); /**< Finish the current transferring. */
130 void (*read)(uint8_t *bufptr, uint32_t size, void (*callback) (void*, uint8_t), void* dummy); /**< Read data. */
131 void (*write)(uint8_t *bufptr, uint32_t size, void (*callback) (void*, uint8_t), void* dummy); /**< Write data. */
132 } hci_uart_call_t;
133 /** @} */
134
135 /** @addtogroup BLE_COMMEN_TYPEDEF Typedefs
136 * @{
137 */
138
139 /**@brief The BLE sync event callback. */
140 typedef void (*ble_sync_evt_cb_t)(uint32_t sync_cnt, uint16_t sync_period);
141 /** @} */
142
143 /** @addtogroup BLE_COMMEN_FUNCTIONS Functions
144 * @{ */
145 /**
146 *****************************************************************************************
147 * @brief Initialize BEL Stack.
148 *
149 * @param[in] p_app_callback: Pointer to the structure of app callbacks.
150 * @param[in] p_heaps_table: Pointer to the BLE stack heaps table.
151 *****************************************************************************************
152 */
153 void ble_stack_init(app_callback_t *p_app_callback, stack_heaps_table_t *p_heaps_table);
154
155 /**
156 *****************************************************************************************
157 * @brief Register UART instance for HCI.
158 *
159 * @param[in] id: Instance index.
160 * @param[in] api: Pointer to the struct of function pointers for HCI UART.
161 *****************************************************************************************
162 */
163 void ble_hci_uart_register(uint8_t id, hci_uart_call_t *api);
164
165 /**
166 *****************************************************************************************
167 * @brief Register BLE idle time notification callback function.
168 *
169 * @param[in] callback: function pointer of BLE idle time notification function.
170 * @note param[in] of callback: hs - the idle time of BLE in half slot (312.5μs).
171 * Callback will be called by BLE ISR to notify the rest idle time if there are some BLE activities.
172 * It should be realized as simlpe as you can.
173 * It's not suitable for ISO activities.
174 *****************************************************************************************
175 */
176 void ble_idle_time_notify_cb_register(void (*callback)(uint32_t hs));
177
178 /**
179 *****************************************************************************************
180 * @brief Register BLE activity start notification callback function.
181 *
182 * @param[in] callback: function pointer of BLE activity start notification function.
183 * @note param[in] of callback: e_role - the role of activity, @ref gap_activity_role_t for possible roles.
184 * param[in] of callback: index - The index parameter is interpreted by role.
185 * If role is @ref GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising.
186 * If role is @ref GAP_ACTIVITY_ROLE_CON, it's the index of Connection.
187 * For all other roles, it should be ignored.
188 * Callback will be called by BLE ISR when the BLE activity starts every time.
189 * It should be realized as simlpe as you can.
190 * Notice: You must define the start callback in the RAM space to avoid hardfault.
191 * It's not suitable for ISO activities.
192 *****************************************************************************************
193 */
194 void ble_activity_start_notify_cb_register(void (*callback)(gap_activity_role_t e_role, uint8_t index));
195
196 /**
197 *****************************************************************************************
198 * @brief Register BLE activity end notification callback function.
199 *
200 * @param[in] callback: function pointer of BLE activity end notification function.
201 * @note param[in] of callback: e_role - the role of activity, @ref gap_activity_role_t for possible roles.
202 * param[in] of callback: index - The index parameter is interpreted by role.
203 * If role is @ref GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising.
204 * If role is @ref GAP_ACTIVITY_ROLE_CON, it's the index of Connection.
205 * For all other roles, it should be ignored.
206 * Callback will be called by BLE ISR when the BLE activity ends every time.
207 * It should be realized as simlpe as you can. You'd better to define it in the RAM space
208 * It's not suitable for ISO activities.
209 *****************************************************************************************
210 */
211 void ble_activity_end_notify_cb_register(void (*callback)(gap_activity_role_t e_role, uint8_t index));
212
213 /**
214 *****************************************************************************************
215 * @brief Create sync source.
216 *
217 * @param[in] period: Period of sync source.
218 *
219 * @return SDK_ERR_DISALLOWED: Create sync source fail.
220 * SDK_SUCCESS: Create sync source successfully.
221 *****************************************************************************************
222 */
223 uint16_t ble_sync_source_create(uint16_t period);
224
225 /**
226 *****************************************************************************************
227 * @brief Register sync event callback.
228 *
229 * @param[in] sync_evt_cb: Sync event callback.
230 *
231 * @return SDK_ERR_POINTER_NULL: Pointer to sync event callback is NULL.
232 * SDK_SUCCESS: Register successfully.
233 *****************************************************************************************
234 */
235 uint16_t ble_sync_evt_cb_register(ble_sync_evt_cb_t sync_evt_cb);
236
237 /**
238 *****************************************************************************************
239 * @brief Distribute sync source.
240 *
241 * @param[in] conn_idx: The connection index.
242 *
243 * @return SDK_ERR_INVALID_CONN_IDX: Invalid connect index.
244 * SDK_ERR_DISALLOWED: Distribute is disallowed.
245 * SDK_SUCCESS: Distribute successfully.
246 *****************************************************************************************
247 */
248 uint16_t ble_sync_source_distribute(uint8_t conn_idx);
249
250 /**
251 *****************************************************************************************
252 * @brief Destroy sync source.
253 *
254 * @return SDK_SUCCESS: Destroy successfully.
255 *****************************************************************************************
256 */
257 uint16_t ble_sync_source_destroy(void);
258
259 /**
260 *****************************************************************************************
261 * @brief Change the RF TX mode of LP or ULP.
262 *
263 * @param[in] e_rf_tx_mode: Refer to @ref ble_rf_tx_mode_t.
264 * BLE_RF_TX_MODE_LP_MODE: LP mode.
265 * BLE_RF_TX_MODE_ULP_MODE: ULP mode.
266 * Others: invalid mode.
267 *
268 * @note This function should be called before BLE stack init.
269 *
270 * @return SDK_SUCCESS: Successfully set Tx mode.
271 * SDK_ERR_DISALLOWED: Failed to set Tx mode.
272 *****************************************************************************************
273 */
274 uint8_t ble_rf_tx_mode_set(ble_rf_tx_mode_t e_rf_tx_mode);
275
276 /**
277 *****************************************************************************************
278 * @brief Get the RF TX mode of LP or ULP.
279 *
280 * @return BLE_RF_TX_MODE_LP_MODE: LP Mode.
281 * BLE_RF_TX_MODE_ULP_MODE: ULP Mode.
282 * Others: Fail.
283 *****************************************************************************************
284 */
285 ble_rf_tx_mode_t ble_rf_tx_mode_get(void);
286
287 /**
288 *****************************************************************************************
289 * @brief Set the resistance value of the RF match circuit (unit: ohm).
290 *
291 * @note This function should be called before BLE stack init.
292 *
293 * @param[in] e_ohm: The resistance value (ohm) of the RF match circuit according to the board.
294 * BLE_RF_MATCH_CIRCUIT_25OHM: 25 ohm.
295 * BLE_RF_MATCH_CIRCUIT_100OHM: 100 ohm.
296 * Others: invalid.
297 *****************************************************************************************
298 */
299 void ble_rf_match_circuit_set(ble_rf_match_circuit_t e_ohm);
300
301 /**
302 *****************************************************************************************
303 * @brief Get the resistance value of the RF match circuit (unit: ohm).
304 *
305 * @return The resistance value (ohm) of the RF match circuit according to the board (ohm).
306 * BLE_RF_MATCH_CIRCUIT_25OHM: 25 ohm.
307 * BLE_RF_MATCH_CIRCUIT_100OHM: 100 ohm.
308 * Others: invalid.
309 *****************************************************************************************
310 */
311 ble_rf_match_circuit_t ble_rf_match_circuit_get(void);
312
313 /**
314 *****************************************************************************************
315 * @brief Generate a signal carrier wave.
316 *
317 * @param[in] channel: 0~39 channel, 2402~2480 Mhz.
318 *
319 *****************************************************************************************
320 */
321 void send_signal_carrier_wave(uint8_t channel);
322
323 /** @} */
324 #endif
325 /** @} */
326 /** @} */
ble_sync_source_distribute
uint16_t ble_sync_source_distribute(uint8_t conn_idx)
Distribute sync source.
ble_sync_source_destroy
uint16_t ble_sync_source_destroy(void)
Destroy sync source.
hci_uart_call_t
The function pointers for HCI UART.
Definition: ble.h:125
ble_activity_end_notify_cb_register
void ble_activity_end_notify_cb_register(void(*callback)(gap_activity_role_t e_role, uint8_t index))
Register BLE activity end notification callback function.
ble_sync_evt_cb_register
uint16_t ble_sync_evt_cb_register(ble_sync_evt_cb_t sync_evt_cb)
Register sync event callback.
gattc_cb_fun_t
GATTC Event callback Structures.
Definition: ble_gattc.h:293
stack_heaps_table_t::prf_buf
uint8_t * prf_buf
Pointer to the array for profile heap.
Definition: ble.h:115
ble_sync_source_create
uint16_t ble_sync_source_create(uint16_t period)
Create sync source.
stack_heaps_table_t::msg_ret_size
uint16_t msg_ret_size
The size of the array for message heap.
Definition: ble.h:113
app_callback_t::app_gatt_common_callback
const gatt_common_cb_fun_t * app_gatt_common_callback
Callback function for GATT common.
Definition: ble.h:97
app_callback_t::app_gattc_callback
const gattc_cb_fun_t * app_gattc_callback
Callback function for GATT Client.
Definition: ble.h:98
ble_gatts.h
BLE GATTS API.
ble_rf_match_circuit_t
ble_rf_match_circuit_t
The resistance value (ohm) of the RF match circuit.
Definition: ble.h:82
app_ble_init_cmp_cb_t
void(* app_ble_init_cmp_cb_t)(void)
BLE initialization completed callback function for application.
Definition: ble_gapc.h:496
stack_heaps_table_t::conn_size
uint32_t conn_size
The size of the array for connection heap.
Definition: ble.h:120
stack_heaps_table_t::msg_ret
uint32_t * msg_ret
Pointer to the array for message heap.
Definition: ble.h:109
ble_gatt.h
BLE GATT.
BLE_RF_TX_MODE_LP_MODE
@ BLE_RF_TX_MODE_LP_MODE
Definition: ble.h:74
gap_activity_role_t
gap_activity_role_t
Possible roles of the activity.
Definition: ble_gapm.h:491
BLE_RF_TX_MODE_INVALID
@ BLE_RF_TX_MODE_INVALID
Definition: ble.h:73
app_callback_t
The app callbacks for GAP, GATT, SM and L2CAP.
Definition: ble.h:94
app_callback_t::app_ble_init_cmp_callback
app_ble_init_cmp_cb_t app_ble_init_cmp_callback
Callback function for BLE initialization completed.
Definition: ble.h:95
ble_l2cap.h
BLE L2CAP API.
BLE_RF_MATCH_CIRCUIT_25OHM
@ BLE_RF_MATCH_CIRCUIT_25OHM
Definition: ble.h:83
ble_sec.h
BLE SEC API.
gap_cb_fun_t
The gap callback function struct.
Definition: ble_gapc.h:500
stack_heaps_table_t::bm_size
uint32_t bm_size
The size of the array for bond manager heap.
Definition: ble.h:118
BLE_RF_MATCH_CIRCUIT_100OHM
@ BLE_RF_MATCH_CIRCUIT_100OHM
Definition: ble.h:84
stack_heaps_table_t::db_ret_size
uint16_t db_ret_size
The size of the array for ATT DB heap.
Definition: ble.h:112
stack_heaps_table_t::bm_buf
uint8_t * bm_buf
Pointer to the array for bond manager heap.
Definition: ble.h:117
ble_error.h
File that contains error codes.
ble_gapc.h
BLE GAPC API.
ble_activity_start_notify_cb_register
void ble_activity_start_notify_cb_register(void(*callback)(gap_activity_role_t e_role, uint8_t index))
Register BLE activity start notification callback function.
sec_cb_fun_t
SEC register call back.
Definition: ble_sec.h:234
ble_prf.h
BLE PRF API.
ble_rf_match_circuit_get
ble_rf_match_circuit_t ble_rf_match_circuit_get(void)
Get the resistance value of the RF match circuit (unit: ohm).
stack_heaps_table_t::env_ret_size
uint16_t env_ret_size
The size of the array for environment heap.
Definition: ble.h:111
stack_heaps_table_t::buf_size
uint32_t buf_size
The size of the array for profile heap.
Definition: ble.h:116
ble_rf_match_circuit_set
void ble_rf_match_circuit_set(ble_rf_match_circuit_t e_ohm)
Set the resistance value of the RF match circuit (unit: ohm).
app_callback_t::app_sec_callback
sec_cb_fun_t * app_sec_callback
Callback function for SM.
Definition: ble.h:99
ble_stack_init
void ble_stack_init(app_callback_t *p_app_callback, stack_heaps_table_t *p_heaps_table)
Initialize BEL Stack.
ble_rf_tx_mode_t
ble_rf_tx_mode_t
RF TX mode.
Definition: ble.h:72
ble_gapm.h
BLE GAPM API.
stack_heaps_table_t::conn_buf
uint8_t * conn_buf
Pointer to the array for connection heap.
Definition: ble.h:119
ble_rf_tx_mode_set
uint8_t ble_rf_tx_mode_set(ble_rf_tx_mode_t e_rf_tx_mode)
Change the RF TX mode of LP or ULP.
gatt_common_cb_fun_t
GATT common callback function description.
Definition: ble_gatt.h:89
ble_att.h
Attribute Protocol.
ble_idle_time_notify_cb_register
void ble_idle_time_notify_cb_register(void(*callback)(uint32_t hs))
Register BLE idle time notification callback function.
stack_heaps_table_t::non_ret_size
uint16_t non_ret_size
The size of the array for non-retention heap.
Definition: ble.h:114
BLE_RF_TX_MODE_ULP_MODE
@ BLE_RF_TX_MODE_ULP_MODE
Definition: ble.h:75
ble_gattc.h
BLE GATTC API.
ble_rf_tx_mode_get
ble_rf_tx_mode_t ble_rf_tx_mode_get(void)
Get the RF TX mode of LP or ULP.
ble_hci_uart_register
void ble_hci_uart_register(uint8_t id, hci_uart_call_t *api)
Register UART instance for HCI.
ble_sync_evt_cb_t
void(* ble_sync_evt_cb_t)(uint32_t sync_cnt, uint16_t sync_period)
The BLE sync event callback.
Definition: ble.h:140
stack_heaps_table_t::non_ret
uint32_t * non_ret
Pointer to the array for non-retention heap.
Definition: ble.h:110
stack_heaps_table_t::env_ret
uint32_t * env_ret
Pointer to the array for environment heap.
Definition: ble.h:107
stack_heaps_table_t::db_ret
uint32_t * db_ret
Pointer to the array for ATT DB heap.
Definition: ble.h:108
app_callback_t::app_gap_callbacks
gap_cb_fun_t * app_gap_callbacks
Callback function for GAP.
Definition: ble.h:96
stack_heaps_table_t
The table contains the pointers to four arrays which are used as heap memory by BLE stack in ROM.
Definition: ble.h:106
send_signal_carrier_wave
void send_signal_carrier_wave(uint8_t channel)
Generate a signal carrier wave.