Volume Control Service (VCS) More...

Data Structures
struct	bt_vcs_register_param

struct	bt_vcs_included
	Volume Control Service included services. More...

struct	bt_vcs_cb

Macros
#define	BT_VCS_VOCS_CNT 0

#define	BT_VCS_AICS_CNT 0

#define	BT_VCS_ERR_INVALID_COUNTER 0x80

#define	BT_VCS_ERR_OP_NOT_SUPPORTED 0x81

#define	BT_VCS_STATE_UNMUTED 0x00

#define	BT_VCS_STATE_MUTED 0x01

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

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

typedef void(*	bt_vcs_flags_cb) (struct bt_vcs *vcs, int err, uint8_t flags)
	Callback function for Volume Control Service flags. More...

typedef void(*	bt_vcs_write_cb) (struct bt_vcs *vcs, int err)
	Callback function for writes. More...

Functions
int	bt_vcs_register (struct bt_vcs_register_param param, struct bt_vcs *vcs)
	Register the Volume Control Service. More...

int	bt_vcs_included_get (struct bt_vcs vcs, struct bt_vcs_included included)
	Get Volume Control Service included services. More...

int	bt_vcs_client_conn_get (const struct bt_vcs vcs, struct bt_conn *conn)
	Get the connection pointer of a client instance. More...

int	bt_vcs_discover (struct bt_conn conn, struct bt_vcs *vcs)
	Discover Volume Control Service and included services. More...

int	bt_vcs_vol_step_set (uint8_t volume_step)
	Set the Volume Control Service volume step size. More...

int	bt_vcs_vol_get (struct bt_vcs *vcs)
	Read the Volume Control Service volume state. More...

int	bt_vcs_flags_get (struct bt_vcs *vcs)
	Read the Volume Control Service flags. More...

int	bt_vcs_vol_down (struct bt_vcs *vcs)
	Turn the volume down by one step on the server. More...

int	bt_vcs_vol_up (struct bt_vcs *vcs)
	Turn the volume up by one step on the server. More...

int	bt_vcs_unmute_vol_down (struct bt_vcs *vcs)
	Turn the volume down and unmute the server. More...

int	bt_vcs_unmute_vol_up (struct bt_vcs *vcs)
	Turn the volume up and unmute the server. More...

int	bt_vcs_vol_set (struct bt_vcs *vcs, uint8_t volume)
	Set the volume on the server. More...

int	bt_vcs_unmute (struct bt_vcs *vcs)
	Unmute the server. More...

int	bt_vcs_mute (struct bt_vcs *vcs)
	Mute the server. More...

int	bt_vcs_vocs_state_get (struct bt_vcs vcs, struct bt_vocs inst)
	Read the Volume Offset Control Service offset state. More...

int	bt_vcs_vocs_location_get (struct bt_vcs vcs, struct bt_vocs inst)
	Read the Volume Offset Control Service location. More...

int	bt_vcs_vocs_location_set (struct bt_vcs vcs, struct bt_vocs inst, uint8_t location)
	Set the Volume Offset Control Service location. More...

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

int	bt_vcs_vocs_description_get (struct bt_vcs vcs, struct bt_vocs inst)
	Read the Volume Offset Control Service output description. More...

int	bt_vcs_vocs_description_set (struct bt_vcs vcs, struct bt_vocs inst, const char *description)
	Set the Volume Offset Control Service description. More...

int	bt_vcs_aics_deactivate (struct bt_vcs vcs, struct bt_aics inst)
	Deactivates an Audio Input Control Service instance. More...

int	bt_vcs_aics_activate (struct bt_vcs vcs, struct bt_aics inst)
	Activates an Audio Input Control Service instance. More...

int	bt_vcs_aics_state_get (struct bt_vcs vcs, struct bt_aics inst)
	Read the Audio Input Control Service input state. More...

int	bt_vcs_aics_gain_setting_get (struct bt_vcs vcs, struct bt_aics inst)
	Read the Audio Input Control Service gain settings. More...

int	bt_vcs_aics_type_get (struct bt_vcs vcs, struct bt_aics inst)
	Read the Audio Input Control Service input type. More...

int	bt_vcs_aics_status_get (struct bt_vcs vcs, struct bt_aics inst)
	Read the Audio Input Control Service input status. More...

