Basic Audio Profile

API Reference

Related code samples

Bluetooth: Broadcast Audio Assistant

Use LE Audio Broadcast Assistant functionality

Bluetooth: Common Audio Profile Acceptor

CAP Acceptor sample that advertises audio availability to CAP Initiators.

Bluetooth: Common Audio Profile Initiator

CAP Initiator sample that connects to CAP Acceptors and setup audio streaming.

group bt_bap

Bluetooth Basic Audio Profile (BAP)

The Basic Audio Profile (BAP) allows for both unicast and broadcast Audio Stream control.

Since

3.0

Version

0.8.0

Defines

BT_BAP_PA_INTERVAL_UNKNOWN

Value indicating that the periodic advertising interval is unknown.

BT_BAP_BIS_SYNC_NO_PREF

Broadcast Assistant no BIS sync preference.

Value indicating that the Broadcast Assistant has no preference to which BIS the Scan Delegator syncs to

BT_BAP_ASCS_RSP(c, r)

Macro used to initialise the object storing values of ASE Control Point notification.

Parameters:

Typedefs

typedef bool (*bt_bap_scan_delegator_state_func_t)(const struct bt_bap_scan_delegator_recv_state *recv_state, void *user_data)

Callback function for Scan Delegator receive state search functions.

Param recv_state:

The receive state.

Param user_data:

User data.

Retval true:

to stop iterating. If this is used in the context of bt_bap_scan_delegator_find_state(), the recv_state will be returned by bt_bap_scan_delegator_find_state()

Retval false:

to continue iterating

typedef void (*bt_bap_broadcast_assistant_write_cb)(struct bt_conn *conn, int err)

Callback function for writes.

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

Enums

enum bt_bap_pa_state

Periodic advertising state reported by the Scan Delegator.

Values:

enumerator BT_BAP_PA_STATE_NOT_SYNCED = 0x00

The periodic advertising has not been synchronized.

enumerator BT_BAP_PA_STATE_INFO_REQ = 0x01

Waiting for SyncInfo from Broadcast Assistant.

enumerator BT_BAP_PA_STATE_SYNCED = 0x02

Synchronized to periodic advertising.

enumerator BT_BAP_PA_STATE_FAILED = 0x03

Failed to synchronized to periodic advertising.

enumerator BT_BAP_PA_STATE_NO_PAST = 0x04

No periodic advertising sync transfer receiver from Broadcast Assistant.

enum bt_bap_big_enc_state

Broadcast Isochronous Group encryption state reported by the Scan Delegator.

Values:

enumerator BT_BAP_BIG_ENC_STATE_NO_ENC = 0x00

The Broadcast Isochronous Group not encrypted.

enumerator BT_BAP_BIG_ENC_STATE_BCODE_REQ = 0x01

The Broadcast Isochronous Group broadcast code requested.

enumerator BT_BAP_BIG_ENC_STATE_DEC = 0x02

The Broadcast Isochronous Group decrypted.

enumerator BT_BAP_BIG_ENC_STATE_BAD_CODE = 0x03

The Broadcast Isochronous Group bad broadcast code.

enum bt_bap_bass_att_err

Broadcast Audio Scan Service (BASS) specific ATT error codes.

Values:

enumerator BT_BAP_BASS_ERR_OPCODE_NOT_SUPPORTED = 0x80

Opcode not supported.

enumerator BT_BAP_BASS_ERR_INVALID_SRC_ID = 0x81

Invalid source ID supplied.

enum bt_bap_ep_state

Endpoint states.

Values:

enumerator BT_BAP_EP_STATE_IDLE = 0x00

Audio Stream Endpoint Idle state.

enumerator BT_BAP_EP_STATE_CODEC_CONFIGURED = 0x01

Audio Stream Endpoint Codec Configured state.

enumerator BT_BAP_EP_STATE_QOS_CONFIGURED = 0x02

Audio Stream Endpoint QoS Configured state.

enumerator BT_BAP_EP_STATE_ENABLING = 0x03

Audio Stream Endpoint Enabling state.

enumerator BT_BAP_EP_STATE_STREAMING = 0x04

Audio Stream Endpoint Streaming state.

enumerator BT_BAP_EP_STATE_DISABLING = 0x05

Audio Stream Endpoint Disabling state.

enumerator BT_BAP_EP_STATE_RELEASING = 0x06

Audio Stream Endpoint Streaming state.

enum bt_bap_ascs_rsp_code

Response Status Code.

These are sent by the server to the client when a stream operation is requested.

Values:

enumerator BT_BAP_ASCS_RSP_CODE_SUCCESS = 0x00

Server completed operation successfully.

enumerator BT_BAP_ASCS_RSP_CODE_NOT_SUPPORTED = 0x01

Server did not support operation by client.

enumerator BT_BAP_ASCS_RSP_CODE_INVALID_LENGTH = 0x02

Server rejected due to invalid operation length.

enumerator BT_BAP_ASCS_RSP_CODE_INVALID_ASE = 0x03

Invalid ASE ID.

enumerator BT_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE = 0x04

Invalid ASE state.

enumerator BT_BAP_ASCS_RSP_CODE_INVALID_DIR = 0x05

Invalid operation for direction.

enumerator BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED = 0x06

Capabilities not supported by server.

enumerator BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED = 0x07

Configuration parameters not supported by server.

enumerator BT_BAP_ASCS_RSP_CODE_CONF_REJECTED = 0x08

Configuration parameters rejected by server.

enumerator BT_BAP_ASCS_RSP_CODE_CONF_INVALID = 0x09

Invalid Configuration parameters.

enumerator BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED = 0x0a

Unsupported metadata.

enumerator BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED = 0x0b

Metadata rejected by server.

enumerator BT_BAP_ASCS_RSP_CODE_METADATA_INVALID = 0x0c

Invalid metadata.

enumerator BT_BAP_ASCS_RSP_CODE_NO_MEM = 0x0d

Server has insufficient resources.

enumerator BT_BAP_ASCS_RSP_CODE_UNSPECIFIED = 0x0e

Unspecified error.

enum bt_bap_ascs_reason

Response Reasons.

These are used if the bt_bap_ascs_rsp_code value is BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED, BT_BAP_ASCS_RSP_CODE_CONF_REJECTED or BT_BAP_ASCS_RSP_CODE_CONF_INVALID.

Values:

enumerator BT_BAP_ASCS_REASON_NONE = 0x00

No reason.

enumerator BT_BAP_ASCS_REASON_CODEC = 0x01

Codec ID.

enumerator BT_BAP_ASCS_REASON_CODEC_DATA = 0x02

Codec configuration.

enumerator BT_BAP_ASCS_REASON_INTERVAL = 0x03

SDU interval.

enumerator BT_BAP_ASCS_REASON_FRAMING = 0x04

Framing.

enumerator BT_BAP_ASCS_REASON_PHY = 0x05

PHY.

enumerator BT_BAP_ASCS_REASON_SDU = 0x06

Maximum SDU size.

enumerator BT_BAP_ASCS_REASON_RTN = 0x07

RTN.

enumerator BT_BAP_ASCS_REASON_LATENCY = 0x08

Max transport latency.

enumerator BT_BAP_ASCS_REASON_PD = 0x09

Presendation delay.

enumerator BT_BAP_ASCS_REASON_CIS = 0x0a

Invalid CIS mapping.

Functions

int bt_bap_ep_get_info(const struct bt_bap_ep *ep, struct bt_bap_ep_info *info)

Return structure holding information of audio stream endpoint.

Parameters:

  • ep – The audio stream endpoint object.

  • info – The structure object to be filled with the info.

Return values:

  • 0 – in case of success

  • -EINVAL – if ep or info are NULL

