Bluetooth device address definitions and utilities. More...

Data Structures
struct	bt_addr_t
	Bluetooth Device Address. More...
struct	bt_addr_le_t
	Bluetooth LE Device Address. More...

Macros
#define	BT_ADDR_LE_PUBLIC 0x00
#define	BT_ADDR_LE_RANDOM 0x01
#define	BT_ADDR_LE_PUBLIC_ID 0x02
#define	BT_ADDR_LE_RANDOM_ID 0x03
#define	BT_ADDR_LE_UNRESOLVED
#define	BT_ADDR_LE_ANONYMOUS
#define	BT_ADDR_SIZE 6
	Length in bytes of a standard Bluetooth address.
#define	BT_ADDR_LE_SIZE 7
	Length in bytes of an LE Bluetooth address.
#define	BT_ADDR_ANY (&bt_addr_any)
	Bluetooth device "any" address, not a valid address.
#define	BT_ADDR_NONE (&bt_addr_none)
	Bluetooth device "none" address, not a valid address.
#define	BT_ADDR_LE_ANY (&bt_addr_le_any)
	Bluetooth LE device "any" address, not a valid address.
#define	BT_ADDR_LE_NONE (&bt_addr_le_none)
	Bluetooth LE device "none" address, not a valid address.
#define	BT_ADDR_IS_RPA(a)
	Check if a Bluetooth LE random address is resolvable private address.
#define	BT_ADDR_IS_NRPA(a)
	Check if a Bluetooth LE random address is a non-resolvable private address.
#define	BT_ADDR_IS_STATIC(a)
	Check if a Bluetooth LE random address is a static address.
#define	BT_ADDR_SET_RPA(a)
	Set a Bluetooth LE random address as a resolvable private address.
#define	BT_ADDR_SET_NRPA(a)
	Set a Bluetooth LE random address as a non-resolvable private address.
#define	BT_ADDR_SET_STATIC(a)
	Set a Bluetooth LE random address as a static address.
#define	BT_ADDR_STR_LEN 18
	Recommended length of user string buffer for Bluetooth address.
#define	BT_ADDR_LE_STR_LEN 20
	Recommended length of user string buffer for Bluetooth LE address.
#define	bt_addr_str(_addr)
	Convert a Bluetooth address to a string.
#define	bt_addr_le_str(_addr)
	Convert a Bluetooth LE address to a string.
#define	BT_IRK_SIZE 16U
	Size of an Identity Resolving Key in octets.

Functions
static int	bt_addr_cmp (const bt_addr_t a, const bt_addr_t b)
	Compare Bluetooth device addresses.
static bool	bt_addr_eq (const bt_addr_t a, const bt_addr_t b)
	Determine equality of two Bluetooth device addresses.
static int	bt_addr_le_cmp (const bt_addr_le_t a, const bt_addr_le_t b)
	Compare Bluetooth LE device addresses.
static bool	bt_addr_le_eq (const bt_addr_le_t a, const bt_addr_le_t b)
	Determine equality of two Bluetooth LE device addresses.
static void	bt_addr_copy (bt_addr_t dst, const bt_addr_t src)
	Copy Bluetooth device address.
static void	bt_addr_le_copy (bt_addr_le_t dst, const bt_addr_le_t src)
	Copy Bluetooth LE device address.
static void	bt_addr_le_copy_addr (bt_addr_le_t dst, const bt_addr_t src, uint8_t src_type)
	Copy Bluetooth LE device address from Bluetooth device address and type.
int	bt_addr_le_create_nrpa (bt_addr_le_t *addr)
	Create a Bluetooth LE random non-resolvable private address.
int	bt_addr_le_create_static (bt_addr_le_t *addr)
	Create a Bluetooth LE random static address.
static bool	bt_addr_le_is_rpa (const bt_addr_le_t *addr)
	Check if a Bluetooth LE address is a random private resolvable address.
static bool	bt_addr_le_is_identity (const bt_addr_le_t *addr)
	Check if a Bluetooth LE address is valid identity address.
static int	bt_addr_to_str (const bt_addr_t addr, char str, size_t len)
	Converts binary Bluetooth address to string.
static int	bt_addr_le_to_str (const bt_addr_le_t addr, char str, size_t len)
	Converts binary LE Bluetooth address to string.
int	bt_addr_from_str (const char str, bt_addr_t addr)
	Convert Bluetooth address from string to binary.
