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 iff both the types and the 48-bit
112  *  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