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 <emil.gydesen@nordicsemi.no>

Author: Thalley

include/zephyr/bluetooth/audio/bap.h

@@ -1720,6 +1720,32 @@ int bt_bap_unicast_group_add_streams(struct bt_bap_unicast_group *unicast_group,
  */
 int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group);
 
+/** Callback function for bt_bap_unicast_group_foreach_stream()
+ *
+ * @param stream     The audio stream
+ * @param user_data  User data
+ *
+ * @retval true Stop iterating.
+ * @retval false Continue iterating.
+ */
+typedef bool (*bt_bap_unicast_group_foreach_stream_func_t)(struct bt_bap_stream *stream,
+							   void *user_data);
+
+/**
+ * @brief Iterate through all streams in a unicast group
+ *
+ * @param unicast_group  The unicast group
+ * @param func           The callback function
+ * @param user_data      User specified data that sent to the callback function
+ *
+ * @retval 0 Success (even if no streams exists in the group).
+ * @retval -ECANCELED Iteration was stopped by the callback function before complete.
+ * @retval -EINVAL @p unicast_group or @p func were NULL.
+ */
+int bt_bap_unicast_group_foreach_stream(struct bt_bap_unicast_group *unicast_group,
+					bt_bap_unicast_group_foreach_stream_func_t func,
+					void *user_data);
+
 /** Unicast Client callback structure */
 struct bt_bap_unicast_client_cb {
 	/**

include/zephyr/bluetooth/audio/cap.h

@@ -147,6 +147,12 @@ struct bt_cap_initiator_cb {
 	 */
 	void (*broadcast_stopped)(struct bt_cap_broadcast_source *source, uint8_t reason);
 #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE */
+#if defined(CONFIG_BT_CAP_HANDOVER_SUPPORTED)
+	/**
+	 * @brief The unicast to broadcast handover procedure has finished
+	 */
+	void (*unicast_to_broadcast_complete)(int err, struct bt_conn *conn);
+#endif /* CONFIG_BT_CAP_HANDOVER_SUPPORTED */
 };
 
 /**
@@ -398,6 +404,32 @@ int bt_cap_unicast_group_add_streams(struct bt_cap_unicast_group *unicast_group,
  */
 int bt_cap_unicast_group_delete(struct bt_cap_unicast_group *unicast_group);
 
