Developer World
Spresense SDK Library v3.3.0-375c679
ble_util.h
1/****************************************************************************
2 * sdk/modules/include/bluetooth/ble_util.h
3 *
4 * Copyright 2023, 2024 Sony Semiconductor Solutions Corporation
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in
14 * the documentation and/or other materials provided with the
15 * distribution.
16 * 3. Neither the name of Sony Semiconductor Solutions Corporation nor
17 * the names of its contributors may be used to endorse or promote
18 * products derived from this software without specific prior written
19 * permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
28 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 *
34 ****************************************************************************/
35
36#ifndef __SDK_MODULES_INCLUDE_BLUETOOTH_BLE_UTIL_H
37#define __SDK_MODULES_INCLUDE_BLUETOOTH_BLE_UTIL_H
38
39/****************************************************************************
40 * Included Files
41 ****************************************************************************/
42
43#include <stdint.h>
44#include <bluetooth/bt_common.h>
45#include <bluetooth/ble_gatt.h>
46#include <bluetooth/hal/bt_if.h>
47
48#ifdef __cplusplus
49#define EXTERN extern "C"
50extern "C"
51{
52#else
53#define EXTERN extern
54#endif
55
56/****************************************************************************
57 * Public Functions Prototypes
58 ****************************************************************************/
59
60/* name: bleutil_convert_uuid2str
61 * Convert BLE_UUID to string.
62 *
63 * uuid [in] : UUID
64 * str [out] : UUID string
65 * In uuid->type = BLE_UUID_TYPE_UUID128 case,
66 * VVVVVVVV-WWWW-XXXX-YYYY-ZZZZZZZZZZZZ.
67 * otherwise XXXX
68 * len [in] : str buffer length.
69 * In uuid->type = BLE_UUID_TYPE_UUID128 case,
70 * len needs to be greater than BLE_UUID_128BIT_STRING_LENGTH.
71 * othewise, len needs to be greater than BLE_UUID_16BIT_STRING_LENGTH.
72 *
73 * Return : Positive integer String length of str.
74 * -ENOMEM len is too short.
75 */
76
77int bleutil_convert_uuid2str(BLE_UUID *uuid, char *str, int len);
78
79/* name: bleutil_convert_str2uuid
80 * Convert UUID string to BLE_UUID structure.
81 *
82 * str [in] : UUID string
83 * uuid [out] : BLE_UUID structure
84 *
85 * Return : OK convert success, ERROR invalid input string
86 */
87
88int bleutil_convert_str2uuid(char *str, BLE_UUID *uuid);
89
90/* name: bleutil_uuidcmp
91 * Compare two UUIDs that are input.
92 *
93 * uuid1 [in] : UUID1
94 * uuid2 [in] : UUID2
95 *
96 * Return : 0 Two UUIDs are same. 0 Not
97 */
98
99int bleutil_uuidcmp(BLE_UUID *uuid1, BLE_UUID *uuid2);
100
101/* name: bleutil_add_btaddr
102 * Add a BLE address in the ble_status.
103 *
104 * status [in/out] : Status instance.
105 * addr [in] : BLE address
106 * addr_type [in] : BLE address type
107 */
108
109void bleutil_add_btaddr(struct ble_state_s *state, BT_ADDR *addr,
110 uint8_t addr_type);
111
112/* name: bleutil_find_srvc_uuid
113 * Find specific UUID from advertising data.
114 *
115 * uuid [in] : Target UUID to find.
116 * data [in] : Advertising data
117 * len [in] : Advertising data length in bytes
118 *
119 * Return : 1 Found the UUID. 0 Not
120 */
121
122int bleutil_find_srvc_uuid(BLE_UUID *uuid, uint8_t *data, uint8_t len);
123
124/* name: bleutil_get_devicename
125 * Get device name from advertising data
126 *
127 * data [in] : Advertising data
128 * len [in] : Advertising data length in bytes
129 * devname [out] : Device name
130 *
131 * Return : 1 Device name is contained. 0 Not
132 */
133
134int bleutil_get_devicename(uint8_t *data, uint8_t len, char *devname);
135
136/* name: bleutil_get_addrtype
137 * Get BLE address type from advertising data
138 *
139 * data [in] : Advertising data
140 * len [in] : Advertising data length in bytes
141 *
142 * Return : BLE address type. One of below
143 * BLE_ADDRTYPE_PUBLIC
144 * BLE_ADDRTYPE_RAND_STATIC
145 * BLE_ADDRTYPE_RAND_PRIV_RESOLVABLE
146 * BLE_ADDRTYPE_RAND_PRIV_NONRESOLVABLE
147 */
148
149BLE_ADDRESS_TYPE bleutil_get_addrtype(uint8_t *data, uint8_t len);
150
151/* name: bleutil_get_rssi
152 * Get BLE RSSI value from advertising data
153 *
154 * data [in] : Advertising data
155 * len [in] : Advertising data length in bytes
156 *
157 * Return : BLE RSSI value for advertising
158 */
159
160int8_t bleutil_get_rssi(uint8_t *data, uint8_t len);
161
162/* name: bleutil_get_advertising_flags
163 * Get advertising flags from advertising data
164 * This flags setting is defined in P.15 of
165 * https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=556598
166 *
167 * data [in] : Advertising data
168 * len [in] : Advertising data length in bytes
169 * flags [out] : Advertising flags, which has the bit structure.
170 * Each bits are defined as follows
171 * BLE_ADV_FLAGS_LIMITED_DISC_MODE
172 * BLE_ADV_FLAGS_GENERAL_DISC_MODE
173 * BLE_ADV_FLAGS_BR_EDR_NOT_SUPPORTED
174 * BLE_ADV_FLAGS_LE_BR_EDR_CONTROLLER
175 * BLE_ADV_FLAGS_LE_BR_EDR_HOST
176 *
177 * Return : 1 Advertising flags is contained. 0 Not
178 */
179
180int bleutil_get_advertising_flags(uint8_t *data, uint8_t len, uint8_t *flags);
181
182/* name: bleutil_get_txpower
183 * Get advertise flags from advertising data
184 *
185 * data [in] : Advertising data
186 * len [in] : Advertising data length in bytes
187 * txpower [out] : TX power(-127dBm to +127dBm)
188 *
189 * Return : 1 TX power is contained. 0 Not
190 */
191
192int bleutil_get_txpower(uint8_t *data, uint8_t len, int8_t *txpower);
193
194/* name: bleutil_get_connection_interval
195 * Get connection interval range from advertising data.
196 *
197 * data [in] : Advertising data
198 * len [in] : Advertising data length in bytes
199 * min [out] : The minimum value for the connection interval
200 * The actual minimum value = min * 1.25msec
201 * max [out] : The maximum value for the connection interval
202 * The actual maximum value = max * 1.25msec
203 *
204 * Return : 1 Connection interval is contained. 0 Not
205 */
206
207int bleutil_get_connection_interval(uint8_t *data,
208 uint8_t len,
209 uint16_t *min,
210 uint16_t *max);
211
212/* name: bleutil_judge_srvc_uuid_requested
213 * Judge if specific UUID is requested from advertising data.
214 *
215 * uuid [in] : Target UUID, that own device provides
216 * data [in] : Advertising data
217 * len [in] : Advertising data length in bytes
218 *
219 * Return : 1 UUID is requested. 0 Not
220 */
221
222int bleutil_judge_srvc_uuid_requested(BLE_UUID *uuid,
223 uint8_t *data,
224 uint8_t len);
225
226/* name: bleutil_get_appearance
227 * Get appearance from advertising data.
228 * Appearances are defined in P.27 - P.40
229 * of https://btprodspecificationrefs.blob.core.windows.net/assigned-numbers/Assigned%20Number%20Types/Assigned_Numbers.pdf
230 *
231 * data [in] : Advertising data
232 * len [in] : Advertising data length in bytes
233 * appearance [out] : Apperance. One of below
234 * BLE_APPEARANCE_GENERIC_PHONE
235 * BLE_APPEARANCE_GENERIC_COMPUTER
236 * BLE_APPEARANCE_GENERIC_WATCH
237 * BLE_APPEARANCE_WATCH_SPORTS
238 * BLE_APPEARANCE_GENERIC_CLOCK
239 * BLE_APPEARANCE_GENERIC_DISPLAY
240 * BLE_APPEARANCE_GENERIC_REMOTE_CONTROL
241 * BLE_APPEARANCE_GENERIC_EYE_GLASSES
242 * BLE_APPEARANCE_GENERIC_TAG
243 * BLE_APPEARANCE_GENERIC_KEYRING
244 * BLE_APPEARANCE_GENERIC_MEDIA_PLAYER
245 * BLE_APPEARANCE_GENERIC_BARCODE_SCANNER
246 * BLE_APPEARANCE_GENERIC_THERMOMETER
247 * BLE_APPEARANCE_THERMOMETER_EAR
248 * BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR
249 * BLE_APPEARANCE_HEART_RATE_BELT
250 * BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE
251 * BLE_APPEARANCE_BLOOD_PRESSURE_ARM
252 * BLE_APPEARANCE_BLOOD_PRESSURE_WRIST
253 * BLE_APPEARANCE_GENERIC_HID_DEVICE
254 * BLE_APPEARANCE_HID_KEYBOARD
255 * BLE_APPEARANCE_HID_MOUSE
256 * BLE_APPEARANCE_HID_JOYSTICK
257 * BLE_APPEARANCE_HID_GAMEPAD
258 * BLE_APPEARANCE_HID_DIGITIZER_TABLET
259 * BLE_APPEARANCE_HID_CARD_READER
260 * BLE_APPEARANCE_HID_DIGITAL_PEN
261 * BLE_APPEARANCE_HID_BARCODE_SCANNER
262 * BLE_APPEARANCE_GENERIC_GLUCOSE_METER
263 * BLE_APPEARANCE_GENERIC_RUNNING_WALKING_SENSOR
264 * BLE_APPEARANCE_RUNNING_WALKING_SENSOR_IN_SHOE
265 * BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_SHOE
266 * BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_HIP
267 * BLE_APPEARANCE_GENERIC_CYCLING
268 * BLE_APPEARANCE_CYCLING_COMPUTER
269 * BLE_APPEARANCE_CYCLING_SPEED_SENSOR
270 * BLE_APPEARANCE_CYCLING_CADENCE_SENSOR
271 * BLE_APPEARANCE_CYCLING_POWER_SENSOR
272 * BLE_APPEARANCE_CYCLING_SPEED_AND_CADENCE_SENSOR
273 *
274 * Return : 1 Apperance is contained. 0 Not
275 */
276
277int bleutil_get_appearance(uint8_t *data, uint8_t len, uint16_t *appearance);
278
279/* name: bleutil_get_advertise_interval
280 * Get advertising interval range from advertising data.
281 *
282 * data [in] : Advertising data
283 * len [in] : Advertising data length in bytes
284 * interval [out] : The advertising interval
285 * The actual value = interval * 0.625msec
286 *
287 * Return : 1 Advertising interval is contained. 0 Not
288 */
289
290int bleutil_get_advertising_interval(uint8_t *data, uint8_t len, uint16_t *interval);
291
292/* name: bleutil_get_manufacturer_specific_data
293 * Get manufacturer specific data from advertising data.
294 * The manufacturer specific data consists of company ID and arbitrary data.
295 * Company IDs are defined in P.216 - P.402
296 * of https://btprodspecificationrefs.blob.core.windows.net/assigned-numbers/Assigned%20Number%20Types/Assigned_Numbers.pdf
297 *
298 * data [in] : Advertising data
299 * len [in] : Advertising data length in bytes
300 * company [out] : company ID
301 * specific_data [out] : Manufacturer specific data
302 * specific_datalen [out] : Manufacturer specific data length
303 *
304 * Return : 1 Manufacturer specific data is contained. 0 Not
305 */
306
307int bleutil_get_manufacturer_specific_data(uint8_t *data,
308 uint8_t len,
309 uint8_t *company,
310 uint8_t **specific_data,
311 uint8_t *specific_datalen);
312
313#undef EXTERN
314#ifdef __cplusplus
315}
316#endif
317
318#endif /* __SDK_MODULES_INCLUDE_BLUETOOTH_BLE_UTIL_H */
ble_gatt.h
Bluetooth Low Energy GATT Server/Client API.
BLE_ADDRESS_TYPE
BLE_ADDRESS_TYPE
BLE address type.
Definition: bluetooth.h:470
bt_common.h
Bluetooth generic API.
bt_if.h
Bluetooth HAL I/F.
BLE_UUID
BLE UUID structure.
Definition: ble_gatt.h:177
BT_ADDR
BT address types.
Definition: bluetooth.h:171
ble_state_s
Bluetooth LE context.
Definition: bt_common.h:176