Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bluetooth: Host: Clarify use of identity in docs #87407

Merged
merged 1 commit into from
Mar 25, 2025
+67 −71
Merged

Bluetooth: Host: Clarify use of identity in docs #87407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 65 additions & 69 deletions include/zephyr/bluetooth/bluetooth.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,9 @@ extern "C" {
*/

/**
* Convenience macro for specifying the default identity. This helps
* make the code more readable, especially when only one identity is
* supported.
* Identity handle referring to the first identity address. This is a convenience macro for
* specifying the default identity address. This helps make the code more readable, especially when
* only one identity address is supported.
*/
#define BT_ID_DEFAULT 0

Expand Down Expand Up @@ -316,7 +316,7 @@ int bt_enable(bt_ready_cb_t cb);
*
* Disable Bluetooth. Can't be called before bt_enable has completed.
*
* This API will clear all configured identities and keys that are not persistently
* This API will clear all configured identity addresses and keys that are not persistently
* stored with @kconfig{CONFIG_BT_SETTINGS}. These can be restored
* with settings_load() before reenabling the stack.
*
Expand Down Expand Up @@ -396,36 +396,35 @@ uint16_t bt_get_appearance(void);
int bt_set_appearance(uint16_t new_appearance);

/**
* @brief Get the currently configured identities.
* @brief Get the currently configured identity addresses.
*
* Returns an array of the currently configured identity addresses. To
* make sure all available identities can be retrieved, the number of
* make sure all available identity addresses can be retrieved, the number of
* elements in the @a addrs array should be CONFIG_BT_ID_MAX. The identity
* identifier that some APIs expect (such as advertising parameters) is
* simply the index of the identity in the @a addrs array.
* handle that some APIs expect (such as @ref bt_le_adv_param) is
* simply the index of the identity address in the @a addrs array.
*
* If @a addrs is passed as NULL, then returned @a count contains the
* count of all available identities that can be retrieved with a
* If @a addrs is passed as NULL, then the returned @a count contains the
* count of all available identity addresses that can be retrieved with a
* subsequent call to this function with non-NULL @a addrs parameter.
*
* @note Deleted identities may show up as @ref BT_ADDR_LE_ANY in the returned
* array.
* @note Deleted identity addresses may show up as @ref BT_ADDR_LE_ANY in the returned array.
*
* @param addrs Array where to store the configured identities.
* @param count Should be initialized to the array size. Once the function
* returns it will contain the number of returned identities.
* @param addrs Array where to store the configured identity addresses.
* @param count Should be initialized to the array size. Once the function returns
* it will contain the number of returned identity addresses.
*/
void bt_id_get(bt_addr_le_t *addrs, size_t *count);

/**
* @brief Create a new identity.
* @brief Create a new identity address.
*
* Create a new identity using the given address and IRK. This function can be
* called before calling bt_enable(). However, the new identity will only be
* Create a new identity address using the given address and IRK. This function can be
* called before calling bt_enable(). However, the new identity address will only be
* stored persistently in flash when this API is used after bt_enable(). The
* reason is that the persistent settings are loaded after bt_enable() and would
* therefore cause potential conflicts with the stack blindly overwriting what's
* stored in flash. The identity will also not be written to flash in case a
* stored in flash. The identity address will also not be written to flash in case a
* pre-defined address is provided, since in such a situation the app clearly
* has some place it got the address from and will be able to repeat the
* procedure on every power cycle, i.e. it would be redundant to also store the
Expand All @@ -434,11 +433,11 @@ void bt_id_get(bt_addr_le_t *addrs, size_t *count);
* Generating random static address or random IRK is not supported when calling
* this function before bt_enable().
*
* If the application wants to have the stack randomly generate identities
* If the application wants to have the stack randomly generate identity addresses
* and store them in flash for later recovery, the way to do it would be
* to first initialize the stack (using bt_enable), then call settings_load(),
* and after that check with bt_id_get() how many identities were recovered.
* If an insufficient amount of identities were recovered the app may then
* and after that check with bt_id_get() how many identity addresses were recovered.
* If an insufficient amount of identity addresses were recovered the app may then
* call bt_id_create() to create new ones.
*
* If supported by the HCI driver (indicated by setting
Expand All @@ -447,71 +446,66 @@ void bt_id_get(bt_addr_le_t *addrs, size_t *count);
* before calling bt_enable(). Subsequent calls always add/generate random
* static addresses.
*
* @param addr Address to use for the new identity. If NULL or initialized
* to BT_ADDR_LE_ANY the stack will generate a new random
* static address for the identity and copy it to the given
* parameter upon return from this function (in case the
* parameter was non-NULL).
* @param addr Address to use for the new identity address. If NULL or initialized
* to BT_ADDR_LE_ANY the stack will generate a new random static address
* for the identity address and copy it to the given parameter upon return
* from this function (in case the parameter was non-NULL).
* @param irk Identity Resolving Key (16 bytes) to be used with this
* identity. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity and copy it back
* identity address. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity address and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
* error code on failure.
* @return Identity handle (>= 0) in case of success, or a negative error code on failure.
*/
int bt_id_create(bt_addr_le_t *addr, uint8_t *irk);

