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 #include "ble_event.h"
63
64 #include <stdio.h>
65
66 /** @addtogroup BLE_COMMEN_ENUM Enumerations
67 * @{
68 */
69 /**
70 * @brief RF TX mode.
71 */
72 typedef enum
73 {
74 BLE_RF_TX_MODE_INVALID = 0,
75 BLE_RF_TX_MODE_LP_MODE = 1,
76 BLE_RF_TX_MODE_ULP_MODE = 2,
77 } ble_rf_tx_mode_t;
78
79 /**
80 * @brief The resistance value (ohm) of the RF match circuit.
81 */
82 typedef enum
83 {
84 BLE_RF_MATCH_CIRCUIT_25OHM = 25,
85 BLE_RF_MATCH_CIRCUIT_100OHM = 100,
86 } ble_rf_match_circuit_t;
87
88 /** @} */
89
90 /** @addtogroup BLE_COMMEN_STRUCTURES Structures
91 * @{
92 */
93 /**@brief The table contains the pointers to four arrays which are used
94 * as heap memory by BLE stack in ROM. The size of four arrays depends on
95 * the number of connections and the number of attributes of profiles. */
96 typedef struct
97 {
98 uint32_t *env_ret; /**< Pointer to the array for environment heap */
99 uint32_t *db_ret; /**< Pointer to the array for ATT DB heap */
100 uint32_t *msg_ret; /**< Pointer to the array for message heap */
101 uint32_t *non_ret; /**< Pointer to the array for non-retention heap */
102 uint16_t env_ret_size; /**< The size of the array for environment heap */
103 uint16_t db_ret_size; /**< The size of the array for ATT DB heap */
104 uint16_t msg_ret_size; /**< The size of the array for message heap */
105 uint16_t non_ret_size; /**< The size of the array for non-retention heap */
106 uint8_t *prf_buf; /**< Pointer to the array for profile heap */
107 uint32_t buf_size; /**< The size of the array for profile heap */
108 uint8_t *bm_buf; /**< Pointer to the array for bond manager heap */
109 uint32_t bm_size; /**< The size of the array for bond manager heap */
110 uint8_t *conn_buf; /**< Pointer to the array for connection heap */
111 uint32_t conn_size; /**< The size of the array for connection heap */
112 uint8_t *scan_dup_filt_list_buf; /**< Pointer to the array for adv duplicate filter */
113 uint32_t scan_dup_filt_list_size; /**< The size of the array for adv duplicate filter */
114 }stack_heaps_table_t;
115
116 /**@brief The function pointers for HCI UART. */
117 typedef struct
118 {
119 void (*init)(void); /**< Initialize UART. */
120 void (*flow_on)(void); /**< Flow control on. */
121 bool (*flow_off)(void); /**< Flow control off. */
122 void (*finish_transfers)(void); /**< Finish the current transferring. */
123 void (*read)(uint8_t *bufptr, uint32_t size, void (*callback) (void*, uint8_t), void* dummy); /**< Read data. */
124 void (*write)(uint8_t *bufptr, uint32_t size, void (*callback) (void*, uint8_t), void* dummy); /**< Write data. */
125 } hci_uart_call_t;
126 /** @} */
127
128 /** @addtogroup BLE_COMMEN_TYPEDEF Typedefs
129 * @{
130 */
131
132 /**@brief The BLE sync event callback. */
133 typedef void (*ble_sync_evt_cb_t)(uint32_t sync_cnt, uint16_t sync_period);
134 /** @} */
135
136 /** @addtogroup BLE_COMMEN_FUNCTIONS Functions
137 * @{ */
138 /**
139 *****************************************************************************************
140 * @brief Initialize BLE Stack.
141 *
142 * @param[in] evt_handler: Pointer to ble events handler.
143 * @param[in] p_heaps_table: Pointer to the BLE stack heaps table.
144 *****************************************************************************************
145 */
146 uint16_t ble_stack_init(ble_evt_handler_t evt_handler, stack_heaps_table_t *p_heaps_table);
147
148 /**
149 *****************************************************************************************
150 * @brief Initialize only BLE Stack Controller.
151 *
152 * @param[in] p_heaps_table: Pointer to the BLE stack heaps table.
153 *****************************************************************************************
154 */
155 void ble_stack_controller_init(stack_heaps_table_t *p_heaps_table);
156
157 /**
158 *****************************************************************************************
159 * @brief Register UART instance for HCI.
160 *
161 * @param[in] id: Instance index.
162 * @param[in] api: Pointer to the struct of function pointers for HCI UART.
163 *****************************************************************************************
164 */
165 void ble_hci_uart_register(uint8_t id, hci_uart_call_t *api);
166
167 /**
168 *****************************************************************************************
169 * @brief Register BLE idle time notification callback function.
170 *
171 * @param[in] callback: function pointer of BLE idle time notification function.
172 * @note param[in] of callback: hs - the idle time of BLE in half slot (312.5μs).
173 * Callback will be called by BLE ISR to notify the rest idle time if there are some BLE activities.
174 * It should be realized as simlpe as you can.
175 * It's not suitable for ISO activities.
176 *****************************************************************************************
177 */
178 void ble_idle_time_notify_cb_register(void (*callback)(uint32_t hs));
179
180 /**
181 *****************************************************************************************
182 * @brief Register BLE activity start notification callback function.
183 *
184 * @param[in] callback: function pointer of BLE activity start notification function.
185 * @note param[in] of callback: e_role - the role of activity, gap_activity_role_t for possible roles.
186 * param[in] of callback: index - The index parameter is interpreted by role.
187 * If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising.
188 * If role is GAP_ACTIVITY_ROLE_CON, it's the index of Connection.
189 * For all other roles, it should be ignored.
190 * Callback will be called by BLE ISR when the BLE activity starts every time.
191 * It should be realized as simlpe as you can.
192 * Notice: You must define the start callback in the RAM space to avoid hardfault.
193 * It's not suitable for ISO activities.
194 *****************************************************************************************
195 */
196 void ble_activity_start_notify_cb_register(void (*callback)(ble_gap_actv_role_t e_role, uint8_t index));
197
198 /**
199 *****************************************************************************************
200 * @brief Register BLE activity end notification callback function.
201 *
202 * @param[in] callback: function pointer of BLE activity end notification function.
203 * @note param[in] of callback: e_role - the role of activity,gap_activity_role_t for possible roles.
204 * param[in] of callback: index - The index parameter is interpreted by role.
205 * If role is GAP_ACTIVITY_ROLE_ADV, it's the index of Advertising.
206 * If role is GAP_ACTIVITY_ROLE_CON, it's the index of Connection.
207 * For all other roles, it should be ignored.
208 * Callback will be called by BLE ISR when the BLE activity ends every time.
209 * It should be realized as simlpe as you can. You'd better to define it in the RAM space
210 * It's not suitable for ISO activities.
211 *****************************************************************************************
212 */
213 void ble_activity_end_notify_cb_register(void (*callback)(ble_gap_actv_role_t e_role, uint8_t index));
214
215 /**
216 *****************************************************************************************
217 * @brief Create sync source.
218 *
219 * @param[in] period: Period of sync source.
220 *
221 * @return SDK_ERR_DISALLOWED: Create sync source fail.
222 * SDK_SUCCESS: Create sync source successfully.
223 *****************************************************************************************
224 */
225 uint16_t ble_sync_source_create(uint16_t period);
226
227 /**
228 *****************************************************************************************
229 * @brief Register sync event callback.
230 *
231 * @param[in] sync_evt_cb: Sync event callback.
232 *
233 * @return SDK_ERR_POINTER_NULL: Pointer to sync event callback is NULL.
234 * SDK_SUCCESS: Register successfully.
235 *****************************************************************************************
236 */
237 uint16_t ble_sync_evt_cb_register(ble_sync_evt_cb_t sync_evt_cb);
238
239 /**
240 *****************************************************************************************
241 * @brief Distribute sync source.
242 *
243 * @param[in] conn_idx: The connection index.
244 *
245 * @return SDK_ERR_INVALID_CONN_IDX: Invalid connect index.
246 * SDK_ERR_DISALLOWED: Distribute is disallowed.
247 * SDK_SUCCESS: Distribute successfully.
248 *****************************************************************************************
249 */
250 uint16_t ble_sync_source_distribute(uint8_t conn_idx);
251
252 /**
253 *****************************************************************************************
254 * @brief Destroy sync source.
255 *
256 * @return SDK_SUCCESS: Destroy successfully.
257 *****************************************************************************************
258 */
259 uint16_t ble_sync_source_destroy(void);
260
261 /**
262 *****************************************************************************************
263 * @brief Change the RF TX mode of LP or ULP.
264 *
265 * @param[in] e_rf_tx_mode: Refer to @ref ble_rf_tx_mode_t.
266 * BLE_RF_TX_MODE_LP_MODE: LP mode.
267 * BLE_RF_TX_MODE_ULP_MODE: ULP mode.
268 * Others: invalid mode.
269 *
270 * @note This function should be called before BLE stack init.
271 *
272 * @return SDK_SUCCESS: Successfully set Tx mode.
273 * SDK_ERR_DISALLOWED: Failed to set Tx mode.
274 *****************************************************************************************
275 */
276 uint8_t ble_rf_tx_mode_set(ble_rf_tx_mode_t e_rf_tx_mode);
277
278 /**
279 *****************************************************************************************
280 * @brief Get the RF TX mode of LP or ULP.
281 *
282 * @return BLE_RF_TX_MODE_LP_MODE: LP Mode.
283 * BLE_RF_TX_MODE_ULP_MODE: ULP Mode.
284 * Others: Fail.
285 *****************************************************************************************
286 */
287 ble_rf_tx_mode_t ble_rf_tx_mode_get(void);
288
289 /**
290 *****************************************************************************************
291 * @brief Set the resistance value of the RF match circuit (unit: ohm).
292 *
293 * @note This function should be called before BLE stack init.
294 *
295 * @param[in] e_ohm: The resistance value (ohm) of the RF match circuit according to the board.
296 * BLE_RF_MATCH_CIRCUIT_25OHM: 25 ohm.
297 * BLE_RF_MATCH_CIRCUIT_100OHM: 100 ohm.
298 * Others: invalid.
299 *****************************************************************************************
300 */
301 void ble_rf_match_circuit_set(ble_rf_match_circuit_t e_ohm);
302
303 /**
304 *****************************************************************************************
305 * @brief Get the resistance value of the RF match circuit (unit: ohm).
306 *
307 * @return The resistance value (ohm) of the RF match circuit according to the board (ohm).
308 * BLE_RF_MATCH_CIRCUIT_25OHM: 25 ohm.
309 * BLE_RF_MATCH_CIRCUIT_100OHM: 100 ohm.
310 * Others: invalid.
311 *****************************************************************************************
312 */
313 ble_rf_match_circuit_t ble_rf_match_circuit_get(void);
314
315 /**
316 *****************************************************************************************
317 * @brief Generate a signal carrier wave.
318 *
319 * @param[in] channel: 0~39 channel, 2402~2480 Mhz.
320 *
321 *****************************************************************************************
322 */
323 void send_signal_carrier_wave(uint8_t channel);
324
325 /** @} */
326 #endif
327 /** @} */
328 /** @} */
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.
ble_stack_init
uint16_t ble_stack_init(ble_evt_handler_t evt_handler, stack_heaps_table_t *p_heaps_table)
Initialize BLE Stack.
hci_uart_call_t
The function pointers for HCI UART.
Definition: ble.h:118
ble_sync_evt_cb_register
uint16_t ble_sync_evt_cb_register(ble_sync_evt_cb_t sync_evt_cb)
Register sync event callback.
stack_heaps_table_t::prf_buf
uint8_t * prf_buf
Pointer to the array for profile heap.
Definition: ble.h:106
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:104
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:83
ble_gap_actv_role_t
ble_gap_actv_role_t
Possible roles of the activity.
Definition: ble_gapm.h:505
stack_heaps_table_t::conn_size
uint32_t conn_size
The size of the array for connection heap.
Definition: ble.h:111
stack_heaps_table_t::msg_ret
uint32_t * msg_ret
Pointer to the array for message heap.
Definition: ble.h:100
ble_gatt.h
BLE GATT.
BLE_RF_TX_MODE_LP_MODE
@ BLE_RF_TX_MODE_LP_MODE
Definition: ble.h:75
BLE_RF_TX_MODE_INVALID
@ BLE_RF_TX_MODE_INVALID
Definition: ble.h:74
ble_l2cap.h
BLE L2CAP API.
ble_activity_start_notify_cb_register
void ble_activity_start_notify_cb_register(void(*callback)(ble_gap_actv_role_t e_role, uint8_t index))
Register BLE activity start notification callback function.
BLE_RF_MATCH_CIRCUIT_25OHM
@ BLE_RF_MATCH_CIRCUIT_25OHM
Definition: ble.h:84
ble_sec.h
BLE SEC API.
stack_heaps_table_t::bm_size
uint32_t bm_size
The size of the array for bond manager heap.
Definition: ble.h:109
BLE_RF_MATCH_CIRCUIT_100OHM
@ BLE_RF_MATCH_CIRCUIT_100OHM
Definition: ble.h:85
stack_heaps_table_t::db_ret_size
uint16_t db_ret_size
The size of the array for ATT DB heap.
Definition: ble.h:103
stack_heaps_table_t::bm_buf
uint8_t * bm_buf
Pointer to the array for bond manager heap.
Definition: ble.h:108
ble_error.h
File that contains error codes.
ble_gapc.h
BLE GAPC API.
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:102
stack_heaps_table_t::buf_size
uint32_t buf_size
The size of the array for profile heap.
Definition: ble.h:107
stack_heaps_table_t::scan_dup_filt_list_size
uint32_t scan_dup_filt_list_size
The size of the array for adv duplicate filter.
Definition: ble.h:113
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).
ble_event.h
BLE event header files.
ble_rf_tx_mode_t
ble_rf_tx_mode_t
RF TX mode.
Definition: ble.h:73
ble_stack_controller_init
void ble_stack_controller_init(stack_heaps_table_t *p_heaps_table)
Initialize only BLE Stack Controller.
ble_gapm.h
BLE GAPM API.
ble_activity_end_notify_cb_register
void ble_activity_end_notify_cb_register(void(*callback)(ble_gap_actv_role_t e_role, uint8_t index))
Register BLE activity end notification callback function.
stack_heaps_table_t::scan_dup_filt_list_buf
uint8_t * scan_dup_filt_list_buf
Pointer to the array for adv duplicate filter.
Definition: ble.h:112
stack_heaps_table_t::conn_buf
uint8_t * conn_buf
Pointer to the array for connection heap.
Definition: ble.h:110
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.
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:105
ble_evt_handler_t
void(* ble_evt_handler_t)(const ble_evt_t *p_evt)
The BLE event handler type.
Definition: ble_event.h:213
BLE_RF_TX_MODE_ULP_MODE
@ BLE_RF_TX_MODE_ULP_MODE
Definition: ble.h:76
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:133
stack_heaps_table_t::non_ret
uint32_t * non_ret
Pointer to the array for non-retention heap.
Definition: ble.h:101
stack_heaps_table_t::env_ret
uint32_t * env_ret
Pointer to the array for environment heap.
Definition: ble.h:98
stack_heaps_table_t::db_ret
uint32_t * db_ret
Pointer to the array for ATT DB heap.
Definition: ble.h:99
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:97
send_signal_carrier_wave
void send_signal_carrier_wave(uint8_t channel)
Generate a signal carrier wave.