int	bt_addr_le_from_str (const char str, bt_addr_le_t addr)
	Convert LE Bluetooth address from string to binary.
int	bt_addr_le_rpa_resolve (uint8_t id, const bt_addr_le_t addr, bt_addr_le_t resolved_addr)
	Resolve a Bluetooth LE Resolvable Private Address (RPA) to its identity address.
bool	bt_addr_matches_irk (const bt_addr_t *rpa, const uint8_t irk[16U])
	Check whether a Resolvable Private Address was generated from an IRK.

Variables
const bt_addr_t	bt_addr_any
const bt_addr_t	bt_addr_none
const bt_addr_le_t	bt_addr_le_any
const bt_addr_le_t	bt_addr_le_none

Detailed Description

Bluetooth device address definitions and utilities.

Since: 1.0

Version: 1.1.0

Macro Definition Documentation

◆ BT_ADDR_ANY

#define BT_ADDR_ANY (&bt_addr_any)

#include <zephyr/bluetooth/addr.h>

Bluetooth device "any" address, not a valid address.

◆ BT_ADDR_IS_NRPA

#define BT_ADDR_IS_NRPA ( a )

#include <zephyr/bluetooth/addr.h>

Value:

(((a)->val[5] & 0xc0) == 0x00)

Check if a Bluetooth LE random address is a non-resolvable private address.

◆ BT_ADDR_IS_RPA

#define BT_ADDR_IS_RPA ( a )

#include <zephyr/bluetooth/addr.h>

Value:

(((a)->val[5] & 0xc0) == 0x40)

Check if a Bluetooth LE random address is resolvable private address.

◆ BT_ADDR_IS_STATIC

#define BT_ADDR_IS_STATIC ( a )

#include <zephyr/bluetooth/addr.h>

Value:

(((a)->val[5] & 0xc0) == 0xc0)

Check if a Bluetooth LE random address is a static address.

◆ BT_ADDR_LE_ANONYMOUS

#define BT_ADDR_LE_ANONYMOUS

#include <zephyr/bluetooth/addr.h>

Value:

0xFF /* No address provided
* (anonymous advertisement)
*/

◆ BT_ADDR_LE_ANY

#define BT_ADDR_LE_ANY (&bt_addr_le_any)

#include <zephyr/bluetooth/addr.h>

Bluetooth LE device "any" address, not a valid address.

◆ BT_ADDR_LE_NONE

#define BT_ADDR_LE_NONE (&bt_addr_le_none)

#include <zephyr/bluetooth/addr.h>

Bluetooth LE device "none" address, not a valid address.

◆ BT_ADDR_LE_PUBLIC

#define BT_ADDR_LE_PUBLIC 0x00

#include <zephyr/bluetooth/addr.h>

◆ BT_ADDR_LE_PUBLIC_ID

#define BT_ADDR_LE_PUBLIC_ID 0x02

#include <zephyr/bluetooth/addr.h>

◆ BT_ADDR_LE_RANDOM

#define BT_ADDR_LE_RANDOM 0x01

#include <zephyr/bluetooth/addr.h>

◆ BT_ADDR_LE_RANDOM_ID

#define BT_ADDR_LE_RANDOM_ID 0x03

#include <zephyr/bluetooth/addr.h>

◆ BT_ADDR_LE_SIZE

#define BT_ADDR_LE_SIZE 7

#include <zephyr/bluetooth/addr.h>

Length in bytes of an LE Bluetooth address.

Not packed, so no sizeof()

◆ bt_addr_le_str

#define bt_addr_le_str ( _addr )

#include <zephyr/bluetooth/addr.h>

Value:

bt_addr_le_tmp_str(_addr).str

Convert a Bluetooth LE address to a string.

Parameters

_addr Pointer to the Bluetooth LE address (bt_addr_le_t)

Returns: A string pointer which is only valid until the end of the full expression. In practice this means that this is primarily useful as an input parameter to printk/printf or logging calls.

◆ BT_ADDR_LE_STR_LEN

#define BT_ADDR_LE_STR_LEN 20

#include <zephyr/bluetooth/addr.h>

Recommended length of user string buffer for Bluetooth LE address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed. Format: "P:XX:XX:XX:XX:XX:XX" or "R:XX:XX:XX:XX:XX:XX"

◆ BT_ADDR_LE_UNRESOLVED

