Bluetooth: Host: Clarify use of identity in docs
Clarifies the use of identity in `bluetooth.h` by specifying whether the
documentation refers to the identity address, i. e. the actual address
`bt_addr_le_t`, or the identity handle, i. e. an index corresponding to
a specific identity address.
Signed-off-by: Håvard Reierstad <haavard.reierstad@nordicsemi.no>
diff --git a/include/zephyr/bluetooth/bluetooth.h b/include/zephyr/bluetooth/bluetooth.h
index c3d041e..30fc2e6 100644
--- a/include/zephyr/bluetooth/bluetooth.h
+++ b/include/zephyr/bluetooth/bluetooth.h
@@ -61,9 +61,9 @@
*/
/**
- * 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
@@ -316,7 +316,7 @@
*
* 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.
*
@@ -396,36 +396,35 @@
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
@@ -434,11 +433,11 @@
* 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
@@ -447,71 +446,66 @@
* 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.
+ * @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 (BT_ID_DEFAULT) cannot be reset, i.e. this
+ * @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.
*/
@@ -908,7 +902,7 @@
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.
@@ -997,7 +991,9 @@
/** 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
@@ -1714,7 +1710,7 @@
/** @brief Advertising set info structure. */
struct bt_le_ext_adv_info {
- /* Local identity */
+ /** Local identity handle. */
uint8_t id;
/** Currently selected Transmit Power (dBM). */
@@ -2748,7 +2744,7 @@
*
* @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.
@@ -2937,12 +2933,12 @@
* - 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
@@ -2980,7 +2976,7 @@
/**
* @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.
*
@@ -2997,7 +2993,7 @@
/**
* @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.
*/
@@ -3121,7 +3117,7 @@
* @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
diff --git a/subsys/bluetooth/host/shell/bt.c b/subsys/bluetooth/host/shell/bt.c
index 1c4c0c7..c9d4536 100644
--- a/subsys/bluetooth/host/shell/bt.c
+++ b/subsys/bluetooth/host/shell/bt.c
@@ -1500,7 +1500,7 @@
int err;
if (argc < 2) {
- shell_error(sh, "Identity identifier not specified");
+ shell_error(sh, "Identity handle not specified");
return -ENOEXEC;
}
@@ -1534,7 +1534,7 @@
int err;
if (argc < 2) {
- shell_error(sh, "Identity identifier not specified");
+ shell_error(sh, "Identity handle not specified");
return -ENOEXEC;
}
