Bluetooth Audio Volume Control

API Reference

group bt_gatt_vcs

Volume Control Service (VCS)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Defines

BT_VCS_VOCS_CNT
BT_VCS_AICS_CNT
BT_VCS_ERR_INVALID_COUNTER

Volume Control Service Error codes

BT_VCS_ERR_OP_NOT_SUPPORTED
BT_VCS_STATE_UNMUTED

Volume Control Service Mute Values

BT_VCS_STATE_MUTED

Typedefs

typedef void (*bt_vcs_discover_cb)(struct bt_vcs *vcs, int err, uint8_t vocs_count, uint8_t aics_count)

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_state_cb)(struct bt_vcs *vcs, int err, uint8_t volume, uint8_t mute)

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_flags_cb)(struct bt_vcs *vcs, 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 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_write_cb)(struct bt_vcs *vcs, int err)

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.

Functions

int bt_vcs_register(struct bt_vcs_register_param *param, struct bt_vcs **vcs)

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.

  • vcs – [out] Pointer to the registered Volume Control Service. This will still be valid if the return value is -EALREADY.

Returns

0 if success, errno on failure.

int bt_vcs_included_get(struct bt_vcs *vcs, struct bt_vcs_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

  • vcs – Volume Control Service instance pointer.

  • included – [out] Pointer to store the result in.

Returns

0 if success, errno on failure.

int bt_vcs_client_conn_get(const struct bt_vcs *vcs, 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

  • vcs – Volume Control Service client instance pointer.

  • conn – [out] Connection pointer.

Returns

0 if success, errno on failure.

int bt_vcs_discover(struct bt_conn *conn, struct bt_vcs **vcs)

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

  • vcs – [out] Valid remote instance object on success.

Returns

0 if success, errno on failure.

int bt_vcs_vol_step_set(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_vcs_vol_down or bt_vcs_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_vcs_vol_get(struct bt_vcs *vcs)

Read the Volume Control Service volume state.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_flags_get(struct bt_vcs *vcs)

Read the Volume Control Service flags.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_vol_down(struct bt_vcs *vcs)

Turn the volume down by one step on the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_vol_up(struct bt_vcs *vcs)

Turn the volume up by one step on the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_unmute_vol_down(struct bt_vcs *vcs)

Turn the volume down and unmute the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_unmute_vol_up(struct bt_vcs *vcs)

Turn the volume up and unmute the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_vol_set(struct bt_vcs *vcs, uint8_t volume)

Set the volume on the server.

Parameters

  • vcs – Volume Control Service instance pointer.

  • volume – The absolute volume to set.

Returns

0 if success, errno on failure.

int bt_vcs_unmute(struct bt_vcs *vcs)

Unmute the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_mute(struct bt_vcs *vcs)

Mute the server.

Parameters

  • vcs – Volume Control Service instance pointer.

Returns

0 if success, errno on failure.

int bt_vcs_vocs_state_get(struct bt_vcs *vcs, struct bt_vocs *inst)

Read the Volume Offset Control Service offset state.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_vocs_location_get(struct bt_vcs *vcs, struct bt_vocs *inst)

Read the Volume Offset Control Service location.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_vocs_location_set(struct bt_vcs *vcs, struct bt_vocs *inst, uint8_t location)

Set the Volume Offset Control Service location.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

  • location – The location to set.

Returns

0 if success, errno on failure.

int bt_vcs_vocs_state_set(struct bt_vcs *vcs, struct bt_vocs *inst, int16_t offset)

Set the Volume Offset Control Service offset state.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

  • offset – The offset to set (-255 to 255).

Returns

0 if success, errno on failure.

int bt_vcs_vocs_description_get(struct bt_vcs *vcs, struct bt_vocs *inst)

Read the Volume Offset Control Service output description.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_vocs_description_set(struct bt_vcs *vcs, struct bt_vocs *inst, const char *description)

Set the Volume Offset Control Service description.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Volume Offset Control Service instance.

  • description – The description to set.

Returns

0 if success, errno on failure.

int bt_vcs_aics_deactivate(struct bt_vcs *vcs, struct bt_aics *inst)

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.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_activate(struct bt_vcs *vcs, struct bt_aics *inst)

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

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_state_get(struct bt_vcs *vcs, struct bt_aics *inst)

Read the Audio Input Control Service input state.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_gain_setting_get(struct bt_vcs *vcs, struct bt_aics *inst)

Read the Audio Input Control Service gain settings.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_type_get(struct bt_vcs *vcs, struct bt_aics *inst)

Read the Audio Input Control Service input type.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_status_get(struct bt_vcs *vcs, struct bt_aics *inst)

Read the Audio Input Control Service input status.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_mute(struct bt_vcs *vcs, struct bt_aics *inst)

Mute the Audio Input Control Service input.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_unmute(struct bt_vcs *vcs, struct bt_aics *inst)

Unmute the Audio Input Control Service input.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_manual_gain_set(struct bt_vcs *vcs, struct bt_aics *inst)

Set input gain to manual.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_automatic_gain_set(struct bt_vcs *vcs, struct bt_aics *inst)

Set the input gain to automatic.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_gain_set(struct bt_vcs *vcs, struct bt_aics *inst, int8_t gain)

Set the input gain.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

  • gain – The gain in dB to set (-128 to 127).

Returns

0 if success, errno on failure.

int bt_vcs_aics_description_get(struct bt_vcs *vcs, struct bt_aics *inst)

Read the Audio Input Control Service description.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

Returns

0 if success, errno on failure.

int bt_vcs_aics_description_set(struct bt_vcs *vcs, struct bt_aics *inst, const char *description)

Set the Audio Input Control Service description.

Parameters

  • vcs – Volume Control Service instance pointer.

  • inst – Pointer to the Audio Input Control Service instance.

  • description – The description to set.

Returns

0 if success, errno on failure.

int bt_vcs_client_cb_register(struct bt_vcs_cb *cb)

Registers the callbacks used by the Volume Control Service client.

Parameters

  • cb – The callback structure.

Returns

0 if success, errno on failure.

struct bt_vcs_register_param
#include <vcs.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_vcs_cb *cb

Volume Control Service callback structure.

struct bt_vcs_included
#include <vcs.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_vcs_cb
#include <vcs.h>