blob: fde6c3c5bcc4b1e27e77c538526a00c412cf4d71 [file] [log] [blame]
/** @file
* @brief Header for Bluetooth BASS.
*
* Copyright (c) 2020 Bose Corporation
* Copyright (c) 2021 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BASS_
#define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BASS_
#include <zephyr/types.h>
#include <bluetooth/conn.h>
#if IS_ENABLED(CONFIG_BT_BASS)
#define BT_BASS_MAX_METADATA_LEN CONFIG_BT_BASS_MAX_METADATA_LEN
#define BT_BASS_MAX_SUBGROUPS CONFIG_BT_BASS_MAX_SUBGROUPS
#else
#define BT_BASS_MAX_METADATA_LEN 0
#define BT_BASS_MAX_SUBGROUPS 0
#endif
#define BT_BASS_BROADCAST_CODE_SIZE 16
#define BT_BASS_PA_STATE_NOT_SYNCED 0x00
#define BT_BASS_PA_STATE_INFO_REQ 0x01
#define BT_BASS_PA_STATE_SYNCED 0x02
#define BT_BASS_PA_STATE_FAILED 0x03
#define BT_BASS_PA_STATE_NO_PAST 0x04
#define BT_BASS_BIG_ENC_STATE_NO_ENC 0x00
#define BT_BASS_BIG_ENC_STATE_BCODE_REQ 0x01
#define BT_BASS_BIG_ENC_STATE_DEC 0x02
#define BT_BASS_BIG_ENC_STATE_BAD_CODE 0x03
#define BT_BASS_ERR_OPCODE_NOT_SUPPORTED 0x80
#define BT_BASS_ERR_INVALID_SRC_ID 0x81
#define BT_BASS_PA_INTERVAL_UNKNOWN 0xFFFF
#define BT_BASS_BROADCAST_MAX_ID 0xFFFFFF
#define BT_BASS_BIS_SYNC_NO_PREF 0xFFFFFFFF
struct bt_bass_subgroup {
uint32_t bis_sync;
uint32_t requested_bis_sync;
uint8_t metadata_len;
uint8_t metadata[BT_BASS_MAX_METADATA_LEN];
};
/* TODO: Only expose this as an opaque type */
struct bt_bass_recv_state {
uint8_t src_id;
bt_addr_le_t addr;
uint8_t adv_sid;
uint8_t req_pa_sync_value;
uint8_t pa_sync_state;
uint8_t encrypt_state;
uint32_t broadcast_id; /* 24 bits */
uint8_t bad_code[BT_BASS_BROADCAST_CODE_SIZE];
uint8_t num_subgroups;
struct bt_bass_subgroup subgroups[BT_BASS_MAX_SUBGROUPS];
};
struct bt_bass_cb {
void (*pa_synced)(struct bt_bass_recv_state *recv_state,
const struct bt_le_per_adv_sync_synced_info *info);
void (*pa_term)(struct bt_bass_recv_state *recv_state,
const struct bt_le_per_adv_sync_term_info *info);
void (*pa_recv)(struct bt_bass_recv_state *recv_state,
const struct bt_le_per_adv_sync_recv_info *info,
struct net_buf_simple *buf);
void (*biginfo)(struct bt_bass_recv_state *recv_state,
const struct bt_iso_biginfo *biginfo);
};
/**
* @brief Registers the callbacks used by BASS.
*/
void bt_bass_register_cb(struct bt_bass_cb *cb);
/**
* @brief Set the sync state of a receive state in the server
*
* @param src_id The source id used to identify the receive state.
* @param pa_sync_state The sync state of the PA.
* @param bis_synced Array of bitfields to set the BIS sync state for each
* subgroup.
* @param encrypted The BIG encryption state.
* @return int Error value. 0 on success, ERRNO on fail.
*/
int bt_bass_set_sync_state(uint8_t src_id, uint8_t pa_sync_state,
uint32_t bis_synced[BT_BASS_MAX_SUBGROUPS],
uint8_t encrypted);
/******************************** CLIENT API ********************************/
/**
* @brief Callback function for bt_bass_client_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.
*/
typedef void (*bt_bass_client_discover_cb)(struct bt_conn *conn, int err,
uint8_t recv_state_count);
/**
* @brief 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.
*/
typedef void (*bt_bass_client_scan_cb)(const struct bt_le_scan_recv_info *info,
uint32_t broadcast_id);
/**
* @brief 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.
*/
typedef void (*bt_bass_client_recv_state_cb)(struct bt_conn *conn, int err,
const struct bt_bass_recv_state *state);
/**
* @brief Callback function for when a receive state is removed.
*
* @param conn The connection to the Broadcast Audio Scan Service server.
* @param err Error value. 0 on success, GATT error on fail.
* @param src_id The receive state.
*/
typedef void (*bt_bass_client_recv_state_rem_cb)(struct bt_conn *conn, int err,
uint8_t src_id);
/**
* @brief Callback function for writes.
*
* @param conn The connection to the peer device.
* @param err Error value. 0 on success, GATT error on fail.
*/
typedef void (*bt_bass_client_write_cb)(struct bt_conn *conn, int err);
struct bt_bass_client_cb {
bt_bass_client_discover_cb discover;
bt_bass_client_scan_cb scan;
bt_bass_client_recv_state_cb recv_state;
bt_bass_client_recv_state_rem_cb recv_state_removed;
bt_bass_client_write_cb scan_start;
bt_bass_client_write_cb scan_stop;
bt_bass_client_write_cb add_src;
bt_bass_client_write_cb mod_src;
bt_bass_client_write_cb broadcast_code;
bt_bass_client_write_cb rem_src;
};
/**
* @brief 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.
*
* @param conn The connection
* @return int Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_discover(struct bt_conn *conn);
/**
* @brief 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 @p start_scan is true, is sent to the
* bt_bass_client_scan_cb callback.
*
* @param conn Connection to the Broadcast Audio Scan Service server.
* Used to let the server know that we are scanning.
* @param start_scan Start scanning if true. If false, the application should
* enable scan itself.
* @return int Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_scan_start(struct bt_conn *conn, bool start_scan);
/**
* @brief Stop remote scanning for BISes for a server.
*
* @param conn Connection to the server.
* @return int Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_scan_stop(struct bt_conn *conn);
/**
* @brief Registers the callbacks used by Broadcast Audio Scan Service client.
*/
void bt_bass_client_register_cb(struct bt_bass_client_cb *cb);
/** Parameters for adding a source to a Broadcast Audio Scan Service server */
struct bt_bass_add_src_param {
/** Address of the advertiser. */
bt_addr_le_t addr;
/** SID of the advertising set. */
uint8_t adv_sid;
/** Whether to sync to periodic advertisements. */
uint8_t pa_sync;
/** 24-bit broadcast ID */
uint32_t broadcast_id;
/**
* @brief Periodic advertising interval in milliseconds.
*
* BT_BASS_PA_INTERVAL_UNKNOWN if unknown.
*/
uint16_t pa_interval;
/** Number of subgroups */
uint8_t num_subgroups;
/** Pointer to array of subgroups */
struct bt_bass_subgroup *subgroups;
};
/**
* @brief Add a source on the server.
*
* @param conn Connection to the server.
* @param param Parameter struct.
*
* @return Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_add_src(struct bt_conn *conn,
struct bt_bass_add_src_param *param);
/** Parameters for modifying a source */
struct bt_bass_mod_src_param {
/** Source ID of the receive state. */
uint8_t src_id;
/** Whether to sync to periodic advertisements. */
uint8_t pa_sync;
/**
* @brief Periodic advertising interval.
*
* BT_BASS_PA_INTERVAL_UNKNOWN if unknown.
*/
uint16_t pa_interval;
/** Number of subgroups */
uint8_t num_subgroups;
/** Pointer to array of subgroups */
struct bt_bass_subgroup *subgroups;
};
/** @brief Modify a source on the server.
*
* @param conn Connection to the server.
* @param param Parameter struct.
*
* @return Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_mod_src(struct bt_conn *conn,
struct bt_bass_mod_src_param *param);
/** @brief Set a broadcast code to the specified receive state.
*
* @param conn Connection to the server.
* @param src_id Source ID of the receive state.
* @param broadcast_code The broadcast code.
*
* @return Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_set_broadcast_code(struct bt_conn *conn, uint8_t src_id,
uint8_t broadcast_code[BT_BASS_BROADCAST_CODE_SIZE]);
/** @brief Remove a source from the server.
*
* @param conn Connection to the server.
* @param src_id Source ID of the receive state.
*
* @return Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_rem_src(struct bt_conn *conn, uint8_t src_id);
/** @brief Read the specified receive state from the server.
*
* @param conn Connection to the server.
* @param idx The index of the receive start (0 up to the value from
* bt_bass_client_discover_cb)
*
* @return Error value. 0 on success, GATT error or ERRNO on fail.
*/
int bt_bass_client_read_recv_state(struct bt_conn *conn, uint8_t idx);
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BASS_ */