#define BT_ADDR_LE_UNRESOLVED

#include <zephyr/bluetooth/addr.h>

Value:

0xFE /* Resolvable Private Address
* (Controller unable to resolve)
*/

◆ BT_ADDR_NONE

#define BT_ADDR_NONE (&bt_addr_none)

#include <zephyr/bluetooth/addr.h>

Bluetooth device "none" address, not a valid address.

◆ BT_ADDR_SET_NRPA

#define BT_ADDR_SET_NRPA ( a )

#include <zephyr/bluetooth/addr.h>

Value:

((a)->val[5] &= 0x3f)

Set a Bluetooth LE random address as a non-resolvable private address.

◆ BT_ADDR_SET_RPA

#define BT_ADDR_SET_RPA ( a )

#include <zephyr/bluetooth/addr.h>

Value:

((a)->val[5] = (((a)->val[5] & 0x3f) | 0x40))

Set a Bluetooth LE random address as a resolvable private address.

◆ BT_ADDR_SET_STATIC

#define BT_ADDR_SET_STATIC ( a )

#include <zephyr/bluetooth/addr.h>

Value:

((a)->val[5] |= 0xc0)

Set a Bluetooth LE random address as a static address.

◆ BT_ADDR_SIZE

#define BT_ADDR_SIZE 6

#include <zephyr/bluetooth/addr.h>

Length in bytes of a standard Bluetooth address.

◆ bt_addr_str

#define bt_addr_str ( _addr )

#include <zephyr/bluetooth/addr.h>

Value:

bt_addr_tmp_str(_addr).str

Convert a Bluetooth address to a string.

Parameters

_addr Pointer to the Bluetooth address (bt_addr_t)

Returns: A string pointer which is only valid until the end of the full expression. In practice this means that this is primarily useful as an input parameter to printk/printf or logging calls.

◆ BT_ADDR_STR_LEN

#define BT_ADDR_STR_LEN 18

#include <zephyr/bluetooth/addr.h>

Recommended length of user string buffer for Bluetooth address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed.

◆ BT_IRK_SIZE

#define BT_IRK_SIZE 16U

#include <zephyr/bluetooth/addr.h>

Size of an Identity Resolving Key in octets.

Function Documentation

◆ bt_addr_cmp()

int bt_addr_cmp	(	const bt_addr_t *	a,
		const bt_addr_t *	b )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Compare Bluetooth device addresses.

Parameters

a	First Bluetooth device address to compare
b	Second Bluetooth device address to compare

Returns: negative value if a < b, 0 if a == b, else positive

◆ bt_addr_copy()

void bt_addr_copy	(	bt_addr_t *	dst,
		const bt_addr_t *	src )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Copy Bluetooth device address.

Parameters

dst	Bluetooth device address destination buffer.
src	Bluetooth device address source buffer.

◆ bt_addr_eq()

bool bt_addr_eq	(	const bt_addr_t *	a,
		const bt_addr_t *	b )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Determine equality of two Bluetooth device addresses.

Return values

true	if the two addresses are equal
false	otherwise

◆ bt_addr_from_str()

int bt_addr_from_str	(	const char *	str,
		bt_addr_t *	addr )

#include <zephyr/bluetooth/addr.h>

Convert Bluetooth address from string to binary.

Parameters

[in]	str	The string representation of a Bluetooth address.
[out]	addr	Address of buffer to store the Bluetooth address

Return values

0	Success. The parsed address is stored in `addr`.

Returns: -EINVAL Invalid address string. str is not a well-formed Bluetooth address.

◆ bt_addr_le_cmp()

int bt_addr_le_cmp	(	const bt_addr_le_t *	a,
		const bt_addr_le_t *	b )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Compare Bluetooth LE device addresses.

Parameters

a	First Bluetooth LE device address to compare
b	Second Bluetooth LE device address to compare

Returns: negative value if a < b, 0 if a == b, else positive

See also: bt_addr_le_eq

◆ bt_addr_le_copy()

void bt_addr_le_copy	(	bt_addr_le_t *	dst,
		const bt_addr_le_t *	src )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Copy Bluetooth LE device address.

Parameters

dst	Bluetooth LE device address destination buffer.
src	Bluetooth LE device address source buffer.

◆ bt_addr_le_copy_addr()

void bt_addr_le_copy_addr	(	bt_addr_le_t *	dst,
		const bt_addr_t *	src,
		uint8_t	src_type )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Copy Bluetooth LE device address from Bluetooth device address and type.

