Zephyr API Documentation  3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Volume Control Profile (VCP)

Volume Control Profile (VCP) More...

Data Structures

struct  bt_vcp_vol_rend_register_param
 Register structure for Volume Control Service. More...
 
struct  bt_vcp_included
 Volume Control Service included services. More...
 
struct  bt_vcp_vol_rend_cb
 Struct to hold the Volume Renderer callbacks. More...
 
struct  bt_vcp_vol_ctlr_cb
 Struct to hold the Volume Controller callbacks. More...
 

Macros

#define BT_VCP_VOL_REND_VOCS_CNT   0
 Defines the maximum number of Volume Offset Control service instances for the Volume Control Profile Volume Renderer.
 
#define BT_VCP_VOL_REND_AICS_CNT   0
 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.
 
int bt_vcp_vol_rend_register (struct bt_vcp_vol_rend_register_param *param)
 Register the Volume Control Service.
 
int bt_vcp_vol_rend_set_step (uint8_t volume_step)
 Set the Volume Control Service volume step size.
 
int bt_vcp_vol_rend_get_state (void)
 Get the Volume Control Service volume state.
 
int bt_vcp_vol_rend_get_flags (void)
 Get the Volume Control Service flags.
 
int bt_vcp_vol_rend_vol_down (void)
 Turn the volume down by one step on the server.
 
int bt_vcp_vol_rend_vol_up (void)
 Turn the volume up by one step on the server.
 
int bt_vcp_vol_rend_unmute_vol_down (void)
 Turn the volume down and unmute the server.
 
int bt_vcp_vol_rend_unmute_vol_up (void)
 Turn the volume up and unmute the server.
 
int bt_vcp_vol_rend_set_vol (uint8_t volume)
 Set the volume on the server.
 
int bt_vcp_vol_rend_unmute (void)
 Unmute the server.
 
int bt_vcp_vol_rend_mute (void)
 Mute the server.
 
int bt_vcp_vol_ctlr_cb_register (struct bt_vcp_vol_ctlr_cb *cb)
 Registers the callbacks used by the Volume Controller.
 
int bt_vcp_vol_ctlr_cb_unregister (struct bt_vcp_vol_ctlr_cb *cb)
 Unregisters the callbacks used by the Volume Controller.
 
int bt_vcp_vol_ctlr_discover (struct bt_conn *conn, struct bt_vcp_vol_ctlr **vol_ctlr)
 Discover Volume Control Service and included services.
 
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.
 
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.
 
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.
 
int bt_vcp_vol_ctlr_read_state (struct bt_vcp_vol_ctlr *vol_ctlr)
 Read the volume state of a remote Volume Renderer.
 
int bt_vcp_vol_ctlr_read_flags (struct bt_vcp_vol_ctlr *vol_ctlr)
 Read the volume flags of a remote Volume Renderer.
 
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.
 
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.
 
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.
 
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.
 
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.
 
int bt_vcp_vol_ctlr_unmute (struct bt_vcp_vol_ctlr *vol_ctlr)
 Unmute a remote Volume Renderer.
 
int bt_vcp_vol_ctlr_mute (struct bt_vcp_vol_ctlr *vol_ctlr)
 Mute a remote Volume Renderer.
 

Volume Control Service Error codes

#define BT_VCP_ERR_INVALID_COUNTER   0x80
 The Change_Counter operand value does not match the Change_Counter field value of the Volume State characteristic.
 
#define BT_VCP_ERR_OP_NOT_SUPPORTED   0x81
 An invalid opcode has been used in a control point procedure.
 

Volume Control Service Mute Values

#define BT_VCP_STATE_UNMUTED   0x00
 The volume state is unmuted.
 
#define BT_VCP_STATE_MUTED   0x01
 The volume state is muted.
 

Detailed Description

Volume Control Profile (VCP)

Since
2.7
Version
0.8.0

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

Macro Definition Documentation

◆ BT_VCP_ERR_INVALID_COUNTER

#define BT_VCP_ERR_INVALID_COUNTER   0x80

#include <zephyr/bluetooth/audio/vcp.h>

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

◆ BT_VCP_ERR_OP_NOT_SUPPORTED

#define BT_VCP_ERR_OP_NOT_SUPPORTED   0x81

#include <zephyr/bluetooth/audio/vcp.h>

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

◆ BT_VCP_STATE_MUTED

#define BT_VCP_STATE_MUTED   0x01

#include <zephyr/bluetooth/audio/vcp.h>

The volume state is muted.

◆ BT_VCP_STATE_UNMUTED

#define BT_VCP_STATE_UNMUTED   0x00

#include <zephyr/bluetooth/audio/vcp.h>

The volume state is unmuted.

◆ BT_VCP_VOL_REND_AICS_CNT

#define BT_VCP_VOL_REND_AICS_CNT   0

#include <zephyr/bluetooth/audio/vcp.h>

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

◆ BT_VCP_VOL_REND_VOCS_CNT

#define BT_VCP_VOL_REND_VOCS_CNT   0

#include <zephyr/bluetooth/audio/vcp.h>

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

Function Documentation

◆ bt_vcp_vol_ctlr_cb_register()

int bt_vcp_vol_ctlr_cb_register ( struct bt_vcp_vol_ctlr_cb cb)

#include <zephyr/bluetooth/audio/vcp.h>

Registers the callbacks used by the Volume Controller.

