Common Audio Profile (CAP) More...

Data Structures
struct	bt_cap_initiator_cb

union	bt_cap_set_member

struct	bt_cap_stream

struct	bt_cap_unicast_audio_start_stream_param

struct	bt_cap_unicast_audio_start_param

struct	bt_cap_unicast_audio_update_param

struct	bt_cap_initiator_broadcast_stream_param

struct	bt_cap_initiator_broadcast_subgroup_param

struct	bt_cap_initiator_broadcast_create_param

struct	bt_cap_unicast_to_broadcast_param

struct	bt_cap_broadcast_to_unicast_param

Enumerations
enum	bt_cap_set_type { BT_CAP_SET_TYPE_AD_HOC , BT_CAP_SET_TYPE_CSIP }

Functions
int	bt_cap_acceptor_register (const struct bt_csip_set_member_register_param param, struct bt_csip_set_member_svc_inst *svc_inst)
	Register the Common Audio Service. More...

int	bt_cap_initiator_unicast_discover (struct bt_conn *conn)
	Discovers audio support on a remote device. More...

void	bt_cap_stream_ops_register (struct bt_cap_stream stream, struct bt_bap_stream_ops ops)
	Register Audio operations for a Common Audio Profile stream. More...

int	bt_cap_initiator_register_cb (const struct bt_cap_initiator_cb *cb)
	Register Common Audio Profile callbacks. More...

int	bt_cap_initiator_unicast_audio_start (const struct bt_cap_unicast_audio_start_param param, struct bt_bap_unicast_group unicast_group)
	Setup and start unicast audio streams for a set of devices. More...

int	bt_cap_initiator_unicast_audio_update (const struct bt_cap_unicast_audio_update_param params[], size_t count)
	Update unicast audio streams. More...

int	bt_cap_initiator_unicast_audio_stop (struct bt_bap_unicast_group *unicast_group)
	Stop unicast audio streams for a unicast group. More...

int	bt_cap_initiator_unicast_audio_cancel (void)
	Cancel any current Common Audio Profile procedure. More...

int	bt_cap_initiator_broadcast_audio_create (const struct bt_cap_initiator_broadcast_create_param param, struct bt_cap_broadcast_source *broadcast_source)
	Create a Common Audio Profile broadcast source. More...

int	bt_cap_initiator_broadcast_audio_start (struct bt_cap_broadcast_source broadcast_source, struct bt_le_ext_adv adv)
	Start Common Audio Profile broadcast source. More...

int	bt_cap_initiator_broadcast_audio_update (struct bt_cap_broadcast_source *broadcast_source, const struct bt_codec_data meta[], size_t meta_count)
	Update broadcast audio streams for a Common Audio Profile broadcast source. More...

int	bt_cap_initiator_broadcast_audio_stop (struct bt_cap_broadcast_source *broadcast_source)
	Stop broadcast audio streams for a Common Audio Profile broadcast source. More...

int	bt_cap_initiator_broadcast_audio_delete (struct bt_cap_broadcast_source *broadcast_source)

int	bt_cap_initiator_broadcast_get_id (const struct bt_cap_broadcast_source broadcast_source, uint32_t const broadcast_id)
	Get the broadcast ID of a Common Audio Profile broadcast source. More...

int	bt_cap_initiator_broadcast_get_base (struct bt_cap_broadcast_source broadcast_source, struct net_buf_simple base_buf)
	Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source. More...

int	bt_cap_initiator_unicast_to_broadcast (const struct bt_cap_unicast_to_broadcast_param param, struct bt_cap_broadcast_source *source)
	Hands over the data streams in a unicast group to a broadcast source. More...

int	bt_cap_initiator_broadcast_to_unicast (const struct bt_cap_broadcast_to_unicast_param param, struct bt_bap_unicast_group *unicast_group)
	Hands over the data streams in a broadcast source to a unicast group. More...

Detailed Description

Common Audio Profile (CAP)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Enumeration Type Documentation

◆ bt_cap_set_type

enum bt_cap_set_type

#include <include/zephyr/bluetooth/audio/cap.h>

Type of CAP set

Enumerator
BT_CAP_SET_TYPE_AD_HOC	The set is an ad-hoc set
BT_CAP_SET_TYPE_CSIP	The set is a CSIP Coordinated Set

Function Documentation

◆ bt_cap_acceptor_register()