void bt_bap_stream_cb_register(struct bt_bap_stream *stream, struct bt_bap_stream_ops *ops)

Register Audio callbacks for a stream.

Register Audio callbacks for a stream.

Parameters:

  • stream – Stream object.

  • ops – Stream operations structure.

int bt_bap_stream_config(struct bt_conn *conn, struct bt_bap_stream *stream, struct bt_bap_ep *ep, struct bt_audio_codec_cfg *codec_cfg)

Configure Audio Stream.

This procedure is used by a client to configure a new stream using the remote endpoint, local capability and codec configuration.

Parameters:

  • conn – Connection object

  • stream – Stream object being configured

  • ep – Remote Audio Endpoint being configured

  • codec_cfg – Codec configuration

Returns:

Allocated Audio Stream object or NULL in case of error.

int bt_bap_stream_reconfig(struct bt_bap_stream *stream, struct bt_audio_codec_cfg *codec_cfg)

Reconfigure Audio Stream.

This procedure is used by a unicast client or unicast server to reconfigure a stream to use a different local codec configuration.

This can only be done for unicast streams.

Parameters:

  • stream – Stream object being reconfigured

  • codec_cfg – Codec configuration

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_qos(struct bt_conn *conn, struct bt_bap_unicast_group *group)

Configure Audio Stream QoS.

This procedure is used by a client to configure the Quality of Service of streams in a unicast group. All streams in the group for the specified conn will have the Quality of Service configured. This shall only be used to configure unicast streams.

Parameters:

  • conn – Connection object

  • group – Unicast group object

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_enable(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len)

Enable Audio Stream.

This procedure is used by a client to enable a stream.

This shall only be called for unicast streams, as broadcast streams will always be enabled once created.

Parameters:

  • stream – Stream object

  • meta – Metadata

  • meta_len – Metadata length

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_metadata(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len)

Change Audio Stream Metadata.

This procedure is used by a unicast client or unicast server to change the metadata of a stream.

Parameters:

  • stream – Stream object

  • meta – Metadata

  • meta_len – Metadata length

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_disable(struct bt_bap_stream *stream)

Disable Audio Stream.

This procedure is used by a unicast client or unicast server to disable a stream.

This shall only be called for unicast streams, as broadcast streams will always be enabled once created.

Parameters:

  • stream – Stream object

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_connect(struct bt_bap_stream *stream)

Connect unicast audio stream.

This procedure is used by a unicast client to connect the connected isochronous stream (CIS) associated with the audio stream. If two audio streams share a CIS, then this only needs to be done once for those streams. This can only be done for streams in the QoS configured or enabled states.

The bt_bap_stream_ops.connected() callback will be called on the streams once this has finished.

This shall only be called for unicast streams, and only as the unicast client ( CONFIG_BT_BAP_UNICAST_CLIENT ).

Parameters:

  • stream – Stream object

Return values:

  • 0 – in case of success

  • -EINVAL – if the stream, endpoint, ISO channel or connection is NULL

  • -EBADMSG – if the stream or ISO channel is in an invalid state for connection

  • -EOPNOTSUPP – if the role of the stream is not BT_HCI_ROLE_CENTRAL

  • -EALREADY – if the ISO channel is already connecting or connected

  • -EBUSY – if another ISO channel is connecting

  • -ENOEXEC – if otherwise rejected by the ISO layer

int bt_bap_stream_start(struct bt_bap_stream *stream)

Start Audio Stream.

This procedure is used by a unicast client or unicast server to make a stream start streaming.

For the unicast client, this will send the receiver start ready command to the unicast server for BT_AUDIO_DIR_SOURCE ASEs. The CIS is required to be connected first by bt_bap_stream_connect() before the command can be sent.

For the unicast server, this will execute the receiver start ready command on the unicast server for BT_AUDIO_DIR_SINK ASEs. If the CIS is not connected yet, the stream will go into the streaming state as soon as the CIS is connected.

This shall only be called for unicast streams.

Broadcast sinks will always be started once synchronized, and broadcast source streams shall be started with bt_bap_broadcast_source_start().

Parameters:

  • stream – Stream object

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_stop(struct bt_bap_stream *stream)

Stop Audio Stream.

This procedure is used by a client to make a stream stop streaming.

This shall only be called for unicast streams. Broadcast sinks cannot be stopped. Broadcast sources shall be stopped with bt_bap_broadcast_source_stop().

Parameters:

  • stream – Stream object

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_release(struct bt_bap_stream *stream)

Release Audio Stream.

This procedure is used by a unicast client or unicast server to release a unicast stream.

Broadcast sink streams cannot be released, but can be deleted by bt_bap_broadcast_sink_delete(). Broadcast source streams cannot be released, but can be deleted by bt_bap_broadcast_source_delete().

Parameters:

  • stream – Stream object

Returns:

0 in case of success or negative value in case of error.

int bt_bap_stream_send(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num)

Send data to Audio stream without timestamp.

Send data from buffer to the stream.

Note

Support for sending must be supported, determined by CONFIG_BT_AUDIO_TX .

Parameters:

  • stream – Stream object.

  • buf – Buffer containing data to be sent.

  • seq_num – Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

Returns:

Bytes sent in case of success or negative value in case of error.

int bt_bap_stream_send_ts(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num, uint32_t ts)

Send data to Audio stream with timestamp.

Send data from buffer to the stream.

Note

Support for sending must be supported, determined by CONFIG_BT_AUDIO_TX .

Parameters:

  • stream – Stream object.

  • buf – Buffer containing data to be sent.

  • seq_num – Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

  • ts – Timestamp of the SDU in microseconds (us). This value can be used to transmit multiple SDUs in the same SDU interval in a CIG or BIG.

Returns:

Bytes sent in case of success or negative value in case of error.

int bt_bap_stream_get_tx_sync(struct bt_bap_stream *stream, struct bt_iso_tx_info *info)

Get ISO transmission timing info for a Basic Audio Profile stream.

Reads timing information for transmitted ISO packet on an ISO channel. The HCI_LE_Read_ISO_TX_Sync HCI command is used to retrieve this information from the controller.

Note

An SDU must have already been successfully transmitted on the ISO channel for this function to return successfully. Support for sending must be supported, determined by CONFIG_BT_AUDIO_TX .

Parameters:

  • stream – [in] Stream object.

  • info – [out] Transmit info object.

Return values:

  • 0 – on success

  • -EINVAL – if the stream is invalid, if the stream is not configured for sending or if it is not connected with a isochronous stream

  • Any – return value from bt_iso_chan_get_tx_sync()

void bt_bap_scan_delegator_register_cb(struct bt_bap_scan_delegator_cb *cb)

Register the callbacks for the Basic Audio Profile Scan Delegator.

Only one set of callbacks can be registered at any one time, and calling this function multiple times will override any previously registered callbacks.

Parameters:

  • cb – Pointer to the callback struct

int bt_bap_scan_delegator_set_pa_state(uint8_t src_id, enum bt_bap_pa_state pa_state)

Set the periodic advertising sync state to syncing.

Set the periodic advertising sync state for a receive state to syncing, notifying Broadcast Assistants.

Parameters:

  • src_id – The source id used to identify the receive state.

  • pa_state – The Periodic Advertising sync state to set. BT_BAP_PA_STATE_NOT_SYNCED and BT_BAP_PA_STATE_SYNCED is not necessary to provide, as they are handled internally.

Returns:

int Error value. 0 on success, errno on fail.

int bt_bap_scan_delegator_set_bis_sync_state(uint8_t src_id, uint32_t bis_synced[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS])

Set the sync state of a receive state in the server.

Parameters:

  • src_id – The source id used to identify the receive state.

  • bis_synced – Array of bitfields to set the BIS sync state for each subgroup.

