Contiki-NG
ble-hal.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, Graz University of Technology
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 /**
32  * \file
33  * hardware abstraction for a BLE controller
34  *
35  * \author
36  * Michael Spoerk <michael.spoerk@tugraz.at>
37  */
38 /*---------------------------------------------------------------------------*/
39 
40 #ifndef BLE_HAL_H_
41 #define BLE_HAL_H_
42 
43 #include <stddef.h>
44 
45 /*---------------------------------------------------------------------------*/
46 /* BLE device address size */
47 #define BLE_ADDR_SIZE 6
48 /*---------------------------------------------------------------------------*/
49 /* Advertisement channel definitions */
50 #define BLE_ADV_DATA_LEN 31
51 #define BLE_SCAN_RESP_DATA_LEN 31
52 #define BLE_ADV_CHANNEL_1 37
53 #define BLE_ADV_CHANNEL_1_MASK 0b001
54 #define BLE_ADV_CHANNEL_2 38
55 #define BLE_ADV_CHANNEL_2_MASK 0b010
56 #define BLE_ADV_CHANNEL_3 39
57 #define BLE_ADV_CHANNEL_3_MASK 0b100
58 #define BLE_ADV_INTERVAL_MIN 20
59 #define BLE_ADV_INTERVAL_MAX 0x4000
60 #define BLE_SCAN_INTERVAL_MIN 0x0004
61 #define BLE_SCAN_INTERVAL_MAX 0x4000
62 /*---------------------------------------------------------------------------*/
63 /* Data channel definitions */
64 #define BLE_DATA_CHANNEL_MIN 0
65 #define BLE_DATA_CHANNEL_MAX 36
66 /* Types of data PDU frames */
67 #define BLE_DATA_PDU_LLID_DATA_FRAGMENT 0b01
68 #define BLE_DATA_PDU_LLID_DATA_MESSAGE 0b10
69 #define BLE_DATA_PDU_LLID_CONTROL 0b11
70 /*---------------------------------------------------------------------------*/
71 /* Types of LL control PDUs */
72 #define BLE_LL_CONN_UPDATE_REQ 0x00
73 #define BLE_LL_CHANNEL_MAP_REQ 0x01
74 #define BLE_LL_TERMINATE_IND 0x02
75 #define BLE_LL_ENC_REQ 0x03
76 #define BLE_LL_ENC_RSP 0x04
77 #define BLE_LL_START_ENC_REQ 0x05
78 #define BLE_LL_START_ENC_RSP 0x06
79 #define BLE_LL_UNKNOWN_RSP 0x07
80 #define BLE_LL_FEATURE_REQ 0x08
81 #define BLE_LL_FEATURE_RSP 0x09
82 #define BLE_LL_PAUSE_ENC_REQ 0x0A
83 #define BLE_LL_PAUSE_ENC_RSP 0x0B
84 #define BLE_LL_VERSION_IND 0x0C
85 #define BLE_LL_REJECT_IND 0x0D
86 #define BLE_LL_SLAVE_FEATURE_REQ 0x0E
87 #define BLE_LL_CONN_PARAM_REQ 0x0F
88 #define BLE_LL_CONN_PARAM_RSP 0x10
89 #define BLE_LL_REJECT_IND_EXT 0x11
90 #define BLE_LL_PING_REQ 0x12
91 #define BLE_LL_PING_RSP 0x13
92 /*---------------------------------------------------------------------------*/
93 #define FRAME_BLE_RX_EVENT 0x00 /* signaling that data was received (standard) */
94 #define FRAME_BLE_TX_EVENT 0x10 /* signaling that data was successfully sent */
95 #define FRAME_BLE_CONNECTION_EVENT 0x20 /* signaling that a new BLE connection was established */
96 #define FRAME_BLE_CONNECTION_UPDATED 0x30 /* signaling that the BLE connection parameter were successfully updated */
97 /*---------------------------------------------------------------------------*/
98 /* Return values for functions of ble_controller_driver implementations */
99 typedef enum {
100  BLE_RESULT_OK,
101  BLE_RESULT_NOT_SUPPORTED,
102  BLE_RESULT_INVALID_PARAM,
103  BLE_RESULT_ERROR
104 } ble_result_t;
105 
106 /*---------------------------------------------------------------------------*/
107 /* Type of BLE device address */
108 typedef enum {
109  BLE_ADDR_TYPE_PUBLIC,
110  BLE_ADDR_TYPE_RANDOM
111 } ble_addr_type_t;
112 
113 /*---------------------------------------------------------------------------*/
114 /* Advertising modes of BLE */
115 typedef enum {
116  /* connectable undirected advertising */
117  BLE_ADV_IND,
118 
119  /* connectable directed advertising (high duty cycle) */
120  BLE_ADV_DIR_IND_HDC,
121 
122  /* scannable undirected advertising */
123  BLE_ADV_SCAN_IND,
124 
125  /* non connectable undirected advertising */
126  BLE_ADV_NONCONN_IND,
127 
128  /* connectable directed advertising (low duty cycle) */
129  BLE_ADV_DIR_IND_LDC
130 } ble_adv_type_t;
131 
132 /*---------------------------------------------------------------------------*/
133 /* Scanning modes of BLE */
134 typedef enum {
135  /* no SCAN REQUESTS are sent */
136  BLE_SCAN_PASSIVE,
137  /* SCAN REQUESTS may be sent */
138  BLE_SCAN_ACTIVE
139 } ble_scan_type_t;
140 
141 /*---------------------------------------------------------------------------*/
142 /* Scanning filter policy */
143 typedef enum {
144  /* accept all advertisement packets */
145  BLE_SCAN_FILTER_POLICY_ACCEPT,
146  /* ignore all advertisement packets from devices not on the white list */
147  BLE_SCAN_FILTER_POLICY_IGNORE
148 } ble_scan_filter_policy_t;
149 /*---------------------------------------------------------------------------*/
150 /* List of packets to be sent by RDC layer */
151 struct ble_buf_list {
152  struct ble_buf_list *next;
153  struct queuebuf *buf;
154  void *ptr;
155 };
156 
157 /*---------------------------------------------------------------------------*/
158 /* Extension of the RADIO_PARAM fields for the BLE radios */
159 enum {
160  /* start with 100 to be sure to not interfere with the standard values*/
161  /*-----------------------------------------------------------------------*/
162  /* BLE controller general */
163  /* The bluetooth device address */
164  RADIO_CONST_BLE_BD_ADDR = 100,
165 
166  /* the size of a single BLE command buffer */
167  RADIO_CONST_BLE_BUFFER_SIZE,
168 
169  /* the amount of single BLE command buffers */
170  RADIO_CONST_BLE_BUFFER_AMOUNT,
171 
172  /*-----------------------------------------------------------------------*/
173  /* BLE advertisement */
174 
175  /* advertisement interval */
176  RADIO_PARAM_BLE_ADV_INTERVAL,
177 
178  /* BLE advertisement type (directed/undirected, ...) */
179  RADIO_PARAM_BLE_ADV_TYPE,
180 
181  /* type of own address during advertisement */
182  RADIO_PARAM_BLE_ADV_OWN_ADDR_TYPE,
183 
184  /* advertisement channel map */
185  RADIO_PARAM_BLE_ADV_CHANNEL_MAP,
186 
187  /* advertisement payload */
188  RADIO_PARAM_BLE_ADV_PAYLOAD,
189 
190  /* scan response payload */
191  RADIO_PARAM_BLE_ADV_SCAN_RESPONSE,
192 
193  /* 1: enable advertisement / 0: disable advertisement */
194  RADIO_PARAM_BLE_ADV_ENABLE,
195 
196  /*-----------------------------------------------------------------------*/
197  /* BLE scanning */
198 
199  /* scanning interval */
200  RADIO_PARAM_BLE_SCAN_INTERVAL,
201 
202  /* scanning window */
203  RADIO_PARAM_BLE_SCAN_WINDOW,
204 
205  /* BLE scanning type (active/passive) */
206  RADIO_PARAM_BLE_SCAN_TYPE,
207 
208  /* type of own address during scanning */
209  RADIO_PARAM_BLE_SCAN_OWN_ADDR_TYPE,
210 
211  /* scanning channel */
212  RADIO_PARAM_BLE_SCAN_CHANNEL,
213 
214  /* 1: enable scanning / 0: disable scanning */
215  RADIO_PARAM_BLE_SCAN_ENABLE,
216 
217  /*-----------------------------------------------------------------------*/
218  /* BLE initiating */
219  /* The initiating command uses some parameters from scanning */
220  /* (scan interval, window, address type) */
221 
222  /* address type of the advertising device */
223  RADIO_PARAM_BLE_PEER_ADDR_TYPE,
224 
225  /* address of the advertising device */
226  RADIO_PARAM_BLE_PEER_ADDR,
227 
228  /* connection interval */
229  RADIO_PARAM_BLE_CONN_INTERVAL,
230 
231  /* slave latency */
232  RADIO_PARAM_BLE_CONN_LATENCY,
233 
234  /* supervision timeout */
235  RADIO_PARAM_BLE_CONN_SUPERVISION_TIMEOUT,
236 
237  /* 1: start connection / 0: cancel connection creation */
238  RADIO_PARAM_BLE_INITIATOR_ENABLE,
239 
240  RADIO_PARAM_BLE_CONN_UPDATE
241 };
242 
243 /*---------------------------------------------------------------------------*/
244 /**
245  * The structure of a ble radio controller driver in Contiki.
246  */
247 struct ble_hal_driver {
248 
249  /*------------------------------------------------------------------------*/
250  /* GENERAL COMMANDS */
251  /**
252  * Resets the BLE controller
253  */
254  ble_result_t (*reset)(void);
255 
256  /**
257  * Reads the static BLE device address.
258  *
259  * \param addr the static device address
260  */
261  ble_result_t (*read_bd_addr)(uint8_t *addr);
262 
263  /**
264  * Reads the size of the data buffers.
265  *
266  * \param buf_len the length of a single data buffer
267  * \param num_buf the number of data buffers
268  */
269  ble_result_t (*read_buffer_size) (unsigned int *buf_len,
270  unsigned int *num_buf);
271 
272  /*------------------------------------------------------------------------*/
273  /* ADVERTISING COMMANDS */
274  /**
275  * Sets the parameter for advertising.
276  *
277  * \param adv_interval advertising interval
278  * (interval = adv_interval * 0.625 ms)
279  * \param type type of advertising
280  * \param own_addr_type indicator if own address is public/random
281  * \param adv_channel_map map of advertising channels to use
282  */
283  ble_result_t (*set_adv_param) (unsigned int adv_interval,
284  ble_adv_type_t type,
285  ble_addr_type_t own_addr_type,
286  unsigned short adv_channel_map);
287 
288  /**
289  * Reads the used power on the advertisement channels.
290  *
291  * \param power the used power in dBm
292  */
293  ble_result_t (*read_adv_channel_tx_power) (short *power);
294 
295  /**
296  * Sets the advertising data.
297  *
298  * \param data_len the length of the advertising data
299  * \param data the data to advertise
300  */
301  ble_result_t (*set_adv_data) (unsigned short data_len,
302  char *data);
303 
304  /**
305  * Sets the scan response data.
306  *
307  * \param data_len the length of the scan response data
308  * \param data the data of a scan response
309  */
310  ble_result_t (*set_scan_resp_data) (unsigned short data_len,
311  char *data);
312 
313  /**
314  * Enables/disables advertising.
315  *
316  * \param enable if 1 then enable advertising, otherwise disable
317  */
318  ble_result_t (*set_adv_enable) (unsigned short enable);
319 
320  /*------------------------------------------------------------------------*/
321  /* SCANNING COMMANDS */
322  /**
323  * Sets the parameter for scanning.
324  *
325  * \param type scan mode
326  * \param scan_interval scan interval (interval = scan_interval * 0.625 ms)
327  * \param scan_window scan window (window = scan_window * 0.625 ms)
328  * \param own_addr_type indicator if own address is public/random
329  */
330  ble_result_t (*set_scan_param) (ble_scan_type_t type,
331  unsigned int scan_interval,
332  unsigned int scan_window,
333  ble_addr_type_t own_addr_type);
334 
335  /**
336  * Enables/disables scanning.
337  *
338  * \param enable 1: enable scanning, otherwise disable
339  * \param filter_duplicates: 1: filter duplicates, otherwise no filtering
340  */
341  ble_result_t (*set_scan_enable) (unsigned short enable,
342  unsigned short filter_duplicates);
343 
344  /*------------------------------------------------------------------------*/
345  /* INITIATING COMMANDS */
346  /**
347  * Initiates the creation of a BLE connection.
348  *
349  * \param scan_interval scan interval (interval = scan_interval * 0.625 ms)
350  * \param scan_window scan window (window = scan_window * 0.625 ms)
351  * \param peer_addr_type indicator if peer address is public/random
352  * \param peer_addr ble address of the device to connect to
353  * \param own_addr_type indicator if own address is public/random
354  * \param conn_interval connection interval
355  * (interval = conn_interval * 1.25 ms)
356  * \param conn_latency slave latency
357  * \param supervision_timeout (timeout = supervision_timeout * 10 ms)
358  */
359  ble_result_t (*create_connection) (unsigned int scan_interval,
360  unsigned int scan_window,
361  ble_addr_type_t peer_addr_type,
362  uint8_t *peer_addr,
363  ble_addr_type_t own_addr_type,
364  unsigned int conn_interval,
365  unsigned int conn_latency,
366  unsigned int supervision_timeout);
367 
368  /**
369  * Cancels the initiation of a BLE connection.
370  */
371  ble_result_t (*create_connection_cancel) (void);
372 
373  /*------------------------------------------------------------------------*/
374  /* CONNECTION COMMANDS */
375  /**
376  * Updates the connection parameters.
377  * \param conn_interval connection interval
378  * (interval = conn_interval * 1.25 ms)
379  * \param conn_latency slave latency
380  * \param supervision_timeout (timeout = supervision_timeout * 10 ms)
381  */
382  ble_result_t (*connection_update) (unsigned int connection_handle,
383  unsigned int conn_interval,
384  unsigned int conn_latency,
385  unsigned int supervision_timeout);
386 
387  /**
388  * Disconnects the connection.
389  *
390  * \param connection_handle
391  * \param reason see error codes of Bluetooth specification
392  */
393  ble_result_t (*disconnect) (unsigned int connection_handle,
394  unsigned short reason);
395 
396  ble_result_t (*send) (void *buf, unsigned short buf_len);
397 
398  ble_result_t (*send_list) (struct ble_buf_list *list);
399 
400  ble_result_t (*read_connection_interval) (unsigned int conn_handle,
401  unsigned int *conn_interval_ms);
402 };
403 
404 #endif /* BLE_HAL_H_ */
addr
static uip_ds6_addr_t * addr
Pointer to a nbr cache entry.
Definition: uip-nd6.c:107
ble_hal_driver
The structure of a ble radio controller driver in Contiki.
Definition: ble-hal.h:247
Generated on Tue Dec 8 2020 18:54:52 for Contiki-NG by   doxygen 1.8.13