From aeaa4068c4ac2dcd55303536f6b8a6ddbb5c201a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Reierstad?= Date: Tue, 25 Mar 2025 07:53:05 +0100 Subject: [PATCH] Bluetooth: Host: Clarify use of identity in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- include/zephyr/bluetooth/bluetooth.h | 134 +++++++++++++-------------- subsys/bluetooth/host/shell/bt.c | 4 +- 2 files changed, 67 insertions(+), 71 deletions(-) diff --git a/include/zephyr/bluetooth/bluetooth.h b/include/zephyr/bluetooth/bluetooth.h index c3d041eafcb9..30fc2e6eeed7 100644 --- a/include/zephyr/bluetooth/bluetooth.h +++ b/include/zephyr/bluetooth/bluetooth.h @@ -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 @@ -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. * @@ -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 @@ -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 @@ -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. */ @@ -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. @@ -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 @@ -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). */ @@ -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. @@ -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 @@ -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. * @@ -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. */ @@ -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 diff --git a/subsys/bluetooth/host/shell/bt.c b/subsys/bluetooth/host/shell/bt.c index 1c4c0c7ac2ca..c9d4536e35f9 100644 --- a/subsys/bluetooth/host/shell/bt.c +++ b/subsys/bluetooth/host/shell/bt.c @@ -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; } @@ -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; }