From 78cfce425899666396c546f40f186a9f55658d89 Mon Sep 17 00:00:00 2001 From: Szymon Janc Date: Tue, 11 Jun 2019 09:33:26 +0200 Subject: [PATCH] nimble/gap: Add missing doxygen documentation --- nimble/host/include/host/ble_gap.h | 541 ++++++++++++++++++++++++++++- 1 file changed, 526 insertions(+), 15 deletions(-) diff --git a/nimble/host/include/host/ble_gap.h b/nimble/host/include/host/ble_gap.h index 8cbdc131d..a6f92a098 100644 --- a/nimble/host/include/host/ble_gap.h +++ b/nimble/host/include/host/ble_gap.h @@ -227,43 +227,99 @@ struct ble_gap_conn_desc { uint8_t master_clock_accuracy; }; +/** @brief Connection parameters */ struct ble_gap_conn_params { + /** Scan interval in 0.625ms units */ uint16_t scan_itvl; + + /** Scan window in 0.625ms units */ uint16_t scan_window; + + /** Minimum value for connection interval in 1.25ms units */ uint16_t itvl_min; + + /** Maximum value for connection interval in 1.25ms units */ uint16_t itvl_max; + + /** Connection latency */ uint16_t latency; + + /** Supervision timeout in 10ms units */ uint16_t supervision_timeout; + + /** Minimum length of connection event in 0.625ms units */ uint16_t min_ce_len; + + /** Maximum length of connection event in 0.625ms units */ uint16_t max_ce_len; }; +/** @brief Extended discovery parameters */ struct ble_gap_ext_disc_params { + /** Scan interval in 0.625ms units */ uint16_t itvl; + + /** Scan window in 0.625ms units */ uint16_t window; + + /** If passive scan should be used */ uint8_t passive:1; }; +/** @brief Discovery parameters */ struct ble_gap_disc_params { + /** Scan interval in 0.625ms units */ uint16_t itvl; + + /** Scan window in 0.625ms units */ uint16_t window; + + /** Scan filter policy */ uint8_t filter_policy; + + /** If limited discovery procedure should be used */ uint8_t limited:1; + + /** If passive scan should be used */ uint8_t passive:1; + + /** If enable duplicates filtering */ uint8_t filter_duplicates:1; }; +/** @brief Connection parameters update parameters */ struct ble_gap_upd_params { + /** Minimum value for connection interval in 1.25ms units */ uint16_t itvl_min; + + /** Maximum value for connection interval in 1.25ms units */ uint16_t itvl_max; + + /** Connection latency */ uint16_t latency; + + /** Supervision timeout in 10ms units */ uint16_t supervision_timeout; + + /** Minimum length of connection event in 0.625ms units */ uint16_t min_ce_len; + + /** Maximum length of connection event in 0.625ms units */ uint16_t max_ce_len; }; +/** @brief Passkey query */ struct ble_gap_passkey_params { + /** Passkey action, can be one of following constants: + * - BLE_SM_IOACT_NONE + * - BLE_SM_IOACT_OOB + * - BLE_SM_IOACT_INPUT + * - BLE_SM_IOACT_DISP + * - BLE_SM_IOACT_NUMCMP + */ uint8_t action; + + /** Passkey to compare, valid for BLE_SM_IOACT_NUMCMP action */ uint32_t numcmp; }; @@ -273,39 +329,100 @@ struct ble_gap_passkey_params { #define BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE 0x01 #define BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED 0x02 +/** @brief Extended advertising report */ struct ble_gap_ext_disc_desc { - /*** Common fields. */ + /** Report properties bitmask + * - BLE_HCI_ADV_CONN_MASK + * - BLE_HCI_ADV_SCAN_MASK + * - BLE_HCI_ADV_DIRECT_MASK + * - BLE_HCI_ADV_SCAN_RSP_MASK + * - BLE_HCI_ADV_LEGACY_MASK + * */ uint8_t props; + + /** Advertising data status, can be one of following constants: + * - BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE + * - BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE + * - BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED + */ uint8_t data_status; + + /** Legacy advertising PDU type. Valid if BLE_HCI_ADV_LEGACY_MASK props is + * set. Can be one of following constants: + * - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND + * - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND + * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND + * - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND + * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP + */ uint8_t legacy_event_type; + + /** Advertiser address */ ble_addr_t addr; + + /** Received signal strength indication in dBm (127 if unavailable) */ int8_t rssi; + + /** Advertiser transmit power in dBm (127 if unavailable) */ int8_t tx_power; + + /** Advertising Set ID */ uint8_t sid; + + /** Primary advertising PHY, can be one of following constants: + * - BLE_HCI_LE_PHY_1M + * - BLE_HCI_LE_PHY_CODED + */ uint8_t prim_phy; + + /** Secondary advertising PHY, can be one of following constants: + * - BLE_HCI_LE_PHY_1M + * - LE_HCI_LE_PHY_2M + * - BLE_HCI_LE_PHY_CODED + */ uint8_t sec_phy; + + /** Periodic advertising interval. 0 if no periodic advertising. */ uint16_t periodic_adv_itvl; + + /** Advertising Data length */ uint8_t length_data; + + /** Advertising data */ uint8_t *data; - /*** - * LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if - * direct address fields are not present. + + /** Directed advertising address. Valid if BLE_HCI_ADV_DIRECT_MASK props is + * set (BLE_ADDR_ANY otherwise). */ ble_addr_t direct_addr; }; #endif +/** @brief Advertising report */ struct ble_gap_disc_desc { - /*** Common fields. */ + /** Advertising PDU type. Can be one of following constants: + * - BLE_HCI_ADV_RPT_EVTYPE_ADV_IND + * - BLE_HCI_ADV_RPT_EVTYPE_DIR_IND + * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_IND + * - BLE_HCI_ADV_RPT_EVTYPE_NONCONN_IND + * - BLE_HCI_ADV_RPT_EVTYPE_SCAN_RSP + */ uint8_t event_type; + + /** Advertising Data length */ uint8_t length_data; + + /** Advertiser address */ ble_addr_t addr; + + /** Received signal strength indication in dBm (127 if unavailable) */ int8_t rssi; + + /** Advertising data */ uint8_t *data; - /*** - * LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if - * direct address fields are not present. + /** Directed advertising address. Valid for BLE_HCI_ADV_RPT_EVTYPE_DIR_IND + * event type (BLE_ADDR_ANY otherwise). */ ble_addr_t direct_addr; }; @@ -719,12 +836,30 @@ struct ble_gap_event { * o BLE_GAP_EVENT_PERIODIC_SYNC */ struct { + /** BLE_ERR_SUCCESS on success or error code on failure. Other + * fields are valid only for success + */ uint8_t status; + /** Periodic sync handle */ uint16_t sync_handle; + + /** Advertising Set ID */ uint8_t sid; + + /** Advertiser address */ ble_addr_t adv_addr; + + /** Advertising PHY, can be one of following constants: + * - BLE_HCI_LE_PHY_1M + * - LE_HCI_LE_PHY_2M + * - BLE_HCI_LE_PHY_CODED + */ uint8_t adv_phy; + + /** Periodic advertising interval */ uint16_t per_adv_ival; + + /** Advertiser clock accuracy */ uint8_t adv_clk_accuracy; } periodic_sync; @@ -734,11 +869,26 @@ struct ble_gap_event { * o BLE_GAP_EVENT_PERIODIC_REPORT */ struct { + /** Periodic sync handle */ uint16_t sync_handle; + + /** Advertiser transmit power in dBm (127 if unavailable) */ int8_t tx_power; + + /** Received signal strength indication in dBm (127 if unavailable) */ int8_t rssi; + + /** Advertising data status, can be one of following constants: + * - BLE_HCI_PERIODIC_DATA_STATUS_COMPLETE + * - BLE_HCI_PERIODIC_DATA_STATUS_INCOMPLETE + * - BLE_HCI_PERIODIC_DATA_STATUS_TRUNCATED + */ uint8_t data_status; + + /** Advertising Data length */ uint8_t data_length; + + /** Advertising data */ uint8_t *data; } periodic_report; @@ -750,7 +900,12 @@ struct ble_gap_event { * o BLE_GAP_EVENT_PERIODIC_SYNC_LOST */ struct { + /** Periodic sync handle */ uint16_t sync_handle; + + /** Reason for sync lost, can be BLE_HS_ETIMEOUT for timeout or + * BLE_HS_EDONE for locally terminated sync + */ int reason; } periodic_sync_lost; #endif @@ -927,40 +1082,169 @@ int ble_gap_adv_set_fields(const struct ble_hs_adv_fields *rsp_fields); int ble_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields); #if MYNEWT_VAL(BLE_EXT_ADV) +/** @brief Extended advertising parameters */ struct ble_gap_ext_adv_params { + /** If perform connectable advertising */ unsigned int connectable:1; + + /** If perform scannable advertising */ unsigned int scannable:1; + + /** If perform directed advertising */ unsigned int directed:1; + + /** If perform high-duty directed advertising */ unsigned int high_duty_directed:1; + + /** If use legacy PDUs for advertising */ unsigned int legacy_pdu:1; + + /** If perform anonymous advertising */ unsigned int anonymous:1; + + /** If include TX power in advertising PDU */ unsigned int include_tx_power:1; + + /** If enable scan request notification */ unsigned int scan_req_notif:1; + /** Minimum advertising interval in 0.625ms units, if 0 stack use sane + * defaults + */ uint32_t itvl_min; + + /** Maximum advertising interval in 0.625ms units, if 0 stack use sane + * defaults + */ uint32_t itvl_max; + + /** Advertising channel map , if 0 stack use sane defaults */ uint8_t channel_map; + + /** Own address type to be used by advertising instance */ uint8_t own_addr_type; + + /** Peer address for directed advertising, valid only if directed is set */ ble_addr_t peer; + + /** Advertising Filter policy */ uint8_t filter_policy; + + /** Primary advertising PHY to use , can be one of following constants: + * - BLE_HCI_LE_PHY_1M + * - BLE_HCI_LE_PHY_CODED + */ uint8_t primary_phy; + + /** Secondary advertising PHY to use, can be one of following constants: + * - BLE_HCI_LE_PHY_1M + * - LE_HCI_LE_PHY_2M + * - BLE_HCI_LE_PHY_CODED + */ uint8_t secondary_phy; + + /** Preferred advertiser transmit power */ int8_t tx_power; + + /** Advertising Set ID */ uint8_t sid; }; +/** + * Configure extended advertising instance + * + * @param instance Instance ID + * @param params Additional arguments specifying the particulars + * of the advertising. + * @param selected_tx_power Selected advertising transmit power will be + * stored in that param if non-NULL. + * @param cb The callback to associate with this advertising + * procedure. Advertising complete event is reported + * through this callback + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_ext_adv_configure(uint8_t instance, const struct ble_gap_ext_adv_params *params, int8_t *selected_tx_power, ble_gap_event_fn *cb, void *cb_arg); -int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr); -int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events); -int ble_gap_ext_adv_stop(uint8_t instance); -int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data); -int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data); -int ble_gap_ext_adv_remove(uint8_t instance); + /** - * Clear All existing extended Adv Sets. + * Set random address for configured advertising instance. + * + * @param instance Instance ID + * @param addr Random address to be set + * + * @return 0 on success; nonzero on failure. + */ +int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr); + +/** + * Start advertising instance. + * + * @param instance Instance ID + * @param duration The duration of the advertisement procedure. On + * expiration, the procedure ends and + * a BLE_HS_FOREVER event is reported. + * Units are milliseconds. Specify 0 for no + * expiration. + * @params max_events Number of advertising events that should be sent + * before advertising ends and + * a BLE_GAP_EVENT_ADV_COMPLETE event is reported. + * Specify 0 for no limit. + * + * @return 0 on success, error code on failure. + */ +int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events); + +/** + * Stops advertising procedure for specified instance. + * + * @param instance Instance ID + * + * @return 0 on success, BLE_HS_EALREADY if there is no active advertising + * procedure for instance, other error code on failure. + */ +int ble_gap_ext_adv_stop(uint8_t instance); + +/** + * Configures the data to include in advertisements packets for specified + * advertising instance. + * + * @param instance Instance ID + * @param data Chain containing the advertising data. + * + * @return 0 on success or error code on failure. + */ +int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data); + +/** + * Configures the data to include in subsequent scan responses for specified + * advertisign instance. + * + * @param instance Instance ID + * @param data Chain containing the scan response data. + * + * @return 0 on success or error code on failure. + */ + +int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data); + +/** + * Remove existing advertising instance. + * + * @param instance Instance ID + * + * @return 0 on success, + * BLE_HS_EBUSY if advertising is in progress, + * other error code on failure. + */ +int ble_gap_ext_adv_remove(uint8_t instance); + +/** + * Clear all existing advertising instances * @return 0 on success, * BLE_HS_EBUSY if advertising is in progress, * other error code on failure. @@ -970,34 +1254,151 @@ int ble_gap_ext_adv_clear(void); /* Periodic Advertising */ #if MYNEWT_VAL(BLE_PERIODIC_ADV) + +/** @brief Periodic advertising parameters */ struct ble_gap_periodic_adv_params { + /** If include TX power in advertising PDU */ unsigned int include_tx_power:1; + /** Minimum advertising interval in 0.625ms units, if 0 stack use sane + * defaults + */ uint16_t itvl_min; + + /** Maximum advertising interval in 0.625ms units, if 0 stack use sane + * defaults + */ uint16_t itvl_max; }; +/** @brief Periodic sync parameters */ struct ble_gap_periodic_sync_params { + /** The maximum number of periodic advertising events that controller can + * skip after a successful receive. + * */ uint16_t skip; + + /** Synchronization timeout for the periodic advertising train in 10ms units + */ uint16_t sync_timeout; }; +/** + * Configure periodic advertising for specified advertising instance + * + * This is allowed only for instances configured as non-announymous, + * non-connectable and non-scannable. + * + * @param instance Instance ID + * @param params Additional arguments specifying the particulars + * of periodic advertising. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_periodic_adv_configure(uint8_t instance, const struct ble_gap_periodic_adv_params *params); + +/** + * Start periodic advertising for specified advertising instance. + * + * @param instance Instance ID + * + * @return 0 on success, error code on failure. + */ int ble_gap_periodic_adv_start(uint8_t instance); + +/** + * Stop periodic advertising for specified advertising instance. + * + * @param instance Instance ID + * + * @return 0 on success, error code on failure. + */ int ble_gap_periodic_adv_stop(uint8_t instance); + +/** + * Configures the data to include in periodic advertisements for specified + * advertising instance. + * + * @param instance Instance ID + * @param data Chain containing the periodic advertising data. + * + * @return 0 on success or error code on failure. + */ int ble_gap_periodic_adv_set_data(uint8_t instance, struct os_mbuf *data); +/** + * Performs the Synchronization procedure with periodic advertiser. + * + * @param addr Peer address to synchronize with. If NULL than + * peers from periodic list are used. + * @param adv_sid Advertiser Set ID + * @param params Additional arguments specifying the particulars + * of the synchronization procedure. + * @param cb The callback to associate with this synchrnization + * procedure. BLE_GAP_EVENT_PERIODIC_REPORT events + * are reported only by this callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_periodic_adv_create_sync(const ble_addr_t *addr, uint8_t adv_sid, const struct ble_gap_periodic_sync_params *params, ble_gap_event_fn *cb, void *cb_arg); + +/** + * Cancel pending synchronization procedure. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_periodic_adv_create_sync_cancel(void); + +/** + * Terminate synchronization procedure. + * + * @param sync_handle Handle identifying synchronization to terminate. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_periodic_adv_terminate_sync(uint16_t sync_handle); + +/** + * Add peer device to periodic synchronization list. + * + * @param addr Peer address to add to list. + * @param adv_sid Advertiser Set ID + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_add_dev_to_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid); + +/** + * Remove peer device from periodic synchronization list. + * + * @param addr Peer address to remove from list. + * @param adv_sid Advertiser Set ID + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_rem_dev_from_periodic_adv_list(const ble_addr_t *peer_addr, uint8_t adv_sid); + +/** + * Clear periodic synchrnization list. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_clear_periodic_adv_list(void); + +/** + * Get periodic synchronization list size. + * + * @param per_adv_list_size On success list size is stored here. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_read_periodic_adv_list_size(uint8_t *per_adv_list_size); #endif @@ -1034,6 +1435,46 @@ int ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms, const struct ble_gap_disc_params *disc_params, ble_gap_event_fn *cb, void *cb_arg); +/** + * Performs the Limited or General Extended Discovery Procedures. + * + * @param own_addr_type The type of address the stack should use for + * itself when sending scan requests. Valid + * values are: + * - BLE_ADDR_TYPE_PUBLIC + * - BLE_ADDR_TYPE_RANDOM + * - BLE_ADDR_TYPE_RPA_PUB_DEFAULT + * - BLE_ADDR_TYPE_RPA_RND_DEFAULT + * This parameter is ignored unless active + * scanning is being used. + * @param duration The duration of the discovery procedure. + * On expiration, if period is set to 0, the + * procedure ends and a + * BLE_GAP_EVENT_DISC_COMPLETE event is + * reported. Units are 10 milliseconds. + * Specify 0 for no expiration. + * @param period Time interval from when the Controller started + * its last Scan Duration until it begins the + * subsequent Scan Duration. Specify 0 to scan + * continuously. Units are 1.28 second. + * @param limited If limited discovery procedure should be used. + * @param uncoded_params Additional arguments specifying the particulars + * of the discovery procedure for uncoded PHY. + * If NULL is provided no scan is performed for + * this PHY. + * @param coded_params Additional arguments specifying the particulars + * of the discovery procedure for coded PHY. + * If NULL is provided no scan is performed for + * this PHY. + * @param cb The callback to associate with this discovery + * procedure. Advertising reports and discovery + * termination events are reported through this + * callback. + * @param cb_arg The optional argument to pass to the callback + * function. + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_ext_disc(uint8_t own_addr_type, uint16_t duration, uint16_t period, uint8_t filter_duplicates, uint8_t filter_policy, uint8_t limited, @@ -1328,23 +1769,93 @@ int ble_gap_unpair_oldest_peer(void); #define BLE_GAP_PRIVATE_MODE_NETWORK 0 #define BLE_GAP_PRIVATE_MODE_DEVICE 1 + +/** + * Set privacy mode for specified peer device + * + * @param peer_addr Peer device address + * @param priv_mode Privacy mode to be used. Can be one of following + * constants: + * - BLE_GAP_PRIVATE_MODE_NETWORK + * - BLE_GAP_PRIVATE_MODE_DEVICE + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_set_priv_mode(const ble_addr_t *peer_addr, uint8_t priv_mode); #define BLE_GAP_LE_PHY_1M 1 #define BLE_GAP_LE_PHY_2M 2 #define BLE_GAP_LE_PHY_CODED 3 +/** + * Read PHYs used for specified connection. + * + * On success output parameters are filled with information about used PHY type. + * + * @param conn_handle Connection handle + * @param tx_phy TX PHY used. Can be one of following constants: + * - BLE_GAP_LE_PHY_1M + * - BLE_GAP_LE_PHY_2M + * - BLE_GAP_LE_PHY_CODED + * @param rx_phy RX PHY used. Can be one of following constants: + * - BLE_GAP_LE_PHY_1M + * - BLE_GAP_LE_PHY_2M + * - BLE_GAP_LE_PHY_CODED + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_read_le_phy(uint16_t conn_handle, uint8_t *tx_phy, uint8_t *rx_phy); #define BLE_GAP_LE_PHY_1M_MASK 0x01 #define BLE_GAP_LE_PHY_2M_MASK 0x02 #define BLE_GAP_LE_PHY_CODED_MASK 0x04 #define BLE_GAP_LE_PHY_ANY_MASK 0x0F +/** + * Set preferred default PHYs to be used for connections. + * + * @params tx_phys_mask Preferred TX PHY. Can be mask of following + * constants: + * - BLE_GAP_LE_PHY_1M_MASK + * - BLE_GAP_LE_PHY_2M_MASK + * - BLE_GAP_LE_PHY_CODED_MASK + * - BLE_GAP_LE_PHY_ANY_MASK + * @params rx_phys_mask Preferred RX PHY. Can be mask of following + * constants: + * - BLE_GAP_LE_PHY_1M_MASK + * - BLE_GAP_LE_PHY_2M_MASK + * - BLE_GAP_LE_PHY_CODED_MASK + * - BLE_GAP_LE_PHY_ANY_MASK + + * @return 0 on success; nonzero on failure. + */ int ble_gap_set_prefered_default_le_phy(uint8_t tx_phys_mask, uint8_t rx_phys_mask); #define BLE_GAP_LE_PHY_CODED_ANY 0 #define BLE_GAP_LE_PHY_CODED_S2 1 #define BLE_GAP_LE_PHY_CODED_S8 2 +/** + * Set preferred PHYs to be used for connection. + * + * @param conn_handle Connection handle + * @params tx_phys_mask Preferred TX PHY. Can be mask of following + * constants: + * - BLE_GAP_LE_PHY_1M_MASK + * - BLE_GAP_LE_PHY_2M_MASK + * - BLE_GAP_LE_PHY_CODED_MASK + * - BLE_GAP_LE_PHY_ANY_MASK + * @params rx_phys_mask Preferred RX PHY. Can be mask of following + * constants: + * - BLE_GAP_LE_PHY_1M_MASK + * - BLE_GAP_LE_PHY_2M_MASK + * - BLE_GAP_LE_PHY_CODED_MASK + * - BLE_GAP_LE_PHY_ANY_MASK + * @param phy_opts Additional PHY options. Valid values are: + * - BLE_GAP_LE_PHY_CODED_ANY + * - BLE_GAP_LE_PHY_CODED_S2 + * - BLE_GAP_LE_PHY_CODED_S8 + * + * @return 0 on success; nonzero on failure. + */ int ble_gap_set_prefered_le_phy(uint16_t conn_handle, uint8_t tx_phys_mask, uint8_t rx_phys_mask, uint16_t phy_opts);