/**
* @brief Reset/reclaim an identity for reuse.
* @brief Reset/reclaim an identity address for reuse.
*
* The semantics of the @a addr and @a irk parameters of this function
* are the same as with bt_id_create(). The difference is the first
* @a id parameter that needs to be an existing identity (if it doesn't
* exist this function will return an error). When given an existing
* identity this function will disconnect any connections created using it,
* remove any pairing keys or other data associated with it, and then create
* a new identity in the same slot, based on the @a addr and @a irk
* parameters.
*
* @note the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this
* @a id parameter that needs to be an existing identity handle (if it doesn't
* exist this function will return an error). When given an existing identity handle
* this function will disconnect any connections (to the corresponding identity address)
* created using it, remove any pairing keys or other data associated with it, and then
* create a new identity address in the same slot, based on the @a addr and @a irk parameters.
*
* @note The default identity address (corresponding to BT_ID_DEFAULT) cannot be reset, and this
* API will return an error if asked to do that.
*
* @param id Existing identity identifier.
* @param addr Address to use for the new identity. If NULL or initialized
* to BT_ADDR_LE_ANY the stack will generate a new static
* random address for the identity and copy it to the given
* parameter upon return from this function (in case the
* parameter was non-NULL).
* @param id Existing identity handle.
* @param addr Address to use for the new identity address. If NULL or initialized
* to BT_ADDR_LE_ANY the stack will generate a new static random
* address for the identity address and copy it to the given
* parameter upon return from this function.
* @param irk Identity Resolving Key (16 bytes) to be used with this
* identity. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity and copy it back
* identity address. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity address and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
* error code on failure.
* @return Identity handle (>= 0) in case of success, or a negative error code on failure.
*/
int bt_id_reset(uint8_t id, bt_addr_le_t *addr, uint8_t *irk);