+/** Callback function for bt_bap_unicast_group_foreach_stream()
+ *
+ * @param stream     The audio stream
+ * @param user_data  User data
+ *
+ * @retval true Stop iterating.
+ * @retval false Continue iterating.
+ */
+typedef bool (*bt_cap_unicast_group_foreach_stream_func_t)(struct bt_cap_stream *stream,
+							   void *user_data);
+
+/**
+ * @brief Iterate through all streams in a unicast group
+ *
+ * @param unicast_group  The unicast group
+ * @param func           The callback function
+ * @param user_data      User specified data that sent to the callback function
+ *
+ * @retval 0 Success (even if no streams exists in the group).
+ * @retval -ECANCELED Iteration was stopped by the callback function before complete.
+ * @retval -EINVAL @p unicast_group or @p func were NULL.
+ */
+int bt_cap_unicast_group_foreach_stream(struct bt_cap_unicast_group *unicast_group,
+					bt_cap_unicast_group_foreach_stream_func_t func,
+					void *user_data);
+
 /** Stream specific parameters for the bt_cap_initiator_unicast_audio_start() function */
 struct bt_cap_unicast_audio_start_stream_param {
 	/** Coordinated or ad-hoc set member. */
@@ -788,30 +820,30 @@ int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcas
 
 /** Parameters for  bt_cap_initiator_unicast_to_broadcast() */
 struct bt_cap_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.
 	 */
-	bool encrypt;
+	/* TBD: Is this necessary? Should we, or the app, start the source? */
+	struct bt_le_ext_adv *ext_adv;
+
+	uint8_t sid;
+	uint16_t pa_interval;
+	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.
-	 *
-	 * Example:
-	 *   The string "Broadcast Code" shall be
-	 *   [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
+	 * These parameters shall remain valid until the procedure has completed.
 	 */
-	uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
+	struct bt_cap_initiator_broadcast_create_param *broadcast_create_param;
 };
 
 /**
@@ -820,10 +852,7 @@ struct bt_cap_unicast_to_broadcast_param {
  * The streams in the unicast group will be stopped and the unicast group
  * will be deleted. This can only be done for source streams.
  *
- * @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_SUPPORTED}
  *
  * @param param         The parameters for the handover.
  * @param source        The resulting broadcast source.
@@ -864,10 +893,7 @@ 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_SUPPORTED}
  *
  * @param[in]  param          The parameters for the handover.
  * @param[out] unicast_group  The resulting broadcast source.

subsys/bluetooth/audio/Kconfig.cap

@@ -48,3 +48,7 @@ config BT_CAP_COMMANDER
 		   BT_MCC
 	help
 	  Enabling this will enable the CAP Initiator role.
+
+config BT_CAP_HANDOVER_SUPPORTED
+	def_bool BT_CAP_COMMANDER && BT_CAP_INITIATOR && BT_BAP_BROADCAST_ASSISTANT && \
+		 BT_BAP_BROADCAST_SOURCE && BT_BAP_UNICAST_CLIENT

subsys/bluetooth/audio/bap_unicast_client.c

@@ -3143,6 +3143,33 @@ int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group)
 	return 0;
 }
 
+int bt_bap_unicast_group_foreach_stream(struct bt_bap_unicast_group *unicast_group,
+					bt_bap_unicast_group_foreach_stream_func_t func,
+					void *user_data)
+{
+	struct bt_bap_stream *stream, *next;
+
+	if (unicast_group == NULL) {
+		LOG_DBG("unicast_group is NULL");
+		return -EINVAL;
+	}
+
+	if (func == NULL) {
+		LOG_DBG("func is NULL");
+		return -EINVAL;
+	}
+
+	SYS_SLIST_FOR_EACH_CONTAINER_SAFE(&unicast_group->streams, stream, next, _node) {
+		const bool stop = func(stream, user_data);
+
+		if (stop) {
+			return -ECANCELED;
+		}
+	}
+
+	return 0;
+}
+
 int bt_bap_unicast_client_config(struct bt_bap_stream *stream,
 				 const struct bt_audio_codec_cfg *codec_cfg)
 {

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
  */
@@ -338,7 +338,7 @@ int bt_cap_commander_broadcast_reception_start(
 		return -EINVAL;
 	}
 
-	if (bt_cap_common_test_and_set_proc_active()) {
+	if (bt_cap_common_test_and_set_proc_active() && !bt_cap_common_handover_is_active()) {
 		LOG_DBG("A CAP procedure is already in progress");
 
 		return -EBUSY;
@@ -798,7 +798,7 @@ int bt_cap_commander_distribute_broadcast_code(
 		return -EINVAL;
 	}
 
-	if (bt_cap_common_test_and_set_proc_active()) {
+	if (bt_cap_common_test_and_set_proc_active() && !bt_cap_common_handover_is_active()) {
 		LOG_DBG("A CAP procedure is already in progress");
 
 		return -EBUSY;
@@ -868,66 +868,74 @@ int bt_cap_commander_distribute_broadcast_code(
 static void cap_commander_proc_complete(void)
 {
 	struct bt_cap_common_proc *active_proc = bt_cap_common_get_active_proc();
+	const bool is_handover = bt_cap_common_handover_is_active();
 	enum bt_cap_common_proc_type proc_type;
 	struct bt_conn *failed_conn;
 	int err;
 
 	failed_conn = active_proc->failed_conn;
 	err = active_proc->err;
 	proc_type = active_proc->proc_type;
-	bt_cap_common_clear_active_proc();
 
-	if (cap_cb == NULL) {
+	if (is_handover && err != 0) {
+		bt_cap_handover_proc_complete();
 		return;
+	} else if (!is_handover) {
+		bt_cap_common_clear_active_proc();
 	}
 
 	switch (proc_type) {
 #if defined(CONFIG_BT_VCP_VOL_CTLR)
 	case BT_CAP_COMMON_PROC_TYPE_VOLUME_CHANGE:
-		if (cap_cb->volume_changed != NULL) {
+		if (cap_cb != NULL && cap_cb->volume_changed != NULL) {
 			cap_cb->volume_changed(failed_conn, err);
 		}
 		break;
 	case BT_CAP_COMMON_PROC_TYPE_VOLUME_MUTE_CHANGE:
-		if (cap_cb->volume_mute_changed != NULL) {
+		if (cap_cb != NULL && cap_cb->volume_mute_changed != NULL) {
 			cap_cb->volume_mute_changed(failed_conn, err);
 		}
 		break;
 #if defined(CONFIG_BT_VCP_VOL_CTLR_VOCS)
 	case BT_CAP_COMMON_PROC_TYPE_VOLUME_OFFSET_CHANGE:
-		if (cap_cb->volume_offset_changed != NULL) {
+		if (cap_cb != NULL && cap_cb->volume_offset_changed != NULL) {
 			cap_cb->volume_offset_changed(failed_conn, err);
 		}
 		break;
 #endif /* CONFIG_BT_VCP_VOL_CTLR_VOCS */
 #endif /* CONFIG_BT_VCP_VOL_CTLR */
 #if defined(CONFIG_BT_MICP_MIC_CTLR)
 	case BT_CAP_COMMON_PROC_TYPE_MICROPHONE_MUTE_CHANGE:
-		if (cap_cb->microphone_mute_changed != NULL) {
+		if (cap_cb != NULL && cap_cb->microphone_mute_changed != NULL) {
 			cap_cb->microphone_mute_changed(failed_conn, err);
 		}
 		break;
 #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS)
 	case BT_CAP_COMMON_PROC_TYPE_MICROPHONE_GAIN_CHANGE:
-		if (cap_cb->microphone_gain_changed != NULL) {
+		if (cap_cb != NULL && cap_cb->microphone_gain_changed != NULL) {
 			cap_cb->microphone_gain_changed(failed_conn, err);
 		}
 		break;
 #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */
 #endif /* CONFIG_BT_MICP_MIC_CTLR */
 #if defined(CONFIG_BT_BAP_BROADCAST_ASSISTANT)
 	case BT_CAP_COMMON_PROC_TYPE_BROADCAST_RECEPTION_START:
-		if (cap_cb->broadcast_reception_start != NULL) {
+		if (is_handover) {
+			/* continue */
+			/* TODO: If PAST, send PAST */
+			LOG_ERR("");
+			bt_cap_handover_proc_complete();
+		} else if (cap_cb != NULL && cap_cb->broadcast_reception_start != NULL) {
 			cap_cb->broadcast_reception_start(failed_conn, err);
 		}
 		break;
 	case BT_CAP_COMMON_PROC_TYPE_BROADCAST_RECEPTION_STOP:
-		if (cap_cb->broadcast_reception_stop != NULL) {
+		if (cap_cb != NULL && cap_cb->broadcast_reception_stop != NULL) {
 			cap_cb->broadcast_reception_stop(failed_conn, err);
 		}
 		break;
 	case BT_CAP_COMMON_PROC_TYPE_DISTRIBUTE_BROADCAST_CODE:
-		if (cap_cb->distribute_broadcast_code != NULL) {
+		if (cap_cb != NULL && cap_cb->distribute_broadcast_code != NULL) {
 			cap_cb->distribute_broadcast_code(failed_conn, err);
 		}
 		break;

subsys/bluetooth/audio/cap_common.c

@@ -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,23 @@ bool bt_cap_common_subproc_is_type(enum bt_cap_common_subproc_type subproc_type)
 }
 #endif /* CONFIG_BT_CAP_INITIATOR_UNICAST */
 
+void bt_cap_common_set_handover_active(void)
+{
+	if (IS_ENABLED(CONFIG_BT_CAP_HANDOVER_SUPPORTED)) {
+		atomic_set_bit(active_proc.proc_state_flags, BT_CAP_COMMON_PROC_STATE_HANDOVER);
+	}
+}
+
+bool bt_cap_common_handover_is_active(void)
+{
+	if (IS_ENABLED(CONFIG_BT_CAP_HANDOVER_SUPPORTED)) {
+		return atomic_test_bit(active_proc.proc_state_flags,
+				       BT_CAP_COMMON_PROC_STATE_HANDOVER);
+	} else {
+		return false;
+	}
+}
+
 struct bt_conn *bt_cap_common_get_member_conn(enum bt_cap_set_type type,
 					      const union bt_cap_set_member *member)
 {