Returns:

int Error value. 0 on success, ERRNO on fail.

int bt_bap_scan_delegator_add_src(const struct bt_bap_scan_delegator_add_src_param *param)

Add a receive state source locally.

This will notify any connected clients about the new source. This allows them to modify and even remove it.

If CONFIG_BT_BAP_BROADCAST_SINK is enabled, any Broadcast Sink sources are autonomously added.

Parameters:

  • param – The parameters for adding the new source

Returns:

int errno on failure, or source ID on success.

int bt_bap_scan_delegator_mod_src(const struct bt_bap_scan_delegator_mod_src_param *param)

Add a receive state source locally.

This will notify any connected clients about the new source. This allows them to modify and even remove it.

If CONFIG_BT_BAP_BROADCAST_SINK is enabled, any Broadcast Sink sources are autonomously modified.

Parameters:

  • param – The parameters for adding the new source

Returns:

int errno on failure, or source ID on success.

int bt_bap_scan_delegator_rem_src(uint8_t src_id)

Remove a receive state source.

This will remove the receive state. If the receive state periodic advertising is synced, bt_bap_scan_delegator_cb.pa_sync_term_req() will be called.

If CONFIG_BT_BAP_BROADCAST_SINK is enabled, any Broadcast Sink sources are autonomously removed.

Parameters:

  • src_id – The source ID to remove

Returns:

int Error value. 0 on success, errno on fail.

void bt_bap_scan_delegator_foreach_state(bt_bap_scan_delegator_state_func_t func, void *user_data)

Iterate through all existing receive states.

Parameters:

  • func – The callback function

  • user_data – User specified data that sent to the callback function

const struct bt_bap_scan_delegator_recv_state *bt_bap_scan_delegator_find_state(bt_bap_scan_delegator_state_func_t func, void *user_data)

Find and return a receive state based on a compare function.

Parameters:

  • func – The compare callback function

  • user_data – User specified data that sent to the callback function

Returns:

The first receive state where the func returned true, or NULL

int bt_bap_broadcast_assistant_discover(struct bt_conn *conn)

Discover Broadcast Audio Scan Service on the server.

Warning: Only one connection can be active at any time; discovering for a new connection, will delete all previous data.

Parameters:

  • conn – The connection

Returns:

int Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_scan_start(struct bt_conn *conn, bool start_scan)

Scan start for BISes for a remote server.

This will let the Broadcast Audio Scan Service server know that this device is actively scanning for broadcast sources. The function can optionally also start scanning, if the caller does not want to start scanning itself.

Scan results, if start_scan is true, is sent to the bt_bap_broadcast_assistant_scan_cb callback.

Parameters:

  • conn – Connection to the Broadcast Audio Scan Service server. Used to let the server know that we are scanning.

  • start_scan – Start scanning if true. If false, the application should enable scan itself.

Returns:

int Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_scan_stop(struct bt_conn *conn)

Stop remote scanning for BISes for a server.

Parameters:

  • conn – Connection to the server.

Returns:

int Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_register_cb(struct bt_bap_broadcast_assistant_cb *cb)

Registers the callbacks used by Broadcast Audio Scan Service client.

Parameters:

  • cb – The callback structure.

Return values:

  • 0 – on success

  • -EINVAL – if cb is NULL

  • -EALREADY – if cb was already registered

int bt_bap_broadcast_assistant_unregister_cb(struct bt_bap_broadcast_assistant_cb *cb)

Unregisters the callbacks used by the Broadcast Audio Scan Service client.

Parameters:

  • cb – The callback structure.

Return values:

  • 0 – on success

  • -EINVAL – if cb is NULL

  • -EALREADY – if cb was not registered

int bt_bap_broadcast_assistant_add_src(struct bt_conn *conn, const struct bt_bap_broadcast_assistant_add_src_param *param)

Add a source on the server.

Parameters:

  • conn – Connection to the server.

  • param – Parameter struct.

Returns:

Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_mod_src(struct bt_conn *conn, const struct bt_bap_broadcast_assistant_mod_src_param *param)

Modify a source on the server.

Parameters:

  • conn – Connection to the server.

  • param – Parameter struct.

Returns:

Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_set_broadcast_code(struct bt_conn *conn, uint8_t src_id, const uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE])

Set a broadcast code to the specified receive state.

Parameters:

  • conn – Connection to the server.

  • src_id – Source ID of the receive state.

  • broadcast_code – The broadcast code.

Returns:

Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_rem_src(struct bt_conn *conn, uint8_t src_id)

Remove a source from the server.

Parameters:

  • conn – Connection to the server.

  • src_id – Source ID of the receive state.

Returns:

Error value. 0 on success, GATT error or ERRNO on fail.

int bt_bap_broadcast_assistant_read_recv_state(struct bt_conn *conn, uint8_t idx)

Read the specified receive state from the server.

Parameters:

  • conn – Connection to the server.

  • idx – The index of the receive start (0 up to the value from bt_bap_broadcast_assistant_discover_cb)

Returns:

Error value. 0 on success, GATT error or ERRNO on fail.

struct bt_bap_ascs_rsp
#include <bap.h>

Structure storing values of fields of ASE Control Point notification.

Public Members

enum bt_bap_ascs_rsp_code code

Value of the Response Code field.

The following response codes are accepted:

enum bt_bap_ascs_reason reason

Response reason.

If the Response Code is one of the following:

If the Response Code is one of the following:

enum bt_audio_metadata_type metadata_type

Response metadata type.

If the Response Code is one of the following:

union bt_bap_ascs_rsp

Value of the Reason field.

The meaning of this value depend on the Response Code field.

struct bt_bap_bass_subgroup
#include <bap.h>

Struct to hold subgroup specific information for the receive state.

Public Members

uint32_t bis_sync

BIS synced bitfield.

uint8_t metadata_len

Length of the metadata.

uint8_t metadata[CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE]

The metadata.

struct bt_bap_scan_delegator_recv_state
#include <bap.h>

Represents the Broadcast Audio Scan Service receive state.

Public Members

uint8_t src_id

The source ID

bt_addr_le_t addr

The Bluetooth address.

uint8_t adv_sid

The advertising set ID.

enum bt_bap_pa_state pa_sync_state

The periodic adverting sync state.

enum bt_bap_big_enc_state encrypt_state

The broadcast isochronous group encryption state.

uint32_t broadcast_id

The 24-bit broadcast ID.

uint8_t bad_code[BT_AUDIO_BROADCAST_CODE_SIZE]

The bad broadcast code.

Only valid if encrypt_state is BT_BAP_BIG_ENC_STATE_BCODE_REQ

uint8_t num_subgroups

Number of subgroups.

struct bt_bap_bass_subgroup subgroups[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS]

Subgroup specific information.

struct bt_bap_scan_delegator_cb
#include <bap.h>

Struct to hold the Basic Audio Profile Scan Delegator callbacks.

These can be registered for usage with bt_bap_scan_delegator_register_cb().

Public Members

void (*recv_state_updated)(struct bt_conn *conn, const struct bt_bap_scan_delegator_recv_state *recv_state)

Receive state updated.

Param conn:

Pointer to the connection to a remote device if the change was caused by it, otherwise NULL.

Param recv_state:

Pointer to the receive state that was updated.

Return:

0 in case of success or negative value in case of error.

int (*pa_sync_req)(struct bt_conn *conn, const struct bt_bap_scan_delegator_recv_state *recv_state, bool past_avail, uint16_t pa_interval)

Periodic advertising sync request.

Request from peer device to synchronize with the periodic advertiser denoted by the recv_state. To notify the Broadcast Assistant about any pending sync

Param conn:

Pointer to the connection requesting the periodic advertising sync.

Param recv_state:

