Bluetooth Audio Volume Control
API Reference
- group bt_gatt_vcp
Volume Control Profile (VCP)
[Experimental] Users should note that the APIs can change as a part of ongoing development.
Defines
-
BT_VCP_VOL_REND_VOCS_CNT
-
BT_VCP_VOL_REND_AICS_CNT
-
BT_VCP_ERR_INVALID_COUNTER
Volume Control Service Error codes
-
BT_VCP_ERR_OP_NOT_SUPPORTED
-
BT_VCP_STATE_UNMUTED
Volume Control Service Mute Values
-
BT_VCP_STATE_MUTED
Functions
-
int bt_vcp_vol_rend_included_get(struct bt_vcp_included *included)
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.
- Parameters
included – [out] Pointer to store the result in.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_register(struct bt_vcp_vol_rend_register_param *param)
Register the Volume Control Service.
This will register and enable the service and make it discoverable by clients.
- Parameters
param – Volume Control Service register parameters.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_set_step(uint8_t volume_step)
Set the Volume Control Service volume step size.
Set the value that the volume changes, when changed relatively with e.g. bt_vcp_vol_rend_vol_down or bt_vcp_vol_rend_vol_up.
This can only be done as the server.
- Parameters
volume_step – The volume step size (1-255).
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_get_state(void)
Get the Volume Control Service volume state.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_get_flags(void)
Get the Volume Control Service flags.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_vol_down(void)
Turn the volume down by one step on the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_vol_up(void)
Turn the volume up by one step on the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_unmute_vol_down(void)
Turn the volume down and unmute the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_unmute_vol_up(void)
Turn the volume up and unmute the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_set_vol(uint8_t volume)
Set the volume on the server.
- Parameters
volume – The absolute volume to set.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_unmute(void)
Unmute the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_rend_mute(void)
Mute the server.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_cb_register(struct bt_vcp_vol_ctlr_cb *cb)
Registers the callbacks used by the Volume Controller.
- Parameters
cb – The callback structure.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_discover(struct bt_conn *conn, struct bt_vcp_vol_ctlr **vol_ctlr)
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 bt_vcp_vol_ctlr_cb::discover callback will notify when it is possible to start remote operations.
This shall only be done as the client,
- Parameters
conn – The connection to discover Volume Control Service for.
vol_ctlr – [out] Valid remote instance object on success.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_conn_get(const struct bt_vcp_vol_ctlr *vol_ctlr, struct bt_conn **conn)
Get the connection pointer of a client instance.
Get the Bluetooth connection pointer of a Volume Control Service client instance.
- Parameters
vol_ctlr – Volume Controller instance pointer.
conn – [out] Connection pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_included_get(struct bt_vcp_vol_ctlr *vol_ctlr, struct bt_vcp_included *included)
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.
- Parameters
vol_ctlr – Volume Controller instance pointer.
included – [out] Pointer to store the result in.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_read_state(struct bt_vcp_vol_ctlr *vol_ctlr)
Read the volume state of a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_read_flags(struct bt_vcp_vol_ctlr *vol_ctlr)
Read the volume flags of a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr)
Turn the volume down one step on a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr)
Turn the volume up one step on a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_unmute_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr)
Turn the volume down one step and unmute on a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_unmute_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr)
Turn the volume up one step and unmute on a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_set_vol(struct bt_vcp_vol_ctlr *vol_ctlr, uint8_t volume)
Set the absolute volume on a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
volume – The absolute volume to set.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_unmute(struct bt_vcp_vol_ctlr *vol_ctlr)
Unmute a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
int bt_vcp_vol_ctlr_mute(struct bt_vcp_vol_ctlr *vol_ctlr)
Mute a remote Volume Renderer.
- Parameters
vol_ctlr – Volume Controller instance pointer.
- Returns
0 if success, errno on failure.
-
struct bt_vcp_vol_rend_register_param
- #include <vcp.h>
Register structure for Volume Control Service
Public Members
-
uint8_t step
Initial step size (1-255)
-
uint8_t mute
Initial mute state (0-1)
-
uint8_t volume
Initial volume level (0-255)
-
struct bt_vocs_register_param vocs_param[0]
Register parameters for Volume Offset Control Services
-
struct bt_aics_register_param aics_param[0]
Register parameters for Audio Input Control Services
-
struct bt_vcp_vol_rend_cb *cb
Volume Control Service callback structure.
-
uint8_t step
-
struct bt_vcp_included
- #include <vcp.h>
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.
Public Members
-
uint8_t vocs_cnt
Number of Volume Offset Control Service instances
-
struct bt_vocs **vocs
Array of pointers to Volume Offset Control Service instances
-
uint8_t aics_cnt
Number of Audio Input Control Service instances
-
struct bt_aics **aics
Array of pointers to Audio Input Control Service instances
-
uint8_t vocs_cnt
-
struct bt_vcp_vol_rend_cb
- #include <vcp.h>
Public Members
-
void (*state)(int err, uint8_t volume, uint8_t mute)
Callback function for Volume Control Service volume state.
Called when the value is locally read with bt_vcp_vol_rend_get_state(), or if the state is changed by either the Volume Renderer or a remote Volume Controller.
- 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.
-
void (*flags)(int err, uint8_t flags)
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 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.
-
void (*state)(int err, uint8_t volume, uint8_t mute)
-
struct bt_vcp_vol_ctlr_cb
- #include <vcp.h>
Public Members
-
void (*state)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t volume, uint8_t mute)
Callback function for Volume Control Profile volume state.
Called when the value is remotely read as the Volume Controller. Called if the value is changed by either the Volume Renderer or Volume Controller, and notified to the to Volume Controller.
- Param vol_ctlr
Volume Controller 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 Renderer.
- Param mute
The mute setting of the Volume Renderer.
-
void (*flags)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t flags)
Callback function for Volume Control Profile volume flags.
Called when the value is remotely read as the Volume Controller. Called if the value is changed by the Volume Renderer.
A non-zero value indicates the the volume has been changed on the Volume Renderer since it was booted.
- Param vol_ctlr
Volume Controller 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 Renderer.
-
void (*discover)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t vocs_count, uint8_t aics_count)
Callback function for bt_vcp_vol_ctlr_discover().
This callback is called once the discovery procedure is completed.
- Param vol_ctlr
Volume Controller 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 the remote Volume Renderer.
- Param aics_count
Number of Audio Input Control Service instances the remote Volume Renderer.
-
void (*vol_down)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_vol_down().
Called when the volume down procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*vol_up)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_vol_up().
Called when the volume up procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*mute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_mute().
Called when the mute procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_unmute().
Called when the unmute procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*vol_down_unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_vol_down_unmute().
Called when the volume down and unmute procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*vol_up_unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_vol_up_unmute().
Called when the volume up and unmute procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*vol_set)(struct bt_vcp_vol_ctlr *vol_ctlr, int err)
Callback function for bt_vcp_vol_ctlr_vol_set().
Called when the set absolute volume procedure is completed.
- Param vol_ctlr
Volume Controller instance pointer.
- Param err
Error value. 0 on success, GATT error on positive value or errno on negative value.
-
void (*state)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t volume, uint8_t mute)
-
BT_VCP_VOL_REND_VOCS_CNT