Parameters

dst	Bluetooth LE device address destination buffer.
src	Bluetooth device address source buffer.
src_type	Bluetooth device address source type.

◆ bt_addr_le_create_nrpa()

int bt_addr_le_create_nrpa ( bt_addr_le_t * addr )

#include <zephyr/bluetooth/addr.h>

Create a Bluetooth LE random non-resolvable private address.

◆ bt_addr_le_create_static()

int bt_addr_le_create_static ( bt_addr_le_t * addr )

#include <zephyr/bluetooth/addr.h>

Create a Bluetooth LE random static address.

◆ bt_addr_le_eq()

bool bt_addr_le_eq	(	const bt_addr_le_t *	a,
		const bt_addr_le_t *	b )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Determine equality of two Bluetooth LE device addresses.

The Bluetooth LE addresses are equal if and only if both the types and the 48-bit addresses are numerically equal.

Return values

true	if the two addresses are equal
false	otherwise

◆ bt_addr_le_from_str()

int bt_addr_le_from_str	(	const char *	str,
		bt_addr_le_t *	addr )

#include <zephyr/bluetooth/addr.h>

Convert LE Bluetooth address from string to binary.

The string must use the format produced by bt_addr_le_to_str(): "P:XX:XX:XX:XX:XX:XX" for a public address or "R:XX:XX:XX:XX:XX:XX" for a random address. The type prefix and the hexadecimal digits are case-insensitive.

Parameters

[in]	str	The string representation of an LE Bluetooth address.
[out]	addr	Address of buffer to store the LE Bluetooth address

Return values

0	Success. The parsed address is stored in `addr`.
-EINVAL	Invalid address string. `str` has an unknown type prefix or is not a well-formed Bluetooth address.

◆ bt_addr_le_is_identity()

bool bt_addr_le_is_identity ( const bt_addr_le_t * addr )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Check if a Bluetooth LE address is valid identity address.

Valid Bluetooth LE identity addresses are either public address or random static address.

Parameters

addr	Bluetooth LE device address.

Returns: true if address is a valid identity address.

◆ bt_addr_le_is_rpa()

bool bt_addr_le_is_rpa ( const bt_addr_le_t * addr )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Check if a Bluetooth LE address is a random private resolvable address.

Parameters

addr	Bluetooth LE device address.

Returns: true if address is a random private resolvable address.

◆ bt_addr_le_rpa_resolve()

int bt_addr_le_rpa_resolve	(	uint8_t	id,
		const bt_addr_le_t *	addr,
		bt_addr_le_t *	resolved_addr )

#include <zephyr/bluetooth/addr.h>

Resolve a Bluetooth LE Resolvable Private Address (RPA) to its identity address.

This function attempts to resolve a RPA to its corresponding identity address (public or random static) using the host Identity Resolving Key (IRK) database.

Attention: Available only when the following Kconfig options are enabled: CONFIG_BT_PRIVACY, CONFIG_BT_SMP.

Parameters

[in]	id	Local identity whose IRK database is used. Must be less than `CONFIG_BT_ID_MAX`.
[in]	addr	The RPA to resolve.
[out]	resolved_addr	On success, contains the resolved identity address. This will be either a public address (BT_ADDR_LE_PUBLIC) or random static address (BT_ADDR_LE_RANDOM).

Return values

0	Success. The address has been resolved. `resolved_addr` contains the identity address.
-ENOENT	`addr` is an RPA but no matching IRK was found in the database. The address could not be resolved.
-EINVAL	Invalid arguments: `addr` or `resolved_addr` is NULL, `id` is invalid, or `addr` is not an RPA.

◆ bt_addr_le_to_str()

int bt_addr_le_to_str	(	const bt_addr_le_t *	addr,
		char *	str,
		size_t	len )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Converts binary LE Bluetooth address to string.

Converts the LE Bluetooth address to a string representation in the format:

"P:XX:XX:XX:XX:XX:XX" for public addresses
"R:XX:XX:XX:XX:XX:XX" for random addresses

Address type values that carry additional HCI-level information, such as BT_ADDR_LE_PUBLIC_ID and BT_ADDR_LE_RANDOM_ID, are formatted according to their base type (public or random). The HCI sentinels for an unresolved RPA (BT_ADDR_LE_UNRESOLVED) and an anonymous advertiser (BT_ADDR_LE_ANONYMOUS) are formatted as random addresses. The additional information is not part of the string and has to be conveyed separately by the caller.

