The latest development version of this page may be more current than this released 3.7.0 version.

Bluetooth Audio Volume Control

API Reference

group bt_gatt_vcp

Volume Control Profile (VCP)

The Volume Control Profile (VCP) provides procedures to control the volume level and mute state on audio devices.

Since

2.7

Version

0.8.0

Volume Control Service Error codes

BT_VCP_ERR_INVALID_COUNTER

The Change_Counter operand value does not match the Change_Counter field value of the Volume State characteristic.

BT_VCP_ERR_OP_NOT_SUPPORTED

An invalid opcode has been used in a control point procedure.

Volume Control Service Mute Values

BT_VCP_STATE_UNMUTED

The volume state is unmuted.

BT_VCP_STATE_MUTED

The volume state is muted.

Defines

BT_VCP_VOL_REND_VOCS_CNT

Defines the maximum number of Volume Offset Control service instances for the Volume Control Profile Volume Renderer.

BT_VCP_VOL_REND_AICS_CNT

Defines the maximum number of Audio Input Control service instances for the Volume Control Profile Volume Renderer.

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.

Return values:

  • 0 – on success

  • -EINVAL – if cb is NULL

  • -EALREADY – if cb was already registered

int bt_vcp_vol_ctlr_cb_unregister(struct bt_vcp_vol_ctlr_cb *cb)

Unregisters the callbacks used by the Volume Controller.

Parameters:

  • cb – The callback structure.

Return values:

  • 0 – on success

  • -EINVAL – if cb is NULL

  • -EALREADY – if cb was not registered

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.

struct bt_vcp_vol_ctlr *bt_vcp_vol_ctlr_get_by_conn(const struct bt_conn *conn)

Get the volume controller from a connection pointer.

Get the Volume Control Profile Volume Controller pointer from a connection pointer. Only volume controllers that have been initiated via bt_vcp_vol_ctlr_discover() can be retrieved.

Parameters:

  • conn – Connection pointer.

Return values:

  • Pointer – to a Volume Control Profile Volume Controller instance

  • NULL – if conn is NULL or if the connection has not done discovery yet

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.

Requires that CONFIG_BT_VCP_VOL_CTLR_VOCS or CONFIG_BT_VCP_VOL_CTLR_AICS is enabled.

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.

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.

struct bt_vcp_vol_rend_cb
#include <vcp.h>

Struct to hold the Volume Renderer callbacks.

These can be registered for usage with bt_vcp_vol_rend_register().

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.

struct bt_vcp_vol_ctlr_cb
#include <vcp.h>

Struct to hold the Volume Controller callbacks.

These can be registered for usage with bt_vcp_vol_ctlr_cb_register().

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 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.

struct bt_vocs_cb vocs_cb

Volume Offset Control Service callbacks.

struct bt_aics_cb aics_cb

Audio Input Control Service callbacks.