int bt_cap_acceptor_register	(	const struct bt_csip_set_member_register_param *	param,
		struct bt_csip_set_member_svc_inst **	svc_inst
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Register the Common Audio Service.

This will register and enable the service and make it discoverable by clients. This will also register a Coordinated Set Identification Service instance.

This shall only be done as a server, and requires BT_CAP_ACCEPTOR_SET_MEMBER . If BT_CAP_ACCEPTOR_SET_MEMBER is not enabled, the Common Audio Service will by statically registered.

Parameters

[in]	param	Coordinated Set Identification Service register parameters.
[out]	svc_inst	Pointer to the registered Coordinated Set Identification Service.

Returns: 0 if success, errno on failure.

◆ bt_cap_initiator_broadcast_audio_create()

int bt_cap_initiator_broadcast_audio_create	(	const struct bt_cap_initiator_broadcast_create_param *	param,
		struct bt_cap_broadcast_source **	broadcast_source
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Create a Common Audio Profile broadcast source.

Create a new audio broadcast source with one or more audio streams.

*
Note
CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

[in] param Parameters to start the audio streams.

[out] broadcast_source Pointer to the broadcast source created.

Returns
0 on success or negative error value on failure.

◆ bt_cap_initiator_broadcast_audio_delete()

int bt_cap_initiator_broadcast_audio_delete ( struct bt_cap_broadcast_source * broadcast_source )

#include <include/zephyr/bluetooth/audio/cap.h>

◆ bt_cap_initiator_broadcast_audio_start()

int bt_cap_initiator_broadcast_audio_start	(	struct bt_cap_broadcast_source *	broadcast_source,
		struct bt_le_ext_adv *	adv
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Start Common Audio Profile broadcast source.

The broadcast source will be visible for scanners once this has been called, and the device will advertise audio announcements.

This will allow the streams in the broadcast source to send audio by calling bt_bap_stream_send().

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

broadcast_source	Pointer to the broadcast source.
adv	Pointer to an extended advertising set with periodic advertising configured.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_broadcast_audio_stop()

int bt_cap_initiator_broadcast_audio_stop ( struct bt_cap_broadcast_source * broadcast_source )

#include <include/zephyr/bluetooth/audio/cap.h>

Stop broadcast audio streams for a Common Audio Profile broadcast source.

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

broadcast_source The broadcast source to stop. The audio streams in this will be stopped and reset.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_broadcast_audio_update()

int bt_cap_initiator_broadcast_audio_update	(	struct bt_cap_broadcast_source *	broadcast_source,
		const struct bt_codec_data	meta[],
		size_t	meta_count
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Update broadcast audio streams for a Common Audio Profile broadcast source.

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

broadcast_source	The broadcast source to update.
meta_count	The number of entries in `meta`.
meta	The new metadata. The metadata shall contain a list of CCIDs as well as a non-0 context bitfield.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_broadcast_get_base()

int bt_cap_initiator_broadcast_get_base	(	struct bt_cap_broadcast_source *	broadcast_source,
		struct net_buf_simple *	base_buf
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source.

This will encode the BASE of a broadcast source into a buffer, that can be used for advertisement. The encoded BASE will thus be encoded as little-endian. The BASE shall be put into the periodic advertising data (see bt_le_per_adv_set_data()).

See table 3.15 in the Basic Audio Profile v1.0.1 for the structure.

Parameters

broadcast_source	Pointer to the broadcast source.
base_buf	Pointer to a buffer where the BASE will be inserted.

Returns: int 0 if on success, errno on error.

◆ bt_cap_initiator_broadcast_get_id()

int bt_cap_initiator_broadcast_get_id	(	const struct bt_cap_broadcast_source *	broadcast_source,
		uint32_t *const	broadcast_id
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Get the broadcast ID of a Common Audio Profile broadcast source.

This will return the 3-octet broadcast ID that should be advertised in the extended advertising data with BT_UUID_BROADCAST_AUDIO_VAL as BT_DATA_SVC_DATA16.

See table 3.14 in the Basic Audio Profile v1.0.1 for the structure.

Parameters

[in]	broadcast_source	Pointer to the broadcast source.
[out]	broadcast_id	Pointer to the 3-octet broadcast ID.

Returns: int 0 if on success, errno on error.

◆ bt_cap_initiator_broadcast_to_unicast()

int bt_cap_initiator_broadcast_to_unicast	(	const struct bt_cap_broadcast_to_unicast_param *	param,
		struct bt_bap_unicast_group **	unicast_group
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Hands over the data streams in a broadcast source to a unicast group.

The streams in the broadcast source will be stopped and the broadcast source will be deleted.

Note: CONFIG_BT_CAP_INITIATOR , CONFIG_BT_BAP_UNICAST_CLIENT and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

[in]	param	The parameters for the handover.
[out]	unicast_group	The resulting broadcast source.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_register_cb()

int bt_cap_initiator_register_cb ( const struct bt_cap_initiator_cb * cb )

#include <include/zephyr/bluetooth/audio/cap.h>

Register Common Audio Profile callbacks.

Parameters

cb	The callback structure. Shall remain static.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_unicast_audio_cancel()

int bt_cap_initiator_unicast_audio_cancel ( void )

#include <include/zephyr/bluetooth/audio/cap.h>

Cancel any current Common Audio Profile procedure.

This will stop the current procedure from continuing and making it possible to run a new Common Audio Profile procedure.

It is recommended to do this if any existing procedure take longer time than expected, which could indicate a missing response from the Common Audio Profile Acceptor.

This does not send any requests to any Common Audio Profile Acceptors involved with the current procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this has been called. It is thus recommended to either only use this if a procedure has stalled, or wait a short while before starting any new Common Audio Profile procedure after this has been called to avoid getting notifications from the cancelled procedure. The wait time depends on the connection interval, the number of devices in the previous procedure and the behavior of the Common Audio Profile Acceptors.

The respective callbacks of the procedure will be called as part of this with the connection pointer set to 0 and the err value set to -ECANCELED.

Return values

0	on success
-EALREADY	if no procedure is active

◆ bt_cap_initiator_unicast_audio_start()

int bt_cap_initiator_unicast_audio_start	(	const struct bt_cap_unicast_audio_start_param *	param,
		struct bt_bap_unicast_group *	unicast_group
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Setup and start unicast audio streams for a set of devices.

The result of this operation is that the streams in param will be initialized and will be usable for streaming audio data. The unicast_group value can be used to update and stop the streams.

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters

[in]	param	Parameters to start the audio streams.
[out]	unicast_group	Pointer to the unicast group.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_unicast_audio_stop()

int bt_cap_initiator_unicast_audio_stop ( struct bt_bap_unicast_group * unicast_group )

#include <include/zephyr/bluetooth/audio/cap.h>

Stop unicast audio streams for a unicast group.

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters

unicast_group The group of unicast devices to stop. The audio streams in this will be stopped and reset, and the unicast_group will be invalidated.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_unicast_audio_update()

int bt_cap_initiator_unicast_audio_update	(	const struct bt_cap_unicast_audio_update_param	params[],
		size_t	count
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Update unicast audio streams.

This will update the metadata of one or more streams.

Note: CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters

params	Array of update parameters.
count	The number of entries in `params`.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_unicast_discover()

int bt_cap_initiator_unicast_discover ( struct bt_conn * conn )

#include <include/zephyr/bluetooth/audio/cap.h>

Discovers audio support on a remote device.

This will discover the Common Audio Service (CAS) on the remote device, to verify if the remote device supports the Common Audio Profile.

Parameters

conn	Connection to a remote server.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_initiator_unicast_to_broadcast()

int bt_cap_initiator_unicast_to_broadcast	(	const struct bt_cap_unicast_to_broadcast_param *	param,
		struct bt_cap_broadcast_source **	source
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Hands over the data streams in a unicast group to a broadcast source.

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: CONFIG_BT_CAP_INITIATOR , CONFIG_BT_BAP_UNICAST_CLIENT and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters

param	The parameters for the handover.
source	The resulting broadcast source.

Returns: 0 on success or negative error value on failure.

◆ bt_cap_stream_ops_register()

void bt_cap_stream_ops_register	(	struct bt_cap_stream *	stream,
		struct bt_bap_stream_ops *	ops
	)

#include <include/zephyr/bluetooth/audio/cap.h>

Register Audio operations for a Common Audio Profile stream.

Register Audio operations for a stream.

Parameters

stream	Stream object.
ops	Stream operations structure.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ bt_cap_set_type

Function Documentation

◆ bt_cap_acceptor_register()

◆ bt_cap_initiator_broadcast_audio_create()

◆ bt_cap_initiator_broadcast_audio_delete()

◆ bt_cap_initiator_broadcast_audio_start()

◆ bt_cap_initiator_broadcast_audio_stop()

◆ bt_cap_initiator_broadcast_audio_update()

◆ bt_cap_initiator_broadcast_get_base()

◆ bt_cap_initiator_broadcast_get_id()

◆ bt_cap_initiator_broadcast_to_unicast()

◆ bt_cap_initiator_register_cb()

◆ bt_cap_initiator_unicast_audio_cancel()

◆ bt_cap_initiator_unicast_audio_start()

◆ bt_cap_initiator_unicast_audio_stop()

◆ bt_cap_initiator_unicast_audio_update()

◆ bt_cap_initiator_unicast_discover()

◆ bt_cap_initiator_unicast_to_broadcast()

◆ bt_cap_stream_ops_register()