Parameters

addr	Address of buffer containing binary LE Bluetooth address.
str	Address of user buffer with enough room to store formatted string containing binary LE address.
len	Length of data to be copied to user string buffer. Refer to BT_ADDR_LE_STR_LEN about recommended value.

Returns: Number of successfully formatted bytes from binary address.

◆ bt_addr_matches_irk()

bool bt_addr_matches_irk	(	const bt_addr_t *	rpa,
		const uint8_t	irk[16U] )

#include <zephyr/bluetooth/addr.h>

Check whether a Resolvable Private Address was generated from an IRK.

Computes the hash of the random part of rpa with irk and compares it with the hash part of rpa.

Available when the Host or the Controller provides AES, that is with CONFIG_BT_HOST_CRYPTO or CONFIG_BT_CTLR_CRYPTO.

Parameters

rpa	Resolvable private address to check.
irk	Identity Resolving Key, least significant octet first, in the same byte order as the IRK used by bt_id_create() and bt_id_reset_irk().

Return values

true	`rpa` was generated from `irk`.
false	`rpa` is not a resolvable private address (see BT_ADDR_IS_RPA()), was not generated from `irk`, or the AES operation failed.

◆ bt_addr_to_str()

int bt_addr_to_str	(	const bt_addr_t *	addr,
		char *	str,
		size_t	len )

inlinestatic

#include <zephyr/bluetooth/addr.h>

Converts binary Bluetooth address to string.

Parameters

addr	Address of buffer containing binary Bluetooth address.
str	Address of user buffer with enough room to store formatted string containing binary address.
len	Length of data to be copied to user string buffer. Refer to BT_ADDR_STR_LEN about recommended value.

Returns: Number of successfully formatted bytes from binary address.

Variable Documentation

◆ bt_addr_any

const bt_addr_t bt_addr_any

extern

#include <zephyr/bluetooth/addr.h>

◆ bt_addr_le_any

const bt_addr_le_t bt_addr_le_any

extern

#include <zephyr/bluetooth/addr.h>

◆ bt_addr_le_none

const bt_addr_le_t bt_addr_le_none

extern

#include <zephyr/bluetooth/addr.h>

◆ bt_addr_none

const bt_addr_t bt_addr_none

extern

#include <zephyr/bluetooth/addr.h>

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BT_ADDR_ANY

◆ BT_ADDR_IS_NRPA

◆ BT_ADDR_IS_RPA

◆ BT_ADDR_IS_STATIC

◆ BT_ADDR_LE_ANONYMOUS

◆ BT_ADDR_LE_ANY

◆ BT_ADDR_LE_NONE

◆ BT_ADDR_LE_PUBLIC

◆ BT_ADDR_LE_PUBLIC_ID

◆ BT_ADDR_LE_RANDOM

◆ BT_ADDR_LE_RANDOM_ID

◆ BT_ADDR_LE_SIZE

◆ bt_addr_le_str

◆ BT_ADDR_LE_STR_LEN

◆ BT_ADDR_LE_UNRESOLVED

◆ BT_ADDR_NONE

◆ BT_ADDR_SET_NRPA

◆ BT_ADDR_SET_RPA

◆ BT_ADDR_SET_STATIC

◆ BT_ADDR_SIZE

◆ bt_addr_str

◆ BT_ADDR_STR_LEN

◆ BT_IRK_SIZE

Function Documentation

◆ bt_addr_cmp()

◆ bt_addr_copy()

◆ bt_addr_eq()

◆ bt_addr_from_str()

◆ bt_addr_le_cmp()

◆ bt_addr_le_copy()

◆ bt_addr_le_copy_addr()

◆ bt_addr_le_create_nrpa()

◆ bt_addr_le_create_static()

◆ bt_addr_le_eq()

◆ bt_addr_le_from_str()

◆ bt_addr_le_is_identity()

◆ bt_addr_le_is_rpa()

◆ bt_addr_le_rpa_resolve()

◆ bt_addr_le_to_str()

◆ bt_addr_matches_irk()

◆ bt_addr_to_str()

Variable Documentation

◆ bt_addr_any

◆ bt_addr_le_any

◆ bt_addr_le_none

◆ bt_addr_none