1 /** @file
2 * @brief Bluetooth device address definitions and utilities.
3 */
4
5 /*
6 * Copyright (c) 2019 Nordic Semiconductor ASA
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_
11 #define ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_
12
13 #include <stdint.h>
14 #include <string.h>
15
16 #include <zephyr/sys/printk.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /**
23 * @brief Bluetooth device address definitions and utilities.
24 * @defgroup bt_addr Device Address
25 * @ingroup bluetooth
26 * @{
27 */
28
29 #define BT_ADDR_LE_PUBLIC 0x00
30 #define BT_ADDR_LE_RANDOM 0x01
31 #define BT_ADDR_LE_PUBLIC_ID 0x02
32 #define BT_ADDR_LE_RANDOM_ID 0x03
33 #define BT_ADDR_LE_UNRESOLVED 0xFE /* Resolvable Private Address
34 * (Controller unable to resolve)
35 */
36 #define BT_ADDR_LE_ANONYMOUS 0xFF /* No address provided
37 * (anonymous advertisement)
38 */
39
40 /** Length in bytes of a standard Bluetooth address */
41 #define BT_ADDR_SIZE 6
42
43 /** Bluetooth Device Address */
44 typedef struct {
45 uint8_t val[BT_ADDR_SIZE];
46 } bt_addr_t;
47 /**/
48
49 /** Length in bytes of an LE Bluetooth address. Not packed, so no sizeof() */
50 #define BT_ADDR_LE_SIZE 7
51
52 /** Bluetooth LE Device Address */
53 typedef struct {
54 uint8_t type;
55 bt_addr_t a;
56 } bt_addr_le_t;
57
58 /* Global Bluetooth address constants defined in bluetooth/common/addr.c */
59 extern const bt_addr_t bt_addr_any;
60 extern const bt_addr_t bt_addr_none;
61 extern const bt_addr_le_t bt_addr_le_any;
62 extern const bt_addr_le_t bt_addr_le_none;
63
64 /** Bluetooth device "any" address, not a valid address */
65 #define BT_ADDR_ANY (&bt_addr_any)
66 /** Bluetooth device "none" address, not a valid address */
67 #define BT_ADDR_NONE (&bt_addr_none)
68 /** Bluetooth LE device "any" address, not a valid address */
69 #define BT_ADDR_LE_ANY (&bt_addr_le_any)
70 /** Bluetooth LE device "none" address, not a valid address */
71 #define BT_ADDR_LE_NONE (&bt_addr_le_none)
72
73 /** @brief Compare Bluetooth device addresses.
74 *
75 * @param a First Bluetooth device address to compare
76 * @param b Second Bluetooth device address to compare
77 *
78 * @return negative value if @a a < @a b, 0 if @a a == @a b, else positive
79 */
bt_addr_cmp(const bt_addr_t * a,const bt_addr_t * b)80 static inline int bt_addr_cmp(const bt_addr_t *a, const bt_addr_t *b)
81 {
82 return memcmp(a, b, sizeof(*a));
83 }
84
85 /** @brief Determine equality of two Bluetooth device addresses.
86 *
87 * @retval #true if the two addresses are equal
88 * @retval #false otherwise
89 */
bt_addr_eq(const bt_addr_t * a,const bt_addr_t * b)90 static inline bool bt_addr_eq(const bt_addr_t *a, const bt_addr_t *b)
91 {
92 return bt_addr_cmp(a, b) == 0;
93 }
94
95 /** @brief Compare Bluetooth LE device addresses.
96 *
97 * @param a First Bluetooth LE device address to compare
98 * @param b Second Bluetooth LE device address to compare
99 *
100 * @return negative value if @a a < @a b, 0 if @a a == @a b, else positive
101 *
102 * @sa bt_addr_le_eq
103 */
bt_addr_le_cmp(const bt_addr_le_t * a,const bt_addr_le_t * b)104 static inline int bt_addr_le_cmp(const bt_addr_le_t *a, const bt_addr_le_t *b)
105 {
106 return memcmp(a, b, sizeof(*a));
107 }
108
109 /** @brief Determine equality of two Bluetooth LE device addresses.
110 *
111 * The Bluetooth LE addresses are equal if and only if both the types and
112 * the 48-bit addresses are numerically equal.
113 *
114 * @retval #true if the two addresses are equal
115 * @retval #false otherwise
116 */
bt_addr_le_eq(const bt_addr_le_t * a,const bt_addr_le_t * b)117 static inline bool bt_addr_le_eq(const bt_addr_le_t *a, const bt_addr_le_t *b)
118 {
119 return bt_addr_le_cmp(a, b) == 0;
120 }
121
122 /** @brief Copy Bluetooth device address.
123 *
124 * @param dst Bluetooth device address destination buffer.
125 * @param src Bluetooth device address source buffer.
126 */
bt_addr_copy(bt_addr_t * dst,const bt_addr_t * src)127 static inline void bt_addr_copy(bt_addr_t *dst, const bt_addr_t *src)
128 {
129 memcpy(dst, src, sizeof(*dst));
130 }
131
132 /** @brief Copy Bluetooth LE device address.
133 *
134 * @param dst Bluetooth LE device address destination buffer.
135 * @param src Bluetooth LE device address source buffer.
136 */
bt_addr_le_copy(bt_addr_le_t * dst,const bt_addr_le_t * src)137 static inline void bt_addr_le_copy(bt_addr_le_t *dst, const bt_addr_le_t *src)
138 {
139 memcpy(dst, src, sizeof(*dst));
140 }
141
142 /** Check if a Bluetooth LE random address is resolvable private address. */
143 #define BT_ADDR_IS_RPA(a) (((a)->val[5] & 0xc0) == 0x40)
144 /** Check if a Bluetooth LE random address is a non-resolvable private address.
145 */
146 #define BT_ADDR_IS_NRPA(a) (((a)->val[5] & 0xc0) == 0x00)
147 /** Check if a Bluetooth LE random address is a static address. */
148 #define BT_ADDR_IS_STATIC(a) (((a)->val[5] & 0xc0) == 0xc0)
149
150 /** Set a Bluetooth LE random address as a resolvable private address. */
151 #define BT_ADDR_SET_RPA(a) ((a)->val[5] = (((a)->val[5] & 0x3f) | 0x40))
152 /** Set a Bluetooth LE random address as a non-resolvable private address. */
153 #define BT_ADDR_SET_NRPA(a) ((a)->val[5] &= 0x3f)
154 /** Set a Bluetooth LE random address as a static address. */
155 #define BT_ADDR_SET_STATIC(a) ((a)->val[5] |= 0xc0)
156
157 /** @brief Create a Bluetooth LE random non-resolvable private address. */
158 int bt_addr_le_create_nrpa(bt_addr_le_t *addr);
159
160 /** @brief Create a Bluetooth LE random static address. */
161 int bt_addr_le_create_static(bt_addr_le_t *addr);
162
163 /** @brief Check if a Bluetooth LE address is a random private resolvable
164 * address.
165 *
166 * @param addr Bluetooth LE device address.
167 *
168 * @return true if address is a random private resolvable address.
169 */
bt_addr_le_is_rpa(const bt_addr_le_t * addr)170 static inline bool bt_addr_le_is_rpa(const bt_addr_le_t *addr)
171 {
172 if (addr->type != BT_ADDR_LE_RANDOM) {
173 return false;
174 }
175
176 return BT_ADDR_IS_RPA(&addr->a);
177 }
178
179 /** @brief Check if a Bluetooth LE address is valid identity address.
180 *
181 * Valid Bluetooth LE identity addresses are either public address or
182 * random static address.
183 *
184 * @param addr Bluetooth LE device address.
185 *
186 * @return true if address is a valid identity address.
187 */
bt_addr_le_is_identity(const bt_addr_le_t * addr)188 static inline bool bt_addr_le_is_identity(const bt_addr_le_t *addr)
189 {
190 if (addr->type == BT_ADDR_LE_PUBLIC) {
191 return true;
192 }
193
194 return BT_ADDR_IS_STATIC(&addr->a);
195 }
196
197 /**
198 * @brief Recommended length of user string buffer for Bluetooth address
199 *
200 * @details The recommended length guarantee the output of address
201 * conversion will not lose valuable information about address being
202 * processed.
203 */
204 #define BT_ADDR_STR_LEN 18
205
206 /**
207 * @brief Recommended length of user string buffer for Bluetooth LE address
208 *
209 * @details The recommended length guarantee the output of address
210 * conversion will not lose valuable information about address being
211 * processed.
212 */
213 #define BT_ADDR_LE_STR_LEN 30
214
215 /** @brief Converts binary Bluetooth address to string.
216 *
217 * @param addr Address of buffer containing binary Bluetooth address.
218 * @param str Address of user buffer with enough room to store formatted
219 * string containing binary address.
220 * @param len Length of data to be copied to user string buffer. Refer to
221 * BT_ADDR_STR_LEN about recommended value.
222 *
223 * @return Number of successfully formatted bytes from binary address.
224 */
bt_addr_to_str(const bt_addr_t * addr,char * str,size_t len)225 static inline int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)
226 {
227 return snprintk(str, len, "%02X:%02X:%02X:%02X:%02X:%02X",
228 addr->val[5], addr->val[4], addr->val[3],
229 addr->val[2], addr->val[1], addr->val[0]);
230 }
231
232 /** @brief Converts binary LE Bluetooth address to string.
233 *
234 * @param addr Address of buffer containing binary LE Bluetooth address.
235 * @param str Address of user buffer with enough room to store
236 * formatted string containing binary LE address.
237 * @param len Length of data to be copied to user string buffer. Refer to
238 * BT_ADDR_LE_STR_LEN about recommended value.
239 *
240 * @return Number of successfully formatted bytes from binary address.
241 */
bt_addr_le_to_str(const bt_addr_le_t * addr,char * str,size_t len)242 static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
243 size_t len)
244 {
245 char type[10];
246
247 switch (addr->type) {
248 case BT_ADDR_LE_PUBLIC:
249 strcpy(type, "public");
250 break;
251 case BT_ADDR_LE_RANDOM:
252 strcpy(type, "random");
253 break;
254 case BT_ADDR_LE_PUBLIC_ID:
255 strcpy(type, "public-id");
256 break;
257 case BT_ADDR_LE_RANDOM_ID:
258 strcpy(type, "random-id");
259 break;
260 default:
261 snprintk(type, sizeof(type), "0x%02x", addr->type);
262 break;
263 }
264
265 return snprintk(str, len, "%02X:%02X:%02X:%02X:%02X:%02X (%s)",
266 addr->a.val[5], addr->a.val[4], addr->a.val[3],
267 addr->a.val[2], addr->a.val[1], addr->a.val[0], type);
268 }
269
270 /** @brief Convert Bluetooth address from string to binary.
271 *
272 * @param[in] str The string representation of a Bluetooth address.
273 * @param[out] addr Address of buffer to store the Bluetooth address
274 *
275 * @retval 0 Success. The parsed address is stored in @p addr.
276 * @return -EINVAL Invalid address string. @p str is not a well-formed Bluetooth address.
277 */
278 int bt_addr_from_str(const char *str, bt_addr_t *addr);
279
280 /** @brief Convert LE Bluetooth address from string to binary.
281 *
282 * @param[in] str The string representation of an LE Bluetooth address.
283 * @param[in] type The string representation of the LE Bluetooth address
284 * type.
285 * @param[out] addr Address of buffer to store the LE Bluetooth address
286 *
287 * @return Zero on success or (negative) error code otherwise.
288 */
289 int bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr);
290
291 /**
292 * @}
293 */
294
295 #ifdef __cplusplus
296 }
297 #endif
298
299 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_ADDR_H_ */
300