Parameters
cbThe callback structure.
Return values
0on success
-EINVALif cb is NULL
-EALREADYif cb was already registered

◆ bt_vcp_vol_ctlr_cb_unregister()

int bt_vcp_vol_ctlr_cb_unregister ( struct bt_vcp_vol_ctlr_cb cb)

#include <zephyr/bluetooth/audio/vcp.h>

Unregisters the callbacks used by the Volume Controller.

Parameters
cbThe callback structure.
Return values
0on success
-EINVALif cb is NULL
-EALREADYif cb was not registered

◆ bt_vcp_vol_ctlr_conn_get()

int bt_vcp_vol_ctlr_conn_get ( const struct bt_vcp_vol_ctlr *  vol_ctlr,
struct bt_conn **  conn 
)

#include <zephyr/bluetooth/audio/vcp.h>

Get the connection pointer of a client instance.

Get the Bluetooth connection pointer of a Volume Control Service client instance.

Parameters
vol_ctlrVolume Controller instance pointer.
[out]connConnection pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_discover()

int bt_vcp_vol_ctlr_discover ( struct bt_conn *  conn,
struct bt_vcp_vol_ctlr **  vol_ctlr 
)

#include <zephyr/bluetooth/audio/vcp.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_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
connThe connection to discover Volume Control Service for.
[out]vol_ctlrValid remote instance object on success.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_get_by_conn()

struct bt_vcp_vol_ctlr * bt_vcp_vol_ctlr_get_by_conn ( const struct bt_conn *  conn)

#include <zephyr/bluetooth/audio/vcp.h>

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
connConnection pointer.
Return values
Pointerto a Volume Control Profile Volume Controller instance
NULLif conn is NULL or if the connection has not done discovery yet

◆ bt_vcp_vol_ctlr_included_get()

int bt_vcp_vol_ctlr_included_get ( struct bt_vcp_vol_ctlr *  vol_ctlr,
struct bt_vcp_included included 
)

#include <zephyr/bluetooth/audio/vcp.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.

Requires that CONFIG_BT_VCP_VOL_CTLR_VOCS or CONFIG_BT_VCP_VOL_CTLR_AICS is enabled.

Parameters
vol_ctlrVolume Controller instance pointer.
[out]includedPointer to store the result in.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_mute()

int bt_vcp_vol_ctlr_mute ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Mute a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_read_flags()

int bt_vcp_vol_ctlr_read_flags ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Read the volume flags of a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_read_state()

int bt_vcp_vol_ctlr_read_state ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Read the volume state of a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_set_vol()

int bt_vcp_vol_ctlr_set_vol ( struct bt_vcp_vol_ctlr *  vol_ctlr,
uint8_t  volume 
)

#include <zephyr/bluetooth/audio/vcp.h>

Set the absolute volume on a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
volumeThe absolute volume to set.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_unmute()

int bt_vcp_vol_ctlr_unmute ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Unmute a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_unmute_vol_down()

int bt_vcp_vol_ctlr_unmute_vol_down ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume down one step and unmute on a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_unmute_vol_up()

int bt_vcp_vol_ctlr_unmute_vol_up ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume up one step and unmute on a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_vol_down()

int bt_vcp_vol_ctlr_vol_down ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume down one step on a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_ctlr_vol_up()

int bt_vcp_vol_ctlr_vol_up ( struct bt_vcp_vol_ctlr *  vol_ctlr)

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume up one step on a remote Volume Renderer.

Parameters
vol_ctlrVolume Controller instance pointer.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_get_flags()

int bt_vcp_vol_rend_get_flags ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Get the Volume Control Service flags.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_get_state()

int bt_vcp_vol_rend_get_state ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Get the Volume Control Service volume state.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_included_get()

int bt_vcp_vol_rend_included_get ( struct bt_vcp_included included)

#include <zephyr/bluetooth/audio/vcp.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
[out]includedPointer to store the result in.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_mute()

int bt_vcp_vol_rend_mute ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Mute the server.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_register()

int bt_vcp_vol_rend_register ( struct bt_vcp_vol_rend_register_param param)

#include <zephyr/bluetooth/audio/vcp.h>

Register the Volume Control Service.

This will register and enable the service and make it discoverable by clients.

Parameters
paramVolume Control Service register parameters.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_set_step()

int bt_vcp_vol_rend_set_step ( uint8_t  volume_step)

#include <zephyr/bluetooth/audio/vcp.h>

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_stepThe volume step size (1-255).
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_set_vol()

int bt_vcp_vol_rend_set_vol ( uint8_t  volume)

#include <zephyr/bluetooth/audio/vcp.h>

Set the volume on the server.

Parameters
volumeThe absolute volume to set.
Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_unmute()

int bt_vcp_vol_rend_unmute ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Unmute the server.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_unmute_vol_down()

int bt_vcp_vol_rend_unmute_vol_down ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume down and unmute the server.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_unmute_vol_up()

int bt_vcp_vol_rend_unmute_vol_up ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume up and unmute the server.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_vol_down()

int bt_vcp_vol_rend_vol_down ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume down by one step on the server.

Returns
0 if success, errno on failure.

◆ bt_vcp_vol_rend_vol_up()

int bt_vcp_vol_rend_vol_up ( void  )

#include <zephyr/bluetooth/audio/vcp.h>

Turn the volume up by one step on the server.

Returns
0 if success, errno on failure.