Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
bluetooth: fast_pair: introduce Fast Pair advertising manager
Added the new Fast Pair advertising manager module to to the Google Fast Pair subsystem. The new module is used by the Fast Pair Locator Tag sample. Ref: NCSDK-30487 Signed-off-by: Kamil Piszczek <[email protected]>
- Loading branch information
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,206 @@ | ||
| /* | ||
| * Copyright (c) 2025 Nordic Semiconductor ASA | ||
| * | ||
| * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause | ||
| */ | ||
|
|
||
| #ifndef BT_FAST_PAIR_ADV_MANAGER_H_ | ||
| #define BT_FAST_PAIR_ADV_MANAGER_H_ | ||
|
|
||
| #include <stdint.h> | ||
|
|
||
| #include <zephyr/sys/slist.h> | ||
| #include <bluetooth/services/fast_pair/fast_pair.h> | ||
|
|
||
| /** | ||
| * @defgroup bt_fast_pair_adv_manager Fast Pair Advertising Manager API | ||
| * @brief Fast Pair Advertising Manager API for managing the Fast Pair advertising set | ||
| * | ||
| * It is required to use the Fast Pair Advertising Manager API in the cooperative thread | ||
| * context. Following this requirement guarantees a proper synchronization between the | ||
| * user operations and the module operations. | ||
| * | ||
| * @{ | ||
| */ | ||
|
|
||
| #ifdef __cplusplus | ||
| extern "C" { | ||
| #endif | ||
|
|
||
| /** Fast Pair Advertising Manager trigger. */ | ||
| struct bt_fast_pair_adv_manager_trigger { | ||
| /** Identifier. */ | ||
| const char *id; | ||
| }; | ||
|
|
||
| /** @brief Register a trigger in the Fast Pair Advertising Manager. | ||
| * | ||
| * @param _name Trigger structure name. | ||
| * @param _id Trigger identifier. | ||
| */ | ||
| #define BT_FAST_PAIR_ADV_MANAGER_TRIGGER_REGISTER(_name, _id) \ | ||
| BUILD_ASSERT(_id != NULL); \ | ||
| static STRUCT_SECTION_ITERABLE(bt_fast_pair_adv_manager_trigger, _name) = { \ | ||
| .id = _id, \ | ||
| } | ||
|
|
||
| /** @brief Request turning on the Fast Pair advertising. | ||
| * | ||
| * The Fast Pair advertising will be turned off only when no trigger has requested to keep | ||
| * the Fast Pair advertising on. | ||
| * | ||
| * If the current Fast Pair Advertising Manager mode is the same as the requested mode, the | ||
| * advertising payload will not be refreshed. Use the | ||
| * @ref bt_fast_pair_adv_manager_payload_refresh function to manually refresh the Fast Pair | ||
| * advertising payload. | ||
| * | ||
| * @param trigger Trigger identifier. | ||
| * @param enable true to request to turn on the Fast Pair advertising. | ||
| * false to remove request to turn on the Fast Pair advertising. | ||
| */ | ||
| void bt_fast_pair_adv_manager_request(struct bt_fast_pair_adv_manager_trigger *trigger, | ||
| bool enable); | ||
|
|
||
| /** @brief Refresh the Fast Pair advertising payload. | ||
| * | ||
| * This function is used to manually trigger the refreshing of the Fast Pair advertising data | ||
| * to ensure that the advertising data is up to date. | ||
| * | ||
| * Use with caution, as it updates the Fast Pair advertising payload asynchronously | ||
| * to the RPA address rotation and to the update of other active advertising sets (e. g. FMDN | ||
| * advertising set). | ||
| */ | ||
| void bt_fast_pair_adv_manager_payload_refresh(void); | ||
|
|
||
| /** @brief Set the Fast Pair advertising mode. | ||
| * | ||
| * This function set the Fast Pair advertising mode. If the Fast Pair advertising is active, | ||
| * this function will not update the advertising payload until the next RPA rotation. If | ||
| * necessary, the @ref bt_fast_pair_adv_manager_payload_refresh function can be used to update | ||
| * the Fast Pair advertising payload immediately. | ||
| * | ||
| * The advertising manager implementation tailored for the specific use case with the @kconfig | ||
| * @kconfig{CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE} Kconfig choice may not support this API | ||
| * function for certain use cases (@kconfig{CONFIG_BT_FAST_PAIR_ADV_MANAGER_USE_CASE_LOCATOR_TAG} | ||
| * Kconfig option is an example). | ||
| * | ||
| * @param mode the new Fast Pair advertising mode. | ||
| * | ||
| * @return 0 if the operation was successful. Otherwise, a (negative) error code is returned. | ||
| */ | ||
| int bt_fast_pair_adv_manager_mode_set(enum bt_fast_pair_adv_mode mode); | ||
|
|
||
| /** @brief Get the current Fast Pair advertising mode. | ||
| * | ||
| * By default, the Fast Pair advertising mode is set to @ref BT_FAST_PAIR_ADV_MODE_DISC. | ||
| * | ||
| * @return Current Fast Pair advertising mode. | ||
| */ | ||
| enum bt_fast_pair_adv_mode bt_fast_pair_adv_manager_mode_get(void); | ||
|
|
||
| /** @brief Set the Bluetooth identity for the Fast Pair advertising. | ||
| * | ||
| * This identity shall be created with the bt_id_create function that is available in the | ||
| * Bluetooth API. You can only set the Bluetooth identity when the Fast Pair Advertising | ||
| * Manager module is disabled. If you do not explicitly set the identity with this API call, | ||
| * the BT_ID_DEFAULT identity is used. | ||
| * | ||
| * @param id Bluetooth identity for the Fast Pair advertising. | ||
| * | ||
| * @return 0 if the operation was successful. Otherwise, a (negative) error code is returned. | ||
| */ | ||
| int bt_fast_pair_adv_manager_id_set(uint8_t id); | ||
|
|
||
| /** @brief Get the Bluetooth identity used for the Fast Pair advertising. | ||
| * | ||
| * @return Bluetooth identity for the Fast Pair advertising. | ||
| */ | ||
| uint8_t bt_fast_pair_adv_manager_id_get(void); | ||
|
|
||
| /** Information callback descriptor for the Fast Pair Advertising Manager. */ | ||
| struct bt_fast_pair_adv_manager_info_cb { | ||
| /** Notify that the advertising state has changed. | ||
| * | ||
| * This information callback is used to track the state of the Fast Pair advertising set. | ||
| * The current state can be used to signal the application mode in the user interface | ||
| * (for example, on LEDs). | ||
| * | ||
| * The @ref bt_fast_pair_adv_manager_is_adv_active API function can be used to | ||
| * synchronously check the state of the Fast Pair advertising set. | ||
| * | ||
| * @param active True: Fast Pair advertising is active. | ||
| * False: Fast Pair advertising is inactive. | ||
| */ | ||
| void (*adv_state_changed)(bool active); | ||
|
|
||
| /** Internally used field for list handling. */ | ||
| sys_snode_t node; | ||
| }; | ||
|
|
||
| /** @brief Register information callbacks for the Fast Pair Advertising Manager. | ||
| * | ||
| * This function registers an instance of information callbacks. The registered instance needs | ||
| * to persist in the memory after this function exits, as it is used directly without the copy | ||
| * operation. | ||
| * | ||
| * This function can only be called before enabling the Fast Pair Advertising Manager module | ||
| * with the @ref bt_fast_pair_adv_manager_enable API. | ||
| * | ||
| * @param cb Callback struct. | ||
| * | ||
| * @return Zero on success or negative error code otherwise | ||
| */ | ||
| int bt_fast_pair_adv_manager_info_cb_register(struct bt_fast_pair_adv_manager_info_cb *cb); | ||
|
|
||
| /** @brief Check if the Fast Pair advertising set is active. | ||
| * | ||
| * This function can be used to synchronously check if the FP advertising set is currently being | ||
| * advertised. To track the advertising state asynchronously, use the @ref state_changed callback | ||
| * that is part of the @ref bt_fast_pair_adv_manager_info_cb structure. | ||
| * | ||
| * @return Current Fast Pair advertising mode. | ||
| */ | ||
| bool bt_fast_pair_adv_manager_is_adv_active(void); | ||
|
|
||
| /** @brief Enable the Fast Pair Advertising Manager module. | ||
| * | ||
| * This function enables the Fast Pair Advertising Manager module. If any trigger is enabled | ||
| * with the @ref bt_fast_pair_adv_manager_request function, the module activates the Fair Pair | ||
| * advertising in the context of this function. | ||
| * | ||
| * This API must be called when the Fast Pair subsystem is ready (see the @ref | ||
| * bt_fast_pair_is_ready function). | ||
| * | ||
| * @return 0 if the operation was successful. Otherwise, a (negative) error code is returned. | ||
| */ | ||
| int bt_fast_pair_adv_manager_enable(void); | ||
|
|
||
| /** @brief Disable the Fast Pair Advertising Manager module. | ||
| * | ||
| * This function disables the Fast Pair Advertising Manager module. If the Fast Pair advertising | ||
| * is active, the module stops the advertising activity in the context of this function. If there | ||
| * is any pending Fast Pair connection, the module attempts to terminate this connection in the | ||
| * context of this function. | ||
| * | ||
| * This API should be called before the Fast Pair subsystem gets disable (see the @ref | ||
| * bt_fast_pair_disable function). | ||
| * | ||
| * @return 0 if the operation was successful. Otherwise, a (negative) error code is returned. | ||
| */ | ||
| int bt_fast_pair_adv_manager_disable(void); | ||
|
|
||
| /** @brief Check if the Fast Pair Advertising Manager module is ready. | ||
| * | ||
| * @return true when the module is ready, false otherwise. | ||
| */ | ||
| bool bt_fast_pair_adv_manager_is_ready(void); | ||
|
|
||
| #ifdef __cplusplus | ||
| } | ||
| #endif | ||
|
|
||
| /** | ||
| * @} | ||
| */ | ||
|
|
||
| #endif /* BT_FAST_PAIR_ADV_MANAGER_H_ */ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.