Pointer to the receive state that is being requested for periodic advertising sync.

Param past_avail:

True if periodic advertising sync transfer is available.

Param pa_interval:

The periodic advertising interval.

Return:

0 in case of accept, or other value to reject.

int (*pa_sync_term_req)(struct bt_conn *conn, const struct bt_bap_scan_delegator_recv_state *recv_state)

Periodic advertising sync termination request.

Request from peer device to terminate the periodic advertiser sync denoted by the recv_state.

Param conn:

Pointer to the connection requesting the periodic advertising sync termination.

Param recv_state:

Pointer to the receive state that is being requested for periodic advertising sync.

Return:

0 in case of success or negative value in case of error.

void (*broadcast_code)(struct bt_conn *conn, const struct bt_bap_scan_delegator_recv_state *recv_state, const uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE])

Broadcast code received.

Broadcast code received from a broadcast assistant

Param conn:

Pointer to the connection providing the broadcast code.

Param recv_state:

Pointer to the receive state the broadcast code is being provided for.

Param broadcast_code:

The 16-octet broadcast code

int (*bis_sync_req)(struct bt_conn *conn, const struct bt_bap_scan_delegator_recv_state *recv_state, const uint32_t bis_sync_req[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS])

Broadcast Isochronous Stream synchronize request.

Request from Broadcast Assistant device to modify the Broadcast Isochronous Stream states. The request shall be fulfilled with accordance to the bis_sync_req within reasonable time. The Broadcast Assistant may also request fewer, or none, indexes to be synchronized.

Param conn:

[in] Pointer to the connection of the Broadcast Assistant requesting the sync.

Param recv_state:

[in] Pointer to the receive state that is being requested for the sync.

Param bis_sync_req:

[in] Array of bitfields of which BIS indexes that is requested to sync for each subgroup by the Broadcast Assistant. A value of 0 indicates a request to terminate the BIG sync.

Return:

0 in case of accept, or other value to reject.

struct bt_bap_ep_info
#include <bap.h>

Structure holding information of audio stream endpoint.

Public Members

uint8_t id

The ID of the endpoint.

enum bt_bap_ep_state state

The state of the endpoint.

enum bt_audio_dir dir

Capabilities type.

struct bt_iso_chan *iso_chan

The isochronous channel associated with the endpoint.

bool can_send

True if the stream associated with the endpoint is able to send data.

bool can_recv

True if the stream associated with the endpoint is able to receive data.

struct bt_bap_ep *paired_ep

Pointer to paired endpoint if the endpoint is part of a bidirectional CIS, otherwise NULL.

const struct bt_audio_codec_qos_pref *qos_pref

Pointer to the preferred QoS settings associated with the endpoint.

struct bt_bap_stream
#include <bap.h>

Basic Audio Profile stream structure.

Streams represents a stream configuration of a Remote Endpoint and a Local Capability.

Note

Streams are unidirectional but can be paired with other streams to use a bidirectional connected isochronous stream.

Public Members

struct bt_conn *conn

Connection reference.

struct bt_bap_ep *ep

Endpoint reference.

struct bt_audio_codec_cfg *codec_cfg

Codec Configuration.

struct bt_audio_codec_qos *qos

QoS Configuration.

struct bt_bap_stream_ops *ops

Audio stream operations.

void *user_data

Stream user data.

struct bt_bap_stream_ops
#include <bap.h>

Stream operation.

Public Members

void (*configured)(struct bt_bap_stream *stream, const struct bt_audio_codec_qos_pref *pref)

Stream configured callback.

Configured callback is called whenever an Audio Stream has been configured.

Param stream:

Stream object that has been configured.

Param pref:

Remote QoS preferences.

void (*qos_set)(struct bt_bap_stream *stream)

Stream QoS set callback.

QoS set callback is called whenever an Audio Stream Quality of Service has been set or updated.

Param stream:

Stream object that had its QoS updated.

void (*enabled)(struct bt_bap_stream *stream)

Stream enabled callback.

Enabled callback is called whenever an Audio Stream has been enabled.

Param stream:

Stream object that has been enabled.

void (*metadata_updated)(struct bt_bap_stream *stream)

Stream metadata updated callback.

Metadata Updated callback is called whenever an Audio Stream’s metadata has been updated.

Param stream:

Stream object that had its metadata updated.

void (*disabled)(struct bt_bap_stream *stream)

Stream disabled callback.

Disabled callback is called whenever an Audio Stream has been disabled.

Param stream:

Stream object that has been disabled.

void (*released)(struct bt_bap_stream *stream)

Stream released callback.

Released callback is called whenever a Audio Stream has been released and can be deallocated.

Param stream:

Stream object that has been released.

void (*started)(struct bt_bap_stream *stream)

Stream started callback.

Started callback is called whenever an Audio Stream has been started and will be usable for streaming.

Param stream:

Stream object that has been started.

void (*stopped)(struct bt_bap_stream *stream, uint8_t reason)

Stream stopped callback.

Stopped callback is called whenever an Audio Stream has been stopped.

Param stream:

Stream object that has been stopped.

Param reason:

BT_HCI_ERR_* reason for the disconnection.

void (*recv)(struct bt_bap_stream *stream, const struct bt_iso_recv_info *info, struct net_buf *buf)

Stream audio HCI receive callback.

This callback is only used if the ISO data path is HCI.

Param stream:

Stream object.

Param info:

Pointer to the metadata for the buffer. The lifetime of the pointer is linked to the lifetime of the net_buf. Metadata such as sequence number and timestamp can be provided by the bluetooth controller.

Param buf:

Buffer containing incoming audio data.

void (*sent)(struct bt_bap_stream *stream)

Stream audio HCI sent callback.

This callback will be called once the controller marks the SDU as completed. When the controller does so is implementation dependent. It could be after the SDU is enqueued for transmission, or after it is sent on air or flushed.

This callback is only used if the ISO data path is HCI.

Param stream:

Stream object.

void (*connected)(struct bt_bap_stream *stream)

Isochronous channel connected callback.

If this callback is provided it will be called whenever the isochronous channel for the stream has been connected. This does not mean that the stream is ready to be used, which is indicated by the bt_bap_stream_ops::started callback.

If the stream shares an isochronous channel with another stream, then this callback may still be called, without the stream going into the started state.

Param stream:

Stream object.

void (*disconnected)(struct bt_bap_stream *stream, uint8_t reason)

Isochronous channel disconnected callback.

If this callback is provided it will be called whenever the isochronous channel is disconnected, including when a connection gets rejected.

If the stream shares an isochronous channel with another stream, then this callback may not be called, even if the stream is leaving the streaming state.

Param stream:

Stream object.

Param reason:

BT_HCI_ERR_* reason for the disconnection.

struct bt_bap_scan_delegator_add_src_param
#include <bap.h>

Parameters for bt_bap_scan_delegator_add_src()

Public Members

struct bt_le_per_adv_sync *pa_sync

The periodic adverting sync.

enum bt_bap_big_enc_state encrypt_state

The broadcast isochronous group encryption state.

uint32_t broadcast_id

The 24-bit broadcast ID.

uint8_t num_subgroups

Number of subgroups.

struct bt_bap_bass_subgroup subgroups[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS]

Subgroup specific information.

struct bt_bap_scan_delegator_mod_src_param
#include <bap.h>

Parameters for bt_bap_scan_delegator_mod_src()

Public Members

uint8_t src_id

The periodic adverting sync.

enum bt_bap_big_enc_state encrypt_state

The broadcast isochronous group encryption state.

uint32_t broadcast_id

The 24-bit broadcast ID.

uint8_t num_subgroups

Number of subgroups.

struct bt_bap_bass_subgroup subgroups[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS]