int	bt_vcs_aics_mute (struct bt_vcs vcs, struct bt_aics inst)
	Mute the Audio Input Control Service input. More...

int	bt_vcs_aics_unmute (struct bt_vcs vcs, struct bt_aics inst)
	Unmute the Audio Input Control Service input. More...

int	bt_vcs_aics_manual_gain_set (struct bt_vcs vcs, struct bt_aics inst)
	Set input gain to manual. More...

int	bt_vcs_aics_automatic_gain_set (struct bt_vcs vcs, struct bt_aics inst)
	Set the input gain to automatic. More...

int	bt_vcs_aics_gain_set (struct bt_vcs vcs, struct bt_aics inst, int8_t gain)
	Set the input gain. More...

int	bt_vcs_aics_description_get (struct bt_vcs vcs, struct bt_aics inst)
	Read the Audio Input Control Service description. More...

int	bt_vcs_aics_description_set (struct bt_vcs vcs, struct bt_aics inst, const char *description)
	Set the Audio Input Control Service description. More...

int	bt_vcs_client_cb_register (struct bt_vcs_cb *cb)
	Registers the callbacks used by the Volume Control Service client. More...

Detailed Description

Volume Control Service (VCS)

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

Macro Definition Documentation

◆ BT_VCS_AICS_CNT

#define BT_VCS_AICS_CNT 0

#include <include/bluetooth/audio/vcs.h>

◆ BT_VCS_ERR_INVALID_COUNTER

#define BT_VCS_ERR_INVALID_COUNTER 0x80

#include <include/bluetooth/audio/vcs.h>

Volume Control Service Error codes

◆ BT_VCS_ERR_OP_NOT_SUPPORTED

#define BT_VCS_ERR_OP_NOT_SUPPORTED 0x81

#include <include/bluetooth/audio/vcs.h>

◆ BT_VCS_STATE_MUTED

#define BT_VCS_STATE_MUTED 0x01

#include <include/bluetooth/audio/vcs.h>

◆ BT_VCS_STATE_UNMUTED

#define BT_VCS_STATE_UNMUTED 0x00

#include <include/bluetooth/audio/vcs.h>

Volume Control Service Mute Values

◆ BT_VCS_VOCS_CNT

#define BT_VCS_VOCS_CNT 0

#include <include/bluetooth/audio/vcs.h>

Typedef Documentation

◆ bt_vcs_discover_cb

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

#include <include/bluetooth/audio/vcs.h>

Callback function for bt_vcs_discover.

This callback is only used for the client.

Parameters

vcs	Volume Control Service instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value.
vocs_count	Number of Volume Offset Control Service instances on peer device.
aics_count	Number of Audio Input Control Service instances on peer device.

◆ bt_vcs_flags_cb

typedef void(* bt_vcs_flags_cb) (struct bt_vcs *vcs, int err, uint8_t flags)

#include <include/bluetooth/audio/vcs.h>

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.

Parameters

vcs	Volume Control Service instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value.
flags	The flags of the Volume Control Service server.

◆ bt_vcs_state_cb

typedef void(* bt_vcs_state_cb) (struct bt_vcs *vcs, int err, uint8_t volume, uint8_t mute)

#include <include/bluetooth/audio/vcs.h>

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.

Parameters

vcs	Volume Control Service instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value.
volume	The volume of the Volume Control Service server.
mute	The mute setting of the Volume Control Service server.

◆ bt_vcs_write_cb

typedef void(* bt_vcs_write_cb) (struct bt_vcs *vcs, int err)

#include <include/bluetooth/audio/vcs.h>

Callback function for writes.

This callback is only used for the client.

Parameters

vcs	Volume Control Service instance pointer.
err	Error value. 0 on success, GATT error on fail.

Function Documentation

◆ bt_vcs_aics_activate()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_automatic_gain_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_deactivate()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_description_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_description_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_gain_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_gain_setting_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_manual_gain_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_mute()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_state_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_status_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_type_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_aics_unmute()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_client_cb_register()

int bt_vcs_client_cb_register ( struct bt_vcs_cb * cb )

#include <include/bluetooth/audio/vcs.h>

Registers the callbacks used by the Volume Control Service client.

Parameters

cb	The callback structure.

Returns: 0 if success, errno on failure.

