Bluetooth: CAP: Implement unicast to broadcast handover

Implement the unicast to broadcast handover procedure,
as per the Bluetooth CAP specificiation.

Signed-off-by: Emil Gydesen <[email protected]>

Author: Thalley

include/zephyr/bluetooth/audio/cap.h

@@ -812,55 +812,99 @@ int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broa
 int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcast_source,
 					struct net_buf_simple *base_buf);
 
-/** Parameters for  bt_cap_initiator_unicast_to_broadcast() */
-struct bt_cap_unicast_to_broadcast_param {
+/** Parameters for  bt_cap_handover_unicast_to_broadcast() */
+struct bt_cap_handover_unicast_to_broadcast_param {
+	/** The type of the set. */
+	enum bt_cap_set_type type;
+
 	/** The source unicast group with the streams. */
-	struct bt_bap_unicast_group *unicast_group;
+	struct bt_cap_unicast_group *unicast_group;
 
 	/**
-	 * @brief Whether or not to encrypt the streams.
+	 * @brief The advertising set to use for the broadcast source
 	 *
-	 * If set to true, then the broadcast code in @p broadcast_code
-	 * will be used to encrypt the streams.
+	 * This shall remain valid until the procedure has completed.
+	 * If the advertising set is not started at the time of calling
+	 * bt_cap_handover_unicast_to_broadcast(),
+	 * the procedure will start the advertising set with @ref BT_LE_EXT_ADV_START_DEFAULT.
 	 */
-	bool encrypt;
+	struct bt_le_ext_adv *ext_adv;
+
+	/** The SID of the advertising set. */
+	uint8_t sid;
+
+	/** The periodic advertising interval configured for the advertising set. */
+	uint16_t pa_interval;
+
+	/** The broadcast ID the advertising set is, or will be, using. */
+	uint32_t broadcast_id;
 
 	/**
-	 * @brief 16-octet broadcast code.
-	 *
-	 * Only valid if @p encrypt is true.
+	 * @brief Broadcast source parameters.
 	 *
-	 * If the value is a string or a the value is less than 16 octets,
-	 * the remaining octets shall be 0.
+	 * These parameters shall remain valid until the procedure has completed.
+	 */
+	struct bt_cap_initiator_broadcast_create_param *broadcast_create_param;
+};
+
+/** Callback structure for CAP procedures */
+struct bt_cap_handover_cb {
+	/**
+	 * @brief The unicast to broadcast handover procedure has finished
 	 *
-	 * Example:
-	 *   The string "Broadcast Code" shall be
-	 *   [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
+	 * @param err 0 if success else a negative errno value.
+	 * @param conn Pointer to the connection where the error occurred or NULL if local failure.
+	 * @param unicast_group NULL if the unicast group was deleted during the procedure, else
+	 *                      pointer to the unicast group provided in the parameters.
+	 * @param broadcast_source Pointer to newly created broadcast source, or NULL in case of an
+	 *                         error happening before it was created.
 	 */
-	uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
+	void (*unicast_to_broadcast_complete)(int err, struct bt_conn *conn,
+					      struct bt_cap_unicast_group *unicast_group,
+					      struct bt_cap_broadcast_source *broadcast_source);
 };
 
 /**
- * @brief Hands over the data streams in a unicast group to a broadcast source.
+ * @brief Register Common Audio Profile Handover callbacks
  *
- * The streams in the unicast group will be stopped and the unicast group
- * will be deleted. This can only be done for source streams.
+ * @param cb   The callback structure. Shall remain static.
  *
- * @note @kconfig{CONFIG_BT_CAP_INITIATOR},
- * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and
- * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
- * to be enabled.
+ * @return 0 on success or negative error value on failure.
+ */
+int bt_cap_handover_register_cb(const struct bt_cap_handover_cb *cb);
+
+/**
+ * @brief Unregister Common Audio Profile Handover callbacks
  *
- * @param param         The parameters for the handover.
- * @param source        The resulting broadcast source.
+ * @param cb   The callback structure that was previously registered.
+ *
+ * @retval 0 Success
+ * @retval -EINVAL @p cb is NULL or @p cb was not registered
+ */
+int bt_cap_handover_unregister_cb(const struct bt_cap_handover_cb *cb);
+
+/**
+ * @brief Hands over the sink streams in a unicast group to a broadcast source.
+ *
+ * All streams in the provided unicast group will be stopped and released. The sink streams will be
+ * tranferred to a broadcast source, and the broadcast source information will be shared with
+ * all accepters that are currently receiving audio. Any stream that is not in the streaming state
+ * will only be released.
+ *
+ * bt_bap_broadcast_assistant_discover() must have been successfully perform for all members in @p
+ * param before starting this procedure.
+ *
+ * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
+ *
+ * @param param The parameters for the handover.
  *
  * @return 0 on success or negative error value on failure.
  */
-int bt_cap_initiator_unicast_to_broadcast(const struct bt_cap_unicast_to_broadcast_param *param,
-					  struct bt_cap_broadcast_source **source);
+int bt_cap_handover_unicast_to_broadcast(
+	const struct bt_cap_handover_unicast_to_broadcast_param *param);
 
-/** Parameters for  bt_cap_initiator_broadcast_to_unicast() */
-struct bt_cap_broadcast_to_unicast_param {
+/** Parameters for  bt_cap_handover_broadcast_to_unicast() */
+struct bt_cap_handover_broadcast_to_unicast_param {
 	/**
 	 * @brief The source broadcast source with the streams.
 	 *
@@ -890,18 +934,16 @@ struct bt_cap_broadcast_to_unicast_param {
  * The streams in the broadcast source will be stopped and the broadcast source
  * will be deleted.
  *
- * @note @kconfig{CONFIG_BT_CAP_INITIATOR},
- * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and
- * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
- * to be enabled.
+ * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
  *
  * @param[in]  param          The parameters for the handover.
  * @param[out] unicast_group  The resulting broadcast source.
  *
  * @return 0 on success or negative error value on failure.
  */
-int bt_cap_initiator_broadcast_to_unicast(const struct bt_cap_broadcast_to_unicast_param *param,
-					  struct bt_bap_unicast_group **unicast_group);
+int bt_cap_handover_broadcast_to_unicast(
+	const struct bt_cap_handover_broadcast_to_unicast_param *param,
+	struct bt_bap_unicast_group **unicast_group);
 
 /** Callback structure for CAP procedures */
 struct bt_cap_commander_cb {

subsys/bluetooth/Kconfig.logging

@@ -213,6 +213,12 @@ module-str = "Common Audio Profile Commander"
 source "subsys/logging/Kconfig.template.log_config_inherit"
 endif # BT_CAP_COMMANDER
 
+if BT_CAP_HANDOVER
+module = BT_CAP_HANDOVER
+module-str = "Common Audio Profile Handover"
+source "subsys/logging/Kconfig.template.log_config_inherit"
+endif # BT_CAP_HANDOVER
+
 if BT_AUDIO
 module = BT_CAP_COMMON
 module-str = "Common Audio Profile Common"

subsys/bluetooth/audio/CMakeLists.txt

@@ -66,6 +66,7 @@ zephyr_library_sources_ifdef(CONFIG_BT_CAP cap_stream.c)
 zephyr_library_sources_ifdef(CONFIG_BT_CAP_ACCEPTOR cap_acceptor.c)
 zephyr_library_sources_ifdef(CONFIG_BT_CAP_INITIATOR cap_initiator.c)
 zephyr_library_sources_ifdef(CONFIG_BT_CAP_COMMANDER cap_commander.c)
+zephyr_library_sources_ifdef(CONFIG_BT_CAP_HANDOVER cap_handover.c)
 if (CONFIG_BT_CAP_INITIATOR_UNICAST OR CONFIG_BT_CAP_COMMANDER)
 	zephyr_library_sources(cap_common.c)
 endif()

subsys/bluetooth/audio/Kconfig.cap

@@ -48,3 +48,11 @@ config BT_CAP_COMMANDER
 		   BT_MCC
 	help
 	  Enabling this will enable the CAP Initiator role.
+
+config BT_CAP_HANDOVER
+	bool "Common Audio Profile Handover Procedures"
+	depends on BT_CAP_COMMANDER && BT_CAP_INITIATOR && BT_BAP_BROADCAST_ASSISTANT && \
+		   BT_BAP_BROADCAST_SOURCE && BT_BAP_UNICAST_CLIENT_ASE_SNK_COUNT > 0
+	help
+	  Enable support for the CAP Handover procedures, allowing a device to switch between
+	  broadcast and unicast for a usecase.

subsys/bluetooth/audio/cap_commander.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022-2023 Nordic Semiconductor ASA
+ * Copyright (c) 2022-2025 Nordic Semiconductor ASA
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -28,6 +28,7 @@
 #include <zephyr/sys/__assert.h>
 #include <zephyr/sys/check.h>
 #include <zephyr/sys/util.h>
+#include <zephyr/sys/util_macro.h>
 
 #include "audio_internal.h"
 #include "bap_endpoint.h"
@@ -325,7 +326,7 @@ static bool valid_broadcast_reception_start_param(
 	return true;
 }
 
-int bt_cap_commander_broadcast_reception_start(
+int cap_commander_broadcast_reception_start(
 	const struct bt_cap_commander_broadcast_reception_start_param *param)
 {
 	struct bt_bap_broadcast_assistant_add_src_param add_src_param = {0};
@@ -334,16 +335,6 @@ int bt_cap_commander_broadcast_reception_start(
 	struct bt_conn *conn;
 	int err;
 
-	if (!valid_broadcast_reception_start_param(param)) {
-		return -EINVAL;
-	}
-
-	if (bt_cap_common_test_and_set_proc_active()) {
-		LOG_DBG("A CAP procedure is already in progress");
-
-		return -EBUSY;
-	}
-
 	broadcast_assistant_cb.add_src = cap_commander_broadcast_assistant_add_src_cb;
 	if (!broadcast_assistant_cb_registered) {
 		err = cap_commander_register_broadcast_assistant_cb();
@@ -406,6 +397,22 @@ int bt_cap_commander_broadcast_reception_start(
 	return 0;
 }
 
+int bt_cap_commander_broadcast_reception_start(
+	const struct bt_cap_commander_broadcast_reception_start_param *param)
+{
+	if (!valid_broadcast_reception_start_param(param)) {
+		return -EINVAL;
+	}
+
+	if (bt_cap_common_test_and_set_proc_active()) {
+		LOG_DBG("A CAP procedure is already in progress");
+
+		return -EBUSY;
+	}
+
+	return cap_commander_broadcast_reception_start(param);
+}
+
 static void
 copy_broadcast_reception_stop_param(struct bt_bap_broadcast_assistant_mod_src_param *mod_src_param,
 				    struct cap_broadcast_reception_stop *stop_param)
@@ -875,6 +882,18 @@ static void cap_commander_proc_complete(void)
 	failed_conn = active_proc->failed_conn;
 	err = active_proc->err;
 	proc_type = active_proc->proc_type;
+
+	if (IS_ENABLED(CONFIG_BT_CAP_HANDOVER) && bt_cap_common_handover_is_active()) {
+		/* Complete handover procedure. At this point we do not know if the remote
+		 * device will attempt to use PAST or scan for itself, so it's best to leave
+		 * this up to the application layer
+		 */
+		__ASSERT_NO_MSG(proc_type == BT_CAP_COMMON_PROC_TYPE_BROADCAST_RECEPTION_START);
+
+		bt_cap_handover_proc_complete();
+		return;
+	}
+
 	bt_cap_common_clear_active_proc();
 
 	if (cap_cb == NULL) {

subsys/bluetooth/audio/cap_common.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023-2024 Nordic Semiconductor ASA
+ * Copyright (c) 2023-2025 Nordic Semiconductor ASA
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -21,6 +21,7 @@
 #include <zephyr/sys/atomic.h>
 #include <zephyr/sys/check.h>
 #include <zephyr/sys/util.h>
+#include <zephyr/sys/util_macro.h>
 
 #include "cap_internal.h"
 #include "csip_internal.h"
@@ -74,6 +75,18 @@ bool bt_cap_common_subproc_is_type(enum bt_cap_common_subproc_type subproc_type)
 }
 #endif /* CONFIG_BT_CAP_INITIATOR_UNICAST */
 
+#if defined(CONFIG_BT_CAP_HANDOVER)
+void bt_cap_common_set_handover_active(void)
+{
+	atomic_set_bit(active_proc.proc_state_flags, BT_CAP_COMMON_PROC_STATE_HANDOVER);
+}
+
+bool bt_cap_common_handover_is_active(void)
+{
+	return atomic_test_bit(active_proc.proc_state_flags, BT_CAP_COMMON_PROC_STATE_HANDOVER);
+}
+#endif /* CONFIG_BT_CAP_HANDOVER */
+
 struct bt_conn *bt_cap_common_get_member_conn(enum bt_cap_set_type type,
 					      const union bt_cap_set_member *member)
 {