michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: host: Update documentation regarding LE SC and OOB pairing

Browse source 
Update documentation regarding LE SC and OOB to include full name
befor starting to use abbreviations. Rephrase some sentences to be more
clear and add references to Kconfig options.

Signed-off-by: Joakim Andersson <joakim.andersson@nordicsemi.no>
This commit is contained in:
Joakim Andersson 2020-03-10 14:15:36 +01:00 • committed by Johan Hedberg
commit ba2a327c5b
2 changed files with 36 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

50
include/bluetooth/bluetooth.h
View file

@ -145,8 +145,8 @@ void bt_id_get(bt_addr_le_t *addrs, size_t *count);
* identity. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy support
* (CONFIG_BT_PRIVACY) is not enabled this parameter must
* the parameter was non-NULL). If privacy
* :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
@ -178,8 +178,8 @@ int bt_id_create(bt_addr_le_t *addr, u8_t *irk);
* identity. If set to all zeroes or NULL, the stack will
* generate a random IRK for the identity and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy support
* (CONFIG_BT_PRIVACY) is not enabled this parameter must
* the parameter was non-NULL). If privacy
* :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
@ -249,8 +249,10 @@ enum {
/** Convenience value when no options are specified. */
BT_LE_ADV_OPT_NONE = 0,
/** Advertise as connectable. Type of advertising is determined by
* providing SCAN_RSP data and/or enabling local privacy support.
/** Advertise as connectable. If not connectable then the type of
* advertising is determined by providing scan response data.
* The advertiser address is determined by the type of advertising
* and/or enabling privacy :option:`CONFIG_BT_PRIVACY`.
*/
BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
@ -264,9 +266,12 @@ enum {
*/
BT_LE_ADV_OPT_ONE_TIME = BIT(1),
/** Advertise using the identity address as the own address.
/** Advertise using the identity address as the advertiser address.
* @warning This will compromise the privacy of the device, so care
* must be taken when using this option.
* @note The address used for advertising will not be the same as
* returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
* should be used to get the LE address.
*/
BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
@ -280,7 +285,8 @@ enum {
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
/** Enable use of Resolvable Private Address (RPA) as the target address
* in directed advertisements when CONFIG_BT_PRIVACY is not enabled.
* in directed advertisements when :option:`CONFIG_BT_PRIVACY` is not
* enabled.
* This is required if the remote device is privacy-enabled and
* supports address resolution of the target address in directed
* advertisement.
@ -616,7 +622,7 @@ void bt_data_parse(struct net_buf_simple *ad,
bool (*func)(struct bt_data *data, void *user_data),
void *user_data);
/** OOB data that is specific for LE SC pairing method. */
/** LE Secure Connections pairing Out of Band data. */
struct bt_le_oob_sc_data {
/** Random Number. */
u8_t r[16];
@ -625,32 +631,32 @@ struct bt_le_oob_sc_data {
u8_t c[16];
};
/** General OOB data. */
/** LE Out of Band information. */
struct bt_le_oob {
/** LE address. If local privacy is enabled this is Resolvable Private
/** LE address. If privacy is enabled this is a Resolvable Private
* Address.
*/
bt_addr_le_t addr;
/** OOB data that are relevant for LESC pairing. */
/** LE Secure Connections pairing Out of Band data. */
struct bt_le_oob_sc_data le_sc_data;
};
/**
* @brief Get LE local Out Of Band information
/** @brief Get local LE Out of Band (OOB) information.
*
* This function allows to get local information that are useful for Out Of Band
* pairing or connection creation process.
* This function allows to get local information that are useful for
* Out of Band pairing or connection creation.
*
* If privacy is enabled this will result in generating new Resolvable Private
* Address that is valid for CONFIG_BT_RPA_TIMEOUT seconds. This address
* will be used for advertising, active scanning and connection creation.
* If privacy :option:`CONFIG_BT_PRIVACY` is enabled this will result in
* generating new Resolvable Private Address (RPA) that is valid for
* :option:`CONFIG_BT_RPA_TIMEOUT` seconds. This address will be used for
* advertising, active scanning and connection creation.
*
* @param id Local identity, in most cases BT_ID_DEFAULT.
* @param oob LE related information
* @param[in] id Local identity, in most cases BT_ID_DEFAULT.
* @param[out] oob LE OOB information
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error
* of protocol error or negative (POSIX) in case of stack internal error.
*/
int bt_le_oob_get_local(u8_t id, struct bt_le_oob *oob);

15
include/bluetooth/conn.h
View file

@ -633,7 +633,7 @@ void bt_set_oob_data_flag(bool enable);
int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const u8_t *tk);
/**
* @brief Set OOB data during LE SC pairing procedure
* @brief Set OOB data during LE Secure Connections (SC) pairing procedure
*
* This function allows to set OOB data during the LE SC pairing procedure. The
* function should only be called in response to the oob_data_request() callback
@ -656,7 +656,7 @@ int bt_le_oob_set_sc_data(struct bt_conn *conn,
const struct bt_le_oob_sc_data *oobd_remote);
/**
* @brief Get OOB data used for LE SC pairing procedure
* @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
*
* This function allows to get OOB data during the LE SC pairing procedure that
* were set by the bt_le_oob_set_sc_data() API.
@ -709,7 +709,7 @@ struct bt_conn_oob_info {
} type;
union {
/** LESC OOB pairing parameters */
/** LE Secure Connections OOB pairing parameters */
struct {
/** OOB data configuration */
enum {
@ -858,14 +858,15 @@ struct bt_conn_auth_cb {
*/
void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
/** @brief Request the user to provide OOB data.
/** @brief Request the user to provide Out of Band (OOB) data.
*
* When called the user is expected to provide OOB data. The required
* data are indicated by the information structure.
*
* For LESC OOB pairing method, the user should provide local OOB data,
* remote OOB data or both depending on their availability. Their value
* should be given to the stack using the bt_le_oob_set_sc_data() API.
* For LE Secure Connections OOB pairing, the user should provide
* local OOB data, remote OOB data or both depending on their
* availability. Their value should be given to the stack using the
* bt_le_oob_set_sc_data() API.
*
* This callback must be set to non-NULL in order to support OOB
* pairing.