51f2022f7b
Add support for setting initial values in bt_vcs_register_param when registering a VCS service Signed-off-by: Emil Gydesen <emil.gydesen@nordicsemi.no>
547 lines
16 KiB
C
547 lines
16 KiB
C
/*
|
|
* Copyright (c) 2020-2021 Nordic Semiconductor ASA
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCS_H_
|
|
#define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCS_H_
|
|
|
|
/**
|
|
* @brief Volume Control Service (VCS)
|
|
*
|
|
* @defgroup bt_gatt_vcs Volume Control Service (VCS)
|
|
*
|
|
* @ingroup bluetooth
|
|
* @{
|
|
*
|
|
* [Experimental] Users should note that the APIs can change
|
|
* as a part of ongoing development.
|
|
*/
|
|
|
|
#include <zephyr/types.h>
|
|
#include <bluetooth/audio/aics.h>
|
|
#include <bluetooth/audio/vocs.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if defined(CONFIG_BT_VCS)
|
|
#define BT_VCS_VOCS_CNT CONFIG_BT_VCS_VOCS_INSTANCE_COUNT
|
|
#define BT_VCS_AICS_CNT CONFIG_BT_VCS_AICS_INSTANCE_COUNT
|
|
#else
|
|
#define BT_VCS_VOCS_CNT 0
|
|
#define BT_VCS_AICS_CNT 0
|
|
#endif /* CONFIG_BT_VCS */
|
|
|
|
/** Volume Control Service Error codes */
|
|
#define BT_VCS_ERR_INVALID_COUNTER 0x80
|
|
#define BT_VCS_ERR_OP_NOT_SUPPORTED 0x81
|
|
|
|
/** Volume Control Service Mute Values */
|
|
#define BT_VCS_STATE_UNMUTED 0x00
|
|
#define BT_VCS_STATE_MUTED 0x01
|
|
|
|
/** @brief Opaque Volume Control Service instance. */
|
|
struct bt_vcs;
|
|
|
|
/** Register structure for Volume Control Service */
|
|
struct bt_vcs_register_param {
|
|
/** Initial step size (1-255) */
|
|
uint8_t step;
|
|
|
|
/** Initial mute state (0-1) */
|
|
uint8_t mute;
|
|
|
|
/** Initial volume level (0-255) */
|
|
uint8_t volume;
|
|
|
|
/** Register parameters for Volume Offset Control Services */
|
|
struct bt_vocs_register_param vocs_param[BT_VCS_VOCS_CNT];
|
|
|
|
/** Register parameters for Audio Input Control Services */
|
|
struct bt_aics_register_param aics_param[BT_VCS_AICS_CNT];
|
|
|
|
/** Volume Control Service callback structure. */
|
|
struct bt_vcs_cb *cb;
|
|
};
|
|
|
|
/**
|
|
* @brief Volume Control Service included services
|
|
*
|
|
* Used for to represent the Volume Control Service included service instances,
|
|
* for either a client or a server. The instance pointers either represent
|
|
* local server instances, or remote service instances.
|
|
*/
|
|
struct bt_vcs_included {
|
|
/** Number of Volume Offset Control Service instances */
|
|
uint8_t vocs_cnt;
|
|
/** Array of pointers to Volume Offset Control Service instances */
|
|
struct bt_vocs **vocs;
|
|
|
|
/** Number of Audio Input Control Service instances */
|
|
uint8_t aics_cnt;
|
|
/** Array of pointers to Audio Input Control Service instances */
|
|
struct bt_aics **aics;
|
|
};
|
|
|
|
/**
|
|
* @brief Register the Volume Control Service.
|
|
*
|
|
* This will register and enable the service and make it discoverable by
|
|
* clients.
|
|
*
|
|
* @param param Volume Control Service register parameters.
|
|
* @param[out] vcs Pointer to the registered Volume Control Service.
|
|
* This will still be valid if the return value is -EALREADY.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_register(struct bt_vcs_register_param *param, struct bt_vcs **vcs);
|
|
|
|
/**
|
|
* @brief Get Volume Control Service included services.
|
|
*
|
|
* Returns a pointer to a struct that contains information about the
|
|
* Volume Control Service included service instances, such as pointers to the
|
|
* Volume Offset Control Service (Volume Offset Control Service) or
|
|
* Audio Input Control Service (AICS) instances.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param[out] included Pointer to store the result in.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_included_get(struct bt_vcs *vcs, struct bt_vcs_included *included);
|
|
|
|
/**
|
|
* @brief Get the connection pointer of a client instance
|
|
*
|
|
* Get the Bluetooth connection pointer of a Volume Control Service
|
|
* client instance.
|
|
*
|
|
* @param vcs Volume Control Service client instance pointer.
|
|
* @param[out] conn Connection pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_client_conn_get(const struct bt_vcs *vcs, struct bt_conn **conn);
|
|
|
|
/**
|
|
* @brief Callback function for bt_vcs_discover.
|
|
*
|
|
* This callback is only used for the client.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param err Error value. 0 on success, GATT error on positive value
|
|
* or errno on negative value.
|
|
* @param vocs_count Number of Volume Offset Control Service instances
|
|
* on peer device.
|
|
* @param aics_count Number of Audio Input Control Service instances on
|
|
* peer device.
|
|
*/
|
|
typedef void (*bt_vcs_discover_cb)(struct bt_vcs *vcs, int err,
|
|
uint8_t vocs_count, uint8_t aics_count);
|
|
|
|
/**
|
|
* @brief Callback function for Volume Control Service volume state.
|
|
*
|
|
* Called when the value is locally read as the server.
|
|
* Called when the value is remotely read as the client.
|
|
* Called if the value is changed by either the server or client.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param err Error value. 0 on success, GATT error on positive value
|
|
* or errno on negative value.
|
|
* @param volume The volume of the Volume Control Service server.
|
|
* @param mute The mute setting of the Volume Control Service server.
|
|
*/
|
|
typedef void (*bt_vcs_state_cb)(struct bt_vcs *vcs, int err, uint8_t volume,
|
|
uint8_t mute);
|
|
|
|
/**
|
|
* @brief Callback function for Volume Control Service flags.
|
|
*
|
|
* Called when the value is locally read as the server.
|
|
* Called when the value is remotely read as the client.
|
|
* Called if the value is changed by either the server or client.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param err Error value. 0 on success, GATT error on positive value
|
|
* or errno on negative value.
|
|
* @param flags The flags of the Volume Control Service server.
|
|
*/
|
|
typedef void (*bt_vcs_flags_cb)(struct bt_vcs *vcs, int err, uint8_t flags);
|
|
|
|
/**
|
|
* @brief Callback function for writes.
|
|
*
|
|
* This callback is only used for the client.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param err Error value. 0 on success, GATT error on fail.
|
|
*/
|
|
typedef void (*bt_vcs_write_cb)(struct bt_vcs *vcs, int err);
|
|
|
|
struct bt_vcs_cb {
|
|
/* Volume Control Service */
|
|
bt_vcs_state_cb state;
|
|
bt_vcs_flags_cb flags;
|
|
#if defined(CONFIG_BT_VCS_CLIENT)
|
|
bt_vcs_discover_cb discover;
|
|
bt_vcs_write_cb vol_down;
|
|
bt_vcs_write_cb vol_up;
|
|
bt_vcs_write_cb mute;
|
|
bt_vcs_write_cb unmute;
|
|
bt_vcs_write_cb vol_down_unmute;
|
|
bt_vcs_write_cb vol_up_unmute;
|
|
bt_vcs_write_cb vol_set;
|
|
|
|
/* Volume Offset Control Service */
|
|
struct bt_vocs_cb vocs_cb;
|
|
|
|
/* Audio Input Control Service */
|
|
struct bt_aics_cb aics_cb;
|
|
#endif /* CONFIG_BT_VCS_CLIENT */
|
|
};
|
|
|
|
/**
|
|
* @brief Discover Volume Control Service and included services.
|
|
*
|
|
* This will start a GATT discovery and setup handles and subscriptions.
|
|
* This shall be called once before any other actions can be
|
|
* executed for the peer device, and the @ref bt_vcs_discover_cb callback
|
|
* will notify when it is possible to start remote operations.
|
|
*
|
|
* This shall only be done as the client,
|
|
*
|
|
* @param conn The connection to discover Volume Control Service for.
|
|
* @param[out] vcs Valid remote instance object on success.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_discover(struct bt_conn *conn, struct bt_vcs **vcs);
|
|
|
|
/**
|
|
* @brief Set the Volume Control Service volume step size.
|
|
*
|
|
* Set the value that the volume changes, when changed relatively with e.g.
|
|
* @ref bt_vcs_vol_down or @ref bt_vcs_vol_up.
|
|
*
|
|
* This can only be done as the server.
|
|
*
|
|
* @param volume_step The volume step size (1-255).
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vol_step_set(uint8_t volume_step);
|
|
|
|
/**
|
|
* @brief Read the Volume Control Service volume state.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vol_get(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Read the Volume Control Service flags.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_flags_get(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Turn the volume down by one step on the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vol_down(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Turn the volume up by one step on the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vol_up(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Turn the volume down and unmute the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_unmute_vol_down(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Turn the volume up and unmute the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_unmute_vol_up(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Set the volume on the server
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param volume The absolute volume to set.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vol_set(struct bt_vcs *vcs, uint8_t volume);
|
|
|
|
/**
|
|
* @brief Unmute the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_unmute(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Mute the server.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_mute(struct bt_vcs *vcs);
|
|
|
|
/**
|
|
* @brief Read the Volume Offset Control Service offset state.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_state_get(struct bt_vcs *vcs, struct bt_vocs *inst);
|
|
|
|
/**
|
|
* @brief Read the Volume Offset Control Service location.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_location_get(struct bt_vcs *vcs, struct bt_vocs *inst);
|
|
|
|
/**
|
|
* @brief Set the Volume Offset Control Service location.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
* @param location The location to set.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_location_set(struct bt_vcs *vcs, struct bt_vocs *inst,
|
|
uint8_t location);
|
|
|
|
/**
|
|
* @brief Set the Volume Offset Control Service offset state.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
* @param offset The offset to set (-255 to 255).
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_state_set(struct bt_vcs *vcs, struct bt_vocs *inst,
|
|
int16_t offset);
|
|
|
|
/**
|
|
* @brief Read the Volume Offset Control Service output description.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_description_get(struct bt_vcs *vcs, struct bt_vocs *inst);
|
|
|
|
/**
|
|
* @brief Set the Volume Offset Control Service description.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Volume Offset Control Service instance.
|
|
* @param description The description to set.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_vocs_description_set(struct bt_vcs *vcs, struct bt_vocs *inst,
|
|
const char *description);
|
|
|
|
/**
|
|
* @brief Deactivates an Audio Input Control Service instance.
|
|
*
|
|
* Audio Input Control Services are activated by default, but this will allow
|
|
* the server to deactivate an Audio Input Control Service.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_deactivate(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Activates an Audio Input Control Service instance.
|
|
*
|
|
* Audio Input Control Services are activated by default, but this will allow
|
|
* the server to reactivate an Audio Input Control Service instance after it has
|
|
* been deactivated with @ref bt_vcs_aics_deactivate.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_activate(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Read the Audio Input Control Service input state.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_state_get(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Read the Audio Input Control Service gain settings.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_gain_setting_get(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Read the Audio Input Control Service input type.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_type_get(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Read the Audio Input Control Service input status.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_status_get(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Mute the Audio Input Control Service input.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_mute(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Unmute the Audio Input Control Service input.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_unmute(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Set input gain to manual.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_manual_gain_set(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Set the input gain to automatic.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_automatic_gain_set(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Set the input gain.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
* @param gain The gain in dB to set (-128 to 127).
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_gain_set(struct bt_vcs *vcs, struct bt_aics *inst,
|
|
int8_t gain);
|
|
|
|
/**
|
|
* @brief Read the Audio Input Control Service description.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_description_get(struct bt_vcs *vcs, struct bt_aics *inst);
|
|
|
|
/**
|
|
* @brief Set the Audio Input Control Service description.
|
|
*
|
|
* @param vcs Volume Control Service instance pointer.
|
|
* @param inst Pointer to the Audio Input Control Service instance.
|
|
* @param description The description to set.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_aics_description_set(struct bt_vcs *vcs, struct bt_aics *inst,
|
|
const char *description);
|
|
|
|
/**
|
|
* @brief Registers the callbacks used by the Volume Control Service client.
|
|
*
|
|
* @param cb The callback structure.
|
|
*
|
|
* @return 0 if success, errno on failure.
|
|
*/
|
|
int bt_vcs_client_cb_register(struct bt_vcs_cb *cb);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCS_H_ */
|