From 0a19c18f8534937023946a5c252dfcd81d99c562 Mon Sep 17 00:00:00 2001 From: Rubin Gerritsen Date: Thu, 25 Apr 2024 10:36:35 +0200 Subject: [PATCH] Bluetooth: Host: Document bt_le_scan_update() This function is used in many places, but just by reading its name it is not obvious why it is needed. By adding some documentation it will hopefully become a bit more clear that this function is mainly used for auto connection establishment. Signed-off-by: Rubin Gerritsen --- subsys/bluetooth/host/hci_core.h | 23 +++++++++++++++++++++++ subsys/bluetooth/host/scan.c | 5 +++++ 2 files changed, 28 insertions(+) diff --git a/subsys/bluetooth/host/hci_core.h b/subsys/bluetooth/host/hci_core.h index 22710648207..1484cc550ba 100644 --- a/subsys/bluetooth/host/hci_core.h +++ b/subsys/bluetooth/host/hci_core.h @@ -468,6 +468,29 @@ uint8_t bt_get_phy(uint8_t hci_phy); * @return CTE type (@ref bt_df_cte_type). */ int bt_get_df_cte_type(uint8_t hci_cte_type); + +/** Start or restart scanner if needed + * + * Examples of cases where it may be required to start/restart a scanner: + * - When the auto-connection establishement feature is used: + * - When the host sets a connection context for auto-connection establishment. + * - When a connection was established. + * The host may now be able to retry to automatically set up a connection. + * - When a connection was disconnected/lost. + * The host may now be able to retry to automatically set up a connection. + * - When the application stops explicit scanning. + * The host may now be able to retry to automatically set up a connection. + * - The application tries to connect to another device, but fails. + * The host may now be able to retry to automatically set up a connection. + * - When the application wants to connect to a device, but we need + * to fallback to host privacy. + * - When the application wants to establish a periodic sync to a device + * and the application has not already started scanning. + * + * @param fast_scan Use fast scan parameters or slow scan parameters + * + * @return 0 in case of success, or a negative error code on failure. + */ int bt_le_scan_update(bool fast_scan); int bt_le_create_conn(const struct bt_conn *conn); diff --git a/subsys/bluetooth/host/scan.c b/subsys/bluetooth/host/scan.c index baee591f1e9..5836bad2fb7 100644 --- a/subsys/bluetooth/host/scan.c +++ b/subsys/bluetooth/host/scan.c @@ -318,6 +318,9 @@ static int start_passive_scan(bool fast_scan) int bt_le_scan_update(bool fast_scan) { if (atomic_test_bit(bt_dev.flags, BT_DEV_EXPLICIT_SCAN)) { + /* The application has already explicitly started scanning. + * We should keep the scanner running to avoid changing scan parameters. + */ return 0; } @@ -348,12 +351,14 @@ int bt_le_scan_update(bool fast_scan) bt_conn_unref(conn); + /* Start/Restart the scanner */ return start_passive_scan(fast_scan); } } #if defined(CONFIG_BT_PER_ADV_SYNC) if (get_pending_per_adv_sync()) { + /* Start/Restart the scanner. */ return start_passive_scan(fast_scan); } #endif