Subgroup specific information.

If a subgroup’s metadata_len is set to 0, the existing metadata for the subgroup will remain unchanged

struct bt_bap_broadcast_assistant_cb
#include <bap.h>

Struct to hold the Basic Audio Profile Broadcast Assistant callbacks.

These can be registered for usage with bt_bap_broadcast_assistant_register_cb().

Public Members

void (*discover)(struct bt_conn *conn, int err, uint8_t recv_state_count)

Callback function for bt_bap_broadcast_assistant_discover.

Param conn:

The connection that was used to discover Broadcast Audio Scan Service.

Param err:

Error value. 0 on success, GATT error or ERRNO on fail.

Param recv_state_count:

Number of receive states on the server.

void (*scan)(const struct bt_le_scan_recv_info *info, uint32_t broadcast_id)

Callback function for Broadcast Audio Scan Service client scan results.

Called when the scanner finds an advertiser that advertises the BT_UUID_BROADCAST_AUDIO UUID.

Param info:

Advertiser information.

Param broadcast_id:

24-bit broadcast ID.

void (*recv_state)(struct bt_conn *conn, int err, const struct bt_bap_scan_delegator_recv_state *state)

Callback function for when a receive state is read or updated.

Called whenever a receive state is read or updated.

Param conn:

The connection to the Broadcast Audio Scan Service server.

Param err:

Error value. 0 on success, GATT error on fail.

Param state:

The receive state or NULL if the receive state is empty.

void (*recv_state_removed)(struct bt_conn *conn, uint8_t src_id)

Callback function for when a receive state is removed.

Param conn:

The connection to the Broadcast Audio Scan Service server.

Param src_id:

The receive state.

void (*scan_start)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_scan_start().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

void (*scan_stop)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_scan_stop().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

void (*add_src)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_add_src().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

void (*mod_src)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_mod_src().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

void (*broadcast_code)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_broadcast_code().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

void (*rem_src)(struct bt_conn *conn, int err)

Callback function for bt_bap_broadcast_assistant_rem_src().

Param conn:

The connection to the peer device.

Param err:

Error value. 0 on success, GATT error on fail.

struct bt_bap_broadcast_assistant_add_src_param
#include <bap.h>

Parameters for adding a source to a Broadcast Audio Scan Service server.

Public Members

bt_addr_le_t addr

Address of the advertiser.

uint8_t adv_sid

SID of the advertising set.

bool pa_sync

Whether to sync to periodic advertisements.

uint32_t broadcast_id

24-bit broadcast ID

uint16_t pa_interval

Periodic advertising interval in milliseconds.

BT_BAP_PA_INTERVAL_UNKNOWN if unknown.

uint8_t num_subgroups

Number of subgroups.

struct bt_bap_bass_subgroup *subgroups

Pointer to array of subgroups.

struct bt_bap_broadcast_assistant_mod_src_param
#include <bap.h>

Parameters for modifying a source.

Public Members

uint8_t src_id

Source ID of the receive state.

bool pa_sync

Whether to sync to periodic advertisements.

uint16_t pa_interval

Periodic advertising interval.

BT_BAP_PA_INTERVAL_UNKNOWN if unknown.

uint8_t num_subgroups

Number of subgroups.

struct bt_bap_bass_subgroup *subgroups

Pointer to array of subgroups.

group bt_bap_unicast_client

Functions

int bt_bap_unicast_group_create(struct bt_bap_unicast_group_param *param, struct bt_bap_unicast_group **unicast_group)

Create audio unicast group.

Create a new audio unicast group with one or more audio streams as a unicast client. Streams in a unicast group shall share the same interval, framing and latency (see bt_audio_codec_qos).

Parameters:

  • param – [in] The unicast group create parameters.

  • unicast_group – [out] Pointer to the unicast group created.

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_unicast_group_add_streams(struct bt_bap_unicast_group *unicast_group, struct bt_bap_unicast_group_stream_pair_param params[], size_t num_param)

Add streams to a unicast group as a unicast client.

This function can be used to add additional streams to a bt_bap_unicast_group.

This can be called at any time before any of the streams in the group has been started (see bt_bap_stream_ops.started()). This can also be called after the streams have been stopped (see bt_bap_stream_ops.stopped()).

Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a group, the group must be deleted with bt_bap_unicast_group_delete(), but this will require all streams in the group to be released first.

Parameters:

  • unicast_group – Pointer to the unicast group

  • params – Array of stream parameters with streams being added to the group.

  • num_param – Number of parameters in params.

Returns:

0 in case of success or negative value in case of error.

int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group)

Delete audio unicast group.

Delete a audio unicast group as a client. All streams in the group shall be in the idle or configured state.

Parameters:

  • unicast_group – Pointer to the unicast group to delete

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_unicast_client_register_cb(const struct bt_bap_unicast_client_cb *cb)

Register unicast client callbacks.

Only one callback structure can be registered, and attempting to registering more than one will result in an error.

Parameters:

  • cb – Unicast client callback structure.

Returns:

0 in case of success or negative value in case of error.

int bt_bap_unicast_client_discover(struct bt_conn *conn, enum bt_audio_dir dir)

Discover remote capabilities and endpoints.

This procedure is used by a client to discover remote capabilities and endpoints and notifies via params callback.

Parameters:

  • conn – Connection object

  • dir – The type of remote endpoints and capabilities to discover.

struct bt_bap_unicast_group_stream_param
#include <bap.h>

Parameter struct for each stream in the unicast group.

Public Members

struct bt_bap_stream *stream

Pointer to a stream object.

struct bt_audio_codec_qos *qos

The QoS settings for the stream object.

struct bt_bap_unicast_group_stream_pair_param
#include <bap.h>

Parameter struct for the unicast group functions.

Parameter struct for the bt_bap_unicast_group_create() and bt_bap_unicast_group_add_streams() functions.

Public Members

struct bt_bap_unicast_group_stream_param *rx_param

Pointer to a receiving stream parameters.

struct bt_bap_unicast_group_stream_param *tx_param

Pointer to a transmitting stream parameters.

struct bt_bap_unicast_group_param
#include <bap.h>

Parameters for the creating unicast groups with bt_bap_unicast_group_create()

Public Members

size_t params_count

The number of parameters in params.

struct bt_bap_unicast_group_stream_pair_param *params

Array of stream parameters.

uint8_t packing

Unicast Group packing mode.

BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED.

Note

This is a recommendation to the controller, which the controller may ignore.

uint8_t c_to_p_ft

Central to Peripheral flush timeout.

The flush timeout in multiples of ISO_Interval for each payload sent from the Central to Peripheral.

Value range from BT_ISO_FT_MIN to BT_ISO_FT_MAX

uint8_t p_to_c_ft

Peripheral to Central flush timeout.

The flush timeout in multiples of ISO_Interval for each payload sent from the Peripheral to Central.

Value range from BT_ISO_FT_MIN to BT_ISO_FT_MAX.

uint16_t iso_interval

ISO interval.

Time between consecutive CIS anchor points.

Value range from BT_ISO_ISO_INTERVAL_MIN to BT_ISO_ISO_INTERVAL_MAX.

struct bt_bap_unicast_client_cb
#include <bap.h>

Unicast Client callback structure.

Public Members

void (*location)(struct bt_conn *conn, enum bt_audio_dir dir, enum bt_audio_location loc)

Remote Unicast Server Audio Locations.

This callback is called whenever the audio locations is read from the server or otherwise notified to the client.

Param conn:

Connection to the remote unicast server.

Param dir:

Direction of the location.

Param loc:

The location bitfield value.

Return:

0 in case of success or negative value in case of error.

void (*available_contexts)(struct bt_conn *conn, enum bt_audio_context snk_ctx, enum bt_audio_context src_ctx)