/**
* @brief Delete an identity.
* @brief Delete an identity address.
*
* When given a valid identity this function will disconnect any connections
* created using it, remove any pairing keys or other data associated with
* it, and then flag is as deleted, so that it can not be used for any
* operations. To take back into use the slot the identity was occupying the
* bt_id_reset() API needs to be used.
* When given a valid identity handle this function will disconnect any connections
* (to the corresponding identity address) created using it, remove any pairing keys
* or other data associated with it, and then flag is as deleted, so that it can not
* be used for any operations. To take back into use the slot the identity address was
* occupying, the bt_id_reset() API needs to be used.
*
* @note the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this
* @note The default identity address (corresponding to BT_ID_DEFAULT) cannot be deleted, and this
* API will return an error if asked to do that.
*
* @param id Existing identity identifier.
* @param id Existing identity handle.
*
* @return 0 in case of success, or a negative error code on failure.
*/
Expand Down Expand Up @@ -908,7 +902,7 @@ enum advertising_options {
BT_LE_ADV_OPT_CODED = BIT(12),

/**
* @brief Advertise without a device address (identity or RPA).
* @brief Advertise without a device address (identity address or RPA).
*
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref advertising_options field) to be
* set as @ref bt_le_adv_param.options.
Expand Down Expand Up @@ -997,7 +991,9 @@ enum advertising_options {
/** LE Advertising Parameters. */
struct bt_le_adv_param {
/**
* @brief Local identity.
* @brief Local identity handle.
*
* The index of the identity address in the local Bluetooth controller.
*
* @note When extended advertising @kconfig{CONFIG_BT_EXT_ADV} is not
* enabled or not supported by the controller it is not possible
Expand Down Expand Up @@ -1714,7 +1710,7 @@ uint8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);

/** @brief Advertising set info structure. */
struct bt_le_ext_adv_info {
/* Local identity */
/** Local identity handle. */
uint8_t id;

/** Currently selected Transmit Power (dBM). */
Expand Down Expand Up @@ -2748,7 +2744,7 @@ BUILD_ASSERT(BT_GAP_SCAN_FAST_WINDOW == BT_GAP_SCAN_FAST_INTERVAL_MIN,
*
* @note The LE scanner by default does not use the Identity Address of the
* local device when @kconfig{CONFIG_BT_PRIVACY} is disabled. This is to
* prevent the active scanner from disclosing the identity information
* prevent the active scanner from disclosing the identity address information
* when requesting additional information from advertisers.
* In order to enable directed advertiser reports then
* @kconfig{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
Expand Down Expand Up @@ -2937,12 +2933,12 @@ struct bt_le_oob {
* - Creating a connection in progress, wait for the connected callback.
* In addition when extended advertising @kconfig{CONFIG_BT_EXT_ADV} is
* not enabled or not supported by the controller:
* - Advertiser is enabled using a Random Static Identity Address for a
* different local identity.
* - The local identity conflicts with the local identity used by other
* - Advertiser is enabled using a Random Static Identity Address as a
* different local identity address.
* - The local identity address conflicts with the local identity address used by other
* roles.
*
* @param[in] id Local identity, in most cases BT_ID_DEFAULT.
* @param[in] id Local identity handle, in most cases BT_ID_DEFAULT.
* @param[out] oob LE OOB information
*
* @return Zero on success or error code otherwise, positive in case of
Expand Down Expand Up @@ -2980,7 +2976,7 @@ int bt_le_ext_adv_oob_get_local(struct bt_le_ext_adv *adv,
/**
* @brief Clear pairing information.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param id Local identity handle (mostly just BT_ID_DEFAULT).
* @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
* devices.
*
Expand All @@ -2997,7 +2993,7 @@ struct bt_bond_info {
/**
* @brief Iterate through all existing bonds.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param id Local identity handle (mostly just BT_ID_DEFAULT).
* @param func Function to call for each bond.
* @param user_data Data to pass to the callback function.
*/
Expand Down Expand Up @@ -3121,7 +3117,7 @@ int bt_le_per_adv_set_response_data(struct bt_le_per_adv_sync *per_adv_sync,
* @details Valid Bluetooth LE identity addresses are either public address or random static
* address.
*
* @param id Local identity (typically @ref BT_ID_DEFAULT).
* @param id Local identity handle (typically @ref BT_ID_DEFAULT).
* @param addr Bluetooth LE device address.
*
* @return true if @p addr is bonded with local @p id
Expand Down
4 changes: 2 additions & 2 deletions subsys/bluetooth/host/shell/bt.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1500,7 +1500,7 @@ static int cmd_id_reset(const struct shell *sh, size_t argc, char *argv[])
int err;

if (argc < 2) {
shell_error(sh, "Identity identifier not specified");
shell_error(sh, "Identity handle not specified");
return -ENOEXEC;
}

Expand Down Expand Up @@ -1534,7 +1534,7 @@ static int cmd_id_delete(const struct shell *sh, size_t argc, char *argv[])
int err;

if (argc < 2) {
shell_error(sh, "Identity identifier not specified");
shell_error(sh, "Identity handle not specified");
return -ENOEXEC;
}

Expand Down
Loading