◆ bt_vcs_client_conn_get()

int bt_vcs_client_conn_get	(	const struct bt_vcs *	vcs,
		struct bt_conn **	conn
	)

#include <include/bluetooth/audio/vcs.h>

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.
[out]	conn	Connection pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_discover()

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

#include <include/bluetooth/audio/vcs.h>

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.
[out]	vcs	Valid remote instance object on success.

Returns: 0 if success, errno on failure.

◆ bt_vcs_flags_get()

int bt_vcs_flags_get ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Read the Volume Control Service flags.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_included_get()

int bt_vcs_included_get	(	struct bt_vcs *	vcs,
		struct bt_vcs_included *	included
	)

#include <include/bluetooth/audio/vcs.h>

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.
[out]	included	Pointer to store the result in.

Returns: 0 if success, errno on failure.

◆ bt_vcs_mute()

int bt_vcs_mute ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Mute the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_register()

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

#include <include/bluetooth/audio/vcs.h>

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.
[out]	vcs	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.

◆ bt_vcs_unmute()

int bt_vcs_unmute ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Unmute the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_unmute_vol_down()

int bt_vcs_unmute_vol_down ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Turn the volume down and unmute the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_unmute_vol_up()

int bt_vcs_unmute_vol_up ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Turn the volume up and unmute the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_vocs_description_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vocs_description_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vocs_location_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vocs_location_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vocs_state_get()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vocs_state_set()

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

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vol_down()

int bt_vcs_vol_down ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Turn the volume down by one step on the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_vol_get()

int bt_vcs_vol_get ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Read the Volume Control Service volume state.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

◆ bt_vcs_vol_set()

int bt_vcs_vol_set	(	struct bt_vcs *	vcs,
		uint8_t	volume
	)

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vol_step_set()

int bt_vcs_vol_step_set ( uint8_t volume_step )

#include <include/bluetooth/audio/vcs.h>

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.

◆ bt_vcs_vol_up()

int bt_vcs_vol_up ( struct bt_vcs * vcs )

#include <include/bluetooth/audio/vcs.h>

Turn the volume up by one step on the server.

Parameters

vcs	Volume Control Service instance pointer.

Returns: 0 if success, errno on failure.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ BT_VCS_AICS_CNT

◆ BT_VCS_ERR_INVALID_COUNTER

◆ BT_VCS_ERR_OP_NOT_SUPPORTED

◆ BT_VCS_STATE_MUTED

◆ BT_VCS_STATE_UNMUTED

◆ BT_VCS_VOCS_CNT

Typedef Documentation

◆ bt_vcs_discover_cb

◆ bt_vcs_flags_cb

◆ bt_vcs_state_cb

◆ bt_vcs_write_cb

Function Documentation

◆ bt_vcs_aics_activate()

◆ bt_vcs_aics_automatic_gain_set()

◆ bt_vcs_aics_deactivate()

◆ bt_vcs_aics_description_get()

◆ bt_vcs_aics_description_set()

◆ bt_vcs_aics_gain_set()

◆ bt_vcs_aics_gain_setting_get()

◆ bt_vcs_aics_manual_gain_set()

◆ bt_vcs_aics_mute()

◆ bt_vcs_aics_state_get()

◆ bt_vcs_aics_status_get()

◆ bt_vcs_aics_type_get()

◆ bt_vcs_aics_unmute()

◆ bt_vcs_client_cb_register()

◆ bt_vcs_client_conn_get()

◆ bt_vcs_discover()

◆ bt_vcs_flags_get()

◆ bt_vcs_included_get()

◆ bt_vcs_mute()

◆ bt_vcs_register()

◆ bt_vcs_unmute()

◆ bt_vcs_unmute_vol_down()

◆ bt_vcs_unmute_vol_up()

◆ bt_vcs_vocs_description_get()

◆ bt_vcs_vocs_description_set()

◆ bt_vcs_vocs_location_get()

◆ bt_vcs_vocs_location_set()

◆ bt_vcs_vocs_state_get()

◆ bt_vcs_vocs_state_set()

◆ bt_vcs_vol_down()

◆ bt_vcs_vol_get()

◆ bt_vcs_vol_set()

◆ bt_vcs_vol_step_set()

◆ bt_vcs_vol_up()