Remote Unicast Server Available Contexts.

This callback is called whenever the available contexts are read from the server or otherwise notified to the client.

Param conn:

Connection to the remote unicast server.

Param snk_ctx:

The sink context bitfield value.

Param src_ctx:

The source context bitfield value.

Return:

0 in case of success or negative value in case of error.

void (*config)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_config() and bt_bap_stream_reconfig().

Called when the codec configure operation is completed on the server.

Param stream:

Stream the operation was performed on.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*qos)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_qos().

Called when the QoS configure operation is completed on the server. This will be called for each stream in the group that was being QoS configured.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*enable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_enable().

Called when the enable operation is completed on the server.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*start)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_start().

Called when the start operation is completed on the server. This will only be called if the stream supplied to bt_bap_stream_start() is for a BT_AUDIO_DIR_SOURCE endpoint.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*stop)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_stop().

Called when the stop operation is completed on the server. This will only be called if the stream supplied to bt_bap_stream_stop() is for a BT_AUDIO_DIR_SOURCE endpoint.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*disable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_disable().

Called when the disable operation is completed on the server.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*metadata)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_metadata().

Called when the metadata operation is completed on the server.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*release)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, enum bt_bap_ascs_reason reason)

Callback function for bt_bap_stream_release().

Called when the release operation is completed on the server.

Param stream:

Stream the operation was performed on. May be NULL if there is no stream associated with the ASE ID sent by the server.

Param rsp_code:

Response code.

Param reason:

Reason code.

void (*pac_record)(struct bt_conn *conn, enum bt_audio_dir dir, const struct bt_audio_codec_cap *codec_cap)

Remote Published Audio Capability (PAC) record discovered.

Called when a PAC record has been discovered as part of the discovery procedure.

The codec is only valid while in the callback, so the values must be stored by the receiver if future use is wanted.

If discovery procedure has complete both codec and ep are set to NULL.

Param conn:

Connection to the remote unicast server.

Param dir:

The type of remote endpoints and capabilities discovered.

Param codec_cap:

Remote capabilities.

void (*endpoint)(struct bt_conn *conn, enum bt_audio_dir dir, struct bt_bap_ep *ep)

Remote Audio Stream Endpoint (ASE) discovered.

Called when an ASE has been discovered as part of the discovery procedure.

If discovery procedure has complete both codec and ep are set to NULL.

Param conn:

Connection to the remote unicast server.

Param dir:

The type of remote endpoints and capabilities discovered.

Param ep:

Remote endpoint.

void (*discover)(struct bt_conn *conn, int err, enum bt_audio_dir dir)

BAP discovery callback function.

If discovery procedure has completed ep is set to NULL and err is 0.

If discovery procedure has complete both codec and ep are set to NULL.

Param conn:

Connection to the remote unicast server.

Param err:

Error value. 0 on success, GATT error on positive value or errno on negative value.

Param dir:

The type of remote endpoints and capabilities discovered.

group bt_bap_unicast_server

Typedefs

typedef void (*bt_bap_ep_func_t)(struct bt_bap_ep *ep, void *user_data)

The callback function called for each endpoint.

Param ep:

The structure object with endpoint info.

Param user_data:

Data to pass to the function.

Functions

int bt_bap_unicast_server_register_cb(const struct bt_bap_unicast_server_cb *cb)

Register unicast server callbacks.

Only one callback structure can be registered, and attempting to registering more than one will result in an error.

Parameters:

  • cb – Unicast server callback structure.

Returns:

0 in case of success or negative value in case of error.

int bt_bap_unicast_server_unregister_cb(const struct bt_bap_unicast_server_cb *cb)

Unregister unicast server callbacks.

May only unregister a callback structure that has previously been registered by bt_bap_unicast_server_register_cb().

Parameters:

  • cb – Unicast server callback structure.

Returns:

0 in case of success or negative value in case of error.

void bt_bap_unicast_server_foreach_ep(struct bt_conn *conn, bt_bap_ep_func_t func, void *user_data)

Iterate through all endpoints of the given connection.

Parameters:

  • conn – Connection object

  • func – Function to call for each endpoint.

  • user_data – Data to pass to the callback function.

int bt_bap_unicast_server_config_ase(struct bt_conn *conn, struct bt_bap_stream *stream, struct bt_audio_codec_cfg *codec_cfg, const struct bt_audio_codec_qos_pref *qos_pref)

Initialize and configure a new ASE.

Parameters:

  • conn – Connection object

  • stream – Configured stream object to be attached to the ASE

  • codec_cfg – Codec configuration

  • qos_pref – Audio Stream Quality of Service Preference

Returns:

0 in case of success or negative value in case of error.

struct bt_bap_unicast_server_cb
#include <bap.h>

Unicast Server callback structure.

Public Members

int (*config)(struct bt_conn *conn, const struct bt_bap_ep *ep, enum bt_audio_dir dir, const struct bt_audio_codec_cfg *codec_cfg, struct bt_bap_stream **stream, struct bt_audio_codec_qos_pref *const pref, struct bt_bap_ascs_rsp *rsp)

Endpoint config request callback.

Config callback is called whenever an endpoint is requested to be configured

Param conn:

[in] Connection object.

Param ep:

[in] Local Audio Endpoint being configured.

Param dir:

[in] Direction of the endpoint.

Param codec_cfg:

[in] Codec configuration.

Param stream:

[out] Pointer to stream that will be configured for the endpoint.

Param pref:

[out] Pointer to a QoS preference object that shall be populated with values. Invalid values will reject the codec configuration request.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*reconfig)(struct bt_bap_stream *stream, enum bt_audio_dir dir, const struct bt_audio_codec_cfg *codec_cfg, struct bt_audio_codec_qos_pref *const pref, struct bt_bap_ascs_rsp *rsp)

Stream reconfig request callback.

Reconfig callback is called whenever an Audio Stream needs to be reconfigured with different codec configuration.

Param stream:

[in] Stream object being reconfigured.

Param dir:

[in] Direction of the endpoint.

Param codec_cfg:

[in] Codec configuration.

Param pref:

[out] Pointer to a QoS preference object that shall be populated with values. Invalid values will reject the codec configuration request.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*qos)(struct bt_bap_stream *stream, const struct bt_audio_codec_qos *qos, struct bt_bap_ascs_rsp *rsp)

Stream QoS request callback.

QoS callback is called whenever an Audio Stream Quality of Service needs to be configured.

Param stream:

[in] Stream object being reconfigured.

Param qos:

[in] Quality of Service configuration.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*enable)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len, struct bt_bap_ascs_rsp *rsp)

Stream Enable request callback.

Enable callback is called whenever an Audio Stream is requested to be enabled to stream.

Param stream:

[in] Stream object being enabled.

Param meta:

[in] Metadata entries.

Param meta_len:

[in] Length of metadata.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*start)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp)

Stream Start request callback.

Start callback is called whenever an Audio Stream is requested to start streaming.

Param stream:

[in] Stream object.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*metadata)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len, struct bt_bap_ascs_rsp *rsp)

Stream Metadata update request callback.

Metadata callback is called whenever an Audio Stream is requested to update its metadata.

Param stream:

[in] Stream object.

Param meta:

[in] Metadata entries.

Param meta_len:

[in] Length of metadata.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*disable)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp)

Stream Disable request callback.

Disable callback is called whenever an Audio Stream is requested to disable the stream.

Param stream:

[in] Stream object being disabled.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*stop)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp)

Stream Stop callback.

Stop callback is called whenever an Audio Stream is requested to stop streaming.

Param stream:

[in] Stream object.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

int (*release)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp)

Stream release callback.

Release callback is called whenever a new Audio Stream needs to be released and thus deallocated.

Param stream:

[in] Stream object.

Param rsp:

[out] Object for the ASE operation response. Only used if the return value is non-zero.

Return:

0 in case of success or negative value in case of error.

group bt_bap_broadcast

BAP Broadcast APIs.

Functions

const struct bt_bap_base *bt_bap_base_get_base_from_ad(const struct bt_data *ad)

Generate a pointer to a BASE from periodic advertising data.

Parameters:

  • ad – The periodic advertising data

Return values:

  • NULL – if the data does not contain a BASE

  • Pointer – to a bt_bap_base structure

int bt_bap_base_get_size(const struct bt_bap_base *base)

Get the size of a BASE.

Parameters:

  • base – The BASE pointer

Return values:

  • -EINVAL – if arguments are invalid

  • The – size of the BASE

int bt_bap_base_get_pres_delay(const struct bt_bap_base *base)

Get the presentation delay value of a BASE.

Parameters:

  • base – The BASE pointer

Return values:

  • -EINVAL – if arguments are invalid

  • The – 24-bit presentation delay value

int bt_bap_base_get_subgroup_count(const struct bt_bap_base *base)

Get the subgroup count of a BASE.

Parameters:

  • base – The BASE pointer

Return values:

  • -EINVAL – if arguments are invalid

  • The – 8-bit subgroup count value

int bt_bap_base_get_bis_indexes(const struct bt_bap_base *base, uint32_t *bis_indexes)

Get all BIS indexes of a BASE.

Parameters:

  • base – [in] The BASE pointer

  • bis_indexes – [out] 32-bit BIS index bitfield that will be populated

Return values:

  • -EINVAL – if arguments are invalid

  • 0 – on success

int bt_bap_base_foreach_subgroup(const struct bt_bap_base *base, bool (*func)(const struct bt_bap_base_subgroup *subgroup, void *user_data), void *user_data)

Iterate on all subgroups in the BASE.

Parameters:

  • base – The BASE pointer

  • func – Callback function. Return true to continue iterating, or false to stop.

  • user_data – Userdata supplied to func

Return values:

  • -EINVAL – if arguments are invalid

  • -ECANCELED – if iterating over the subgroups stopped prematurely by func

  • 0 – if all subgroups were iterated

int bt_bap_base_get_subgroup_codec_id(const struct bt_bap_base_subgroup *subgroup, struct bt_bap_base_codec_id *codec_id)

Get the codec ID of a subgroup.

Parameters:

  • subgroup – [in] The subgroup pointer

  • codec_id – [out] Pointer to the struct where the results are placed

Return values:

  • -EINVAL – if arguments are invalid

  • 0 – on success

int bt_bap_base_get_subgroup_codec_data(const struct bt_bap_base_subgroup *subgroup, uint8_t **data)

Get the codec configuration data of a subgroup.

Parameters:

  • subgroup – [in] The subgroup pointer

  • data – [out] Pointer that will point to the resulting codec configuration data

Return values:

  • -EINVAL – if arguments are invalid

  • 0 – on success

int bt_bap_base_get_subgroup_codec_meta(const struct bt_bap_base_subgroup *subgroup, uint8_t **meta)

Get the codec metadata of a subgroup.

Parameters:

  • subgroup – [in] The subgroup pointer

  • meta – [out] Pointer that will point to the resulting codec metadata

Return values:

  • -EINVAL – if arguments are invalid

  • 0 – on success

int bt_bap_base_subgroup_codec_to_codec_cfg(const struct bt_bap_base_subgroup *subgroup, struct bt_audio_codec_cfg *codec_cfg)

Store subgroup codec data in a Codec config parsing APIs.

Parameters:

  • subgroup – [in] The subgroup pointer

  • codec_cfg – [out] Pointer to the struct where the results are placed

Return values:

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the codec_cfg cannot store the subgroup codec data

  • 0 – on success

int bt_bap_base_get_subgroup_bis_count(const struct bt_bap_base_subgroup *subgroup)

Get the BIS count of a subgroup.

Parameters:

  • subgroup – The subgroup pointer

Return values:

  • -EINVAL – if arguments are invalid

  • The – 8-bit BIS count value

int bt_bap_base_subgroup_get_bis_indexes(const struct bt_bap_base_subgroup *subgroup, uint32_t *bis_indexes)

Get all BIS indexes of a subgroup.

Parameters:

  • subgroup – [in] The subgroup pointer

  • bis_indexes – [out] 32-bit BIS index bitfield that will be populated

Return values:

  • -EINVAL – if arguments are invalid

  • 0 – on success

int bt_bap_base_subgroup_foreach_bis(const struct bt_bap_base_subgroup *subgroup, bool (*func)(const struct bt_bap_base_subgroup_bis *bis, void *user_data), void *user_data)

Iterate on all BIS in the subgroup.

Parameters:

  • subgroup – The subgroup pointer

  • func – Callback function. Return true to continue iterating, or false to stop.

  • user_data – Userdata supplied to func

Return values:

  • -EINVAL – if arguments are invalid

  • -ECANCELED – if iterating over the subgroups stopped prematurely by func

  • 0 – if all BIS were iterated

int bt_bap_base_subgroup_bis_codec_to_codec_cfg(const struct bt_bap_base_subgroup_bis *bis, struct bt_audio_codec_cfg *codec_cfg)

Store BIS codec configuration data in a Codec config parsing APIs.

This only sets the Codec config parsing APIs data and Codec config parsing APIs data_len, but is useful to use the BIS codec configuration data with the bt_audio_codec_cfg_* functions.

Parameters:

  • bis – [in] The BIS pointer

  • codec_cfg – [out] Pointer to the struct where the results are placed

Return values:

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the codec_cfg cannot store the subgroup codec data

  • 0 – on success

struct bt_bap_base_codec_id
#include <bap.h>

Codec ID structure for a Broadcast Audio Source Endpoint (BASE)

Public Members

uint8_t id

Codec ID.

uint16_t cid

Codec Company ID.

uint16_t vid

Codec Company Vendor ID.

struct bt_bap_base_subgroup_bis
#include <bap.h>

BIS structure for each BIS in a Broadcast Audio Source Endpoint (BASE) subgroup.

Public Members

uint8_t index

Unique index of the BIS.

uint8_t data_len

Codec Specific Data length.

uint8_t *data

Codec Specific Data.

group bt_bap_broadcast_sink

BAP Broadcast Sink APIs.

Functions

int bt_bap_broadcast_sink_register_cb(struct bt_bap_broadcast_sink_cb *cb)

Register Broadcast sink callbacks.

It is possible to register multiple struct of callbacks, but a single struct can only be registered once. Registering the same callback multiple times is undefined behavior and may break the stack.

Parameters:

  • cb – Broadcast sink callback structure.

Return values:

  • 0 – in case of success

  • -EINVAL – if cb is NULL

int bt_bap_broadcast_sink_create(struct bt_le_per_adv_sync *pa_sync, uint32_t broadcast_id, struct bt_bap_broadcast_sink **sink)

Create a Broadcast Sink from a periodic advertising sync.

This should only be done after verifying that the periodic advertising sync is from a Broadcast Source.

The created Broadcast Sink will need to be supplied to bt_bap_broadcast_sink_sync() in order to synchronize to the broadcast audio.

bt_bap_broadcast_sink_cb.pa_synced() will be called with the Broadcast Sink object created if this is successful.

Parameters:

  • pa_sync – Pointer to the periodic advertising sync object.

  • broadcast_id – 24-bit broadcast ID.

  • sink – [out] Pointer to the Broadcast Sink created.

Returns:

0 in case of success or errno value in case of error.

int bt_bap_broadcast_sink_sync(struct bt_bap_broadcast_sink *sink, uint32_t indexes_bitfield, struct bt_bap_stream *streams[], const uint8_t broadcast_code[16])

Sync to a broadcaster’s audio.

Example: The string “Broadcast Code” shall be [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]

Parameters:

  • sink – Pointer to the sink object from the base_recv callback.

  • indexes_bitfield – Bitfield of the BIS index to sync to. To sync to e.g. BIS index 1 and 2, this should have the value of BIT(1) | BIT(2).

  • streams – Stream object pointers to be used for the receiver. If multiple BIS indexes shall be synchronized, multiple streams shall be provided.

  • broadcast_code – The 16-octet broadcast code. Shall be supplied if the broadcast is encrypted (see bt_bap_broadcast_sink_cb::syncable). If the value is a string or a the value is less than 16 octets, the remaining octets shall be 0.

Returns:

0 in case of success or negative value in case of error.

int bt_bap_broadcast_sink_stop(struct bt_bap_broadcast_sink *sink)

Stop audio broadcast sink.

Stop an audio broadcast sink. The broadcast sink will stop receiving BIGInfo, and audio data can no longer be streamed.

Parameters:

  • sink – Pointer to the broadcast sink

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_sink_delete(struct bt_bap_broadcast_sink *sink)

Release a broadcast sink.

Once a broadcast sink has been allocated after the pa_synced callback, it can be deleted using this function. If the sink has synchronized to any broadcast audio streams, these must first be stopped using bt_bap_stream_stop.

Parameters:

  • sink – Pointer to the sink object to delete.

Returns:

0 in case of success or negative value in case of error.

struct bt_bap_broadcast_sink_cb
#include <bap.h>

Broadcast Audio Sink callback structure.

Public Members

void (*base_recv)(struct bt_bap_broadcast_sink *sink, const struct bt_bap_base *base, size_t base_size)

Broadcast Audio Source Endpoint (BASE) received.

Callback for when we receive a BASE from a broadcaster after syncing to the broadcaster’s periodic advertising.

Param sink:

Pointer to the sink structure.

Param base:

Broadcast Audio Source Endpoint (BASE).

Param base_size:

Size of the base

void (*syncable)(struct bt_bap_broadcast_sink *sink, const struct bt_iso_biginfo *biginfo)

Broadcast sink is syncable.

Called whenever a broadcast sink is not synchronized to audio, but the audio is synchronizable. This is inferred when a BIGInfo report is received.

Once this callback has been called, it is possible to call bt_bap_broadcast_sink_sync() to synchronize to the audio stream(s).

Param sink:

Pointer to the sink structure.

Param biginfo:

The BIGInfo report.

group bt_bap_broadcast_source

BAP Broadcast Source APIs.

Functions

int bt_bap_broadcast_source_create(struct bt_bap_broadcast_source_param *param, struct bt_bap_broadcast_source **source)

Create audio broadcast source.

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

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

No audio data can be sent until bt_bap_broadcast_source_start() has been called and no audio information (BIGInfo) will be visible to scanners (see bt_le_per_adv_sync_cb).

Parameters:

  • param – [in] Pointer to parameters used to create the broadcast source.

  • source – [out] Pointer to the broadcast source created

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_reconfig(struct bt_bap_broadcast_source *source, struct bt_bap_broadcast_source_param *param)

Reconfigure audio broadcast source.

Reconfigure an audio broadcast source with a new codec and codec quality of service parameters. This can only be done when the source is stopped.

Since this may modify the Broadcast Audio Source Endpoint (BASE), bt_bap_broadcast_source_get_base() should be called after this to get the new BASE information.

If the param.params_count is smaller than the number of subgroups that have been created in the Broadcast Source, only the first param.params_count subgroups are updated. If a stream exist in a subgroup not part of param, then that stream is left as is (i.e. it is not removed; the only way to remove a stream from a Broadcast Source is to recreate the Broadcast Source).

Parameters:

  • source – Pointer to the broadcast source

  • param – Pointer to parameters used to reconfigure the broadcast source.

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_update_metadata(struct bt_bap_broadcast_source *source, const uint8_t meta[], size_t meta_len)

Modify the metadata of an audio broadcast source.

Modify the metadata an audio broadcast source. This can only be done when the source is started. To update the metadata in the stopped state, use bt_bap_broadcast_source_reconfig().

Parameters:

  • source – Pointer to the broadcast source.

  • meta – Metadata.

  • meta_len – Length of metadata.

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_start(struct bt_bap_broadcast_source *source, struct bt_le_ext_adv *adv)

Start audio broadcast source.

Start an audio broadcast source with one or more audio streams. The broadcast source will start advertising BIGInfo, and audio data can be streamed.

Parameters:

  • source – Pointer to the broadcast source

  • adv – Pointer to an extended advertising set with periodic advertising configured.

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_stop(struct bt_bap_broadcast_source *source)

Stop audio broadcast source.

Stop an audio broadcast source. The broadcast source will stop advertising BIGInfo, and audio data can no longer be streamed.

Parameters:

  • source – Pointer to the broadcast source

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_delete(struct bt_bap_broadcast_source *source)

Delete audio broadcast source.

Delete an audio broadcast source. The broadcast source will stop advertising entirely, and the source can no longer be used.

Parameters:

  • source – Pointer to the broadcast source

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_get_id(struct bt_bap_broadcast_source *source, uint32_t *const broadcast_id)

Get the broadcast ID of a 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:

  • source – [in] Pointer to the broadcast source.

  • broadcast_id – [out] Pointer to the 3-octet broadcast ID.

Returns:

Zero on success or (negative) error code otherwise.

int bt_bap_broadcast_source_get_base(struct bt_bap_broadcast_source *source, struct net_buf_simple *base_buf)

Get the Broadcast Audio Stream Endpoint of a 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:

  • source – Pointer to the broadcast source.

  • base_buf – Pointer to a buffer where the BASE will be inserted.

Returns:

Zero on success or (negative) error code otherwise.

struct bt_bap_broadcast_source_stream_param
#include <bap.h>

Broadcast Source stream parameters.

Public Members

struct bt_bap_stream *stream

Audio stream.

size_t data_len

The number of elements in the data array.

The BIS specific data may be omitted and this set to 0.

uint8_t *data

BIS Codec Specific Configuration.

struct bt_bap_broadcast_source_subgroup_param
#include <bap.h>

Broadcast Source subgroup parameters.

Public Members

size_t params_count

The number of parameters in stream_params.

struct bt_bap_broadcast_source_stream_param *params

Array of stream parameters.

struct bt_audio_codec_cfg *codec_cfg

Subgroup Codec configuration.

struct bt_bap_broadcast_source_param
#include <bap.h>

Broadcast Source create parameters.

Public Members

size_t params_count

The number of parameters in subgroup_params.

struct bt_bap_broadcast_source_subgroup_param *params

Array of stream parameters.

struct bt_audio_codec_qos *qos

Quality of Service configuration.

uint8_t packing

Broadcast Source packing mode.

BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED.

Note

This is a recommendation to the controller, which the controller may ignore.

bool encryption

Whether or not to encrypt the streams.

uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]

Broadcast code.

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]

uint8_t irc

Immediate Repetition Count.

The number of times the scheduled payloads are transmitted in a given event.

Value range from BT_ISO_IRC_MIN to BT_ISO_IRC_MAX.

uint8_t pto

Pre-transmission offset.

Offset used for pre-transmissions.

Value range from BT_ISO_PTO_MIN to BT_ISO_PTO_MAX.

uint16_t iso_interval

ISO interval.

Time between consecutive BIS anchor points.

Value range from BT_ISO_ISO_INTERVAL_MIN to BT_ISO_ISO_INTERVAL_MAX.