1 /** 2 * @file 3 * @brief Bluetooth Volume Control Profile (VCP) APIs. 4 */ 5 6 /* 7 * Copyright (c) 2020-2024 Nordic Semiconductor ASA 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 12 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCP_H_ 13 #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCP_H_ 14 15 /** 16 * @brief Volume Control Profile (VCP) 17 * 18 * @defgroup bt_vcp Volume Control Profile (VCP) 19 * 20 * @since 2.7 21 * @version 0.8.0 22 * 23 * @ingroup bluetooth 24 * @{ 25 * 26 * The Volume Control Profile (VCP) provides procedures to control the volume level and mute state 27 * on audio devices. 28 */ 29 30 #include <stdint.h> 31 32 #include <zephyr/bluetooth/audio/aics.h> 33 #include <zephyr/bluetooth/audio/vocs.h> 34 #include <zephyr/bluetooth/conn.h> 35 #include <zephyr/sys/slist.h> 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 * Defines the maximum number of Volume Offset Control service instances for the 43 * Volume Control Profile Volume Renderer 44 */ 45 #if defined(CONFIG_BT_VCP_VOL_REND) 46 #define BT_VCP_VOL_REND_VOCS_CNT CONFIG_BT_VCP_VOL_REND_VOCS_INSTANCE_COUNT 47 #else 48 #define BT_VCP_VOL_REND_VOCS_CNT 0 49 #endif /* CONFIG_BT_VCP_VOL_REND */ 50 51 /** 52 * Defines the maximum number of Audio Input Control service instances for the 53 * Volume Control Profile Volume Renderer 54 */ 55 #if defined(CONFIG_BT_VCP_VOL_REND) 56 #define BT_VCP_VOL_REND_AICS_CNT CONFIG_BT_VCP_VOL_REND_AICS_INSTANCE_COUNT 57 #else 58 #define BT_VCP_VOL_REND_AICS_CNT 0 59 #endif /* CONFIG_BT_VCP_VOL_REND */ 60 61 /** 62 * @name Volume Control Service Error codes 63 * @{ 64 */ 65 /** 66 * The Change_Counter operand value does not match the Change_Counter field value of the Volume 67 * State characteristic. 68 */ 69 #define BT_VCP_ERR_INVALID_COUNTER 0x80 70 /** An invalid opcode has been used in a control point procedure. */ 71 #define BT_VCP_ERR_OP_NOT_SUPPORTED 0x81 72 /** @} */ 73 74 /** 75 * @name Volume Control Service Mute Values 76 * @{ 77 */ 78 /** The volume state is unmuted */ 79 #define BT_VCP_STATE_UNMUTED 0x00 80 /** The volume state is muted */ 81 #define BT_VCP_STATE_MUTED 0x01 82 /** @} */ 83 84 /** @brief Opaque Volume Control Service instance. */ 85 struct bt_vcp_vol_ctlr; 86 87 /** Register structure for Volume Control Service */ 88 struct bt_vcp_vol_rend_register_param { 89 /** Initial step size (1-255) */ 90 uint8_t step; 91 92 /** Initial mute state (0-1) */ 93 uint8_t mute; 94 95 /** Initial volume level (0-255) */ 96 uint8_t volume; 97 98 /** Register parameters for Volume Offset Control Services */ 99 struct bt_vocs_register_param vocs_param[BT_VCP_VOL_REND_VOCS_CNT]; 100 101 /** Register parameters for Audio Input Control Services */ 102 struct bt_aics_register_param aics_param[BT_VCP_VOL_REND_AICS_CNT]; 103 104 /** Volume Control Service callback structure. */ 105 struct bt_vcp_vol_rend_cb *cb; 106 }; 107 108 /** 109 * @brief Volume Control Service included services 110 * 111 * Used for to represent the Volume Control Service included service instances, 112 * for either a client or a server. The instance pointers either represent 113 * local server instances, or remote service instances. 114 */ 115 struct bt_vcp_included { 116 /** Number of Volume Offset Control Service instances */ 117 uint8_t vocs_cnt; 118 /** Array of pointers to Volume Offset Control Service instances */ 119 struct bt_vocs **vocs; 120 121 /** Number of Audio Input Control Service instances */ 122 uint8_t aics_cnt; 123 /** Array of pointers to Audio Input Control Service instances */ 124 struct bt_aics **aics; 125 }; 126 127 /** 128 * @brief Get Volume Control Service included services. 129 * 130 * Returns a pointer to a struct that contains information about the 131 * Volume Control Service included service instances, such as pointers to the 132 * Volume Offset Control Service (Volume Offset Control Service) or 133 * Audio Input Control Service (AICS) instances. 134 * 135 * @param[out] included Pointer to store the result in. 136 * 137 * @return 0 if success, errno on failure. 138 */ 139 int bt_vcp_vol_rend_included_get(struct bt_vcp_included *included); 140 141 /** 142 * @brief Register the Volume Control Service. 143 * 144 * This will register and enable the service and make it discoverable by 145 * clients. 146 * 147 * @param param Volume Control Service register parameters. 148 * 149 * @return 0 if success, errno on failure. 150 */ 151 int bt_vcp_vol_rend_register(struct bt_vcp_vol_rend_register_param *param); 152 153 /** 154 * @brief Struct to hold the Volume Renderer callbacks 155 * 156 * These can be registered for usage with bt_vcp_vol_rend_register(). 157 */ 158 struct bt_vcp_vol_rend_cb { 159 /** 160 * @brief Callback function for Volume Control Service volume state. 161 * 162 * Called when the value is locally read with 163 * bt_vcp_vol_rend_get_state(), or if the state is changed by either 164 * the Volume Renderer or a remote Volume Controller. 165 * 166 * @param conn Pointer to the connection to a remote device if 167 * the change was caused by it, otherwise NULL. 168 * @param err Error value. 0 on success, GATT error on positive value 169 * or errno on negative value. 170 * @param volume The volume of the Volume Control Service server. 171 * @param mute The mute setting of the Volume Control Service server. 172 */ 173 void (*state)(struct bt_conn *conn, int err, uint8_t volume, uint8_t mute); 174 175 /** 176 * @brief Callback function for Volume Control Service flags. 177 * 178 * Called when the value is locally read as the server. 179 * Called when the value is remotely read as the client. 180 * Called if the value is changed by either the server or client. 181 * 182 * @param conn Pointer to the connection to a remote device if 183 * the change was caused by it, otherwise NULL. 184 * @param err Error value. 0 on success, GATT error on positive value 185 * or errno on negative value. 186 * @param flags The flags of the Volume Control Service server. 187 */ 188 void (*flags)(struct bt_conn *conn, int err, uint8_t flags); 189 }; 190 191 /** 192 * @brief Set the Volume Control Service volume step size. 193 * 194 * Set the value that the volume changes, when changed relatively with e.g. 195 * @ref bt_vcp_vol_rend_vol_down or @ref bt_vcp_vol_rend_vol_up. 196 * 197 * This can only be done as the server. 198 * 199 * @param volume_step The volume step size (1-255). 200 * 201 * @return 0 if success, errno on failure. 202 */ 203 int bt_vcp_vol_rend_set_step(uint8_t volume_step); 204 205 /** 206 * @brief Get the Volume Control Service volume state. 207 * 208 * @return 0 if success, errno on failure. 209 */ 210 int bt_vcp_vol_rend_get_state(void); 211 212 /** 213 * @brief Get the Volume Control Service flags. 214 * 215 * @return 0 if success, errno on failure. 216 */ 217 int bt_vcp_vol_rend_get_flags(void); 218 219 /** 220 * @brief Turn the volume down by one step on the server. 221 * 222 * @return 0 if success, errno on failure. 223 */ 224 int bt_vcp_vol_rend_vol_down(void); 225 226 /** 227 * @brief Turn the volume up by one step on the server. 228 * 229 * @return 0 if success, errno on failure. 230 */ 231 int bt_vcp_vol_rend_vol_up(void); 232 233 /** 234 * @brief Turn the volume down and unmute the server. 235 * 236 * @return 0 if success, errno on failure. 237 */ 238 int bt_vcp_vol_rend_unmute_vol_down(void); 239 240 /** 241 * @brief Turn the volume up and unmute the server. 242 * 243 * @return 0 if success, errno on failure. 244 */ 245 int bt_vcp_vol_rend_unmute_vol_up(void); 246 247 /** 248 * @brief Set the volume on the server 249 * 250 * @param volume The absolute volume to set. 251 * 252 * @return 0 if success, errno on failure. 253 */ 254 int bt_vcp_vol_rend_set_vol(uint8_t volume); 255 256 /** 257 * @brief Unmute the server. 258 * 259 * @return 0 if success, errno on failure. 260 */ 261 int bt_vcp_vol_rend_unmute(void); 262 263 /** 264 * @brief Mute the server. 265 * 266 * @return 0 if success, errno on failure. 267 */ 268 int bt_vcp_vol_rend_mute(void); 269 270 /** 271 * @brief Struct to hold the Volume Controller callbacks 272 * 273 * These can be registered for usage with bt_vcp_vol_ctlr_cb_register(). 274 */ 275 struct bt_vcp_vol_ctlr_cb { 276 /** 277 * @brief Callback function for Volume Control Profile volume state. 278 * 279 * Called when the value is remotely read as the Volume Controller. 280 * Called if the value is changed by either the Volume Renderer or 281 * Volume Controller, and notified to the to Volume Controller. 282 * 283 * @param vol_ctlr Volume Controller instance pointer. 284 * @param err Error value. 0 on success, GATT error on positive 285 * value or errno on negative value. 286 * @param volume The volume of the Volume Renderer. 287 * @param mute The mute setting of the Volume Renderer. 288 */ 289 void (*state)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t volume, 290 uint8_t mute); 291 292 /** 293 * @brief Callback function for Volume Control Profile volume flags. 294 * 295 * Called when the value is remotely read as the Volume Controller. 296 * Called if the value is changed by the Volume Renderer. 297 * 298 * A non-zero value indicates the volume has been changed on the 299 * Volume Renderer since it was booted. 300 * 301 * @param vol_ctlr Volume Controller instance pointer. 302 * @param err Error value. 0 on success, GATT error on positive 303 * value or errno on negative value. 304 * @param flags The flags of the Volume Renderer. 305 */ 306 307 void (*flags)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t flags); 308 309 /** 310 * @brief Callback function for bt_vcp_vol_ctlr_discover(). 311 * 312 * This callback is called once the discovery procedure is completed. 313 * 314 * @param vol_ctlr Volume Controller instance pointer. 315 * @param err Error value. 0 on success, GATT error on positive 316 * value or errno on negative value. 317 * @param vocs_count Number of Volume Offset Control Service instances 318 * on the remote Volume Renderer. 319 * @param aics_count Number of Audio Input Control Service instances 320 * the remote Volume Renderer. 321 */ 322 void (*discover)(struct bt_vcp_vol_ctlr *vol_ctlr, int err, uint8_t vocs_count, 323 uint8_t aics_count); 324 325 /** 326 * @brief Callback function for bt_vcp_vol_ctlr_vol_down(). 327 * 328 * Called when the volume down procedure is completed. 329 * 330 * @param vol_ctlr Volume Controller instance pointer. 331 * @param err Error value. 0 on success, GATT error on positive 332 * value or errno on negative value. 333 */ 334 void (*vol_down)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 335 336 /** 337 * @brief Callback function for bt_vcp_vol_ctlr_vol_up(). 338 * 339 * Called when the volume up procedure is completed. 340 * 341 * @param vol_ctlr Volume Controller instance pointer. 342 * @param err Error value. 0 on success, GATT error on positive 343 * value or errno on negative value. 344 */ 345 void (*vol_up)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 346 347 /** 348 * @brief Callback function for bt_vcp_vol_ctlr_mute(). 349 * 350 * Called when the mute procedure is completed. 351 * 352 * @param vol_ctlr Volume Controller instance pointer. 353 * @param err Error value. 0 on success, GATT error on positive 354 * value or errno on negative value. 355 */ 356 void (*mute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 357 358 /** 359 * @brief Callback function for bt_vcp_vol_ctlr_unmute(). 360 * 361 * Called when the unmute procedure is completed. 362 * 363 * @param vol_ctlr Volume Controller instance pointer. 364 * @param err Error value. 0 on success, GATT error on positive 365 * value or errno on negative value. 366 */ 367 void (*unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 368 369 /** 370 * @brief Callback function for bt_vcp_vol_ctlr_vol_down_unmute(). 371 * 372 * Called when the volume down and unmute procedure is completed. 373 * 374 * @param vol_ctlr Volume Controller instance pointer. 375 * @param err Error value. 0 on success, GATT error on positive 376 * value or errno on negative value. 377 */ 378 void (*vol_down_unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 379 380 /** 381 * @brief Callback function for bt_vcp_vol_ctlr_vol_up_unmute(). 382 * 383 * Called when the volume up and unmute procedure is completed. 384 * 385 * @param vol_ctlr Volume Controller instance pointer. 386 * @param err Error value. 0 on success, GATT error on positive 387 * value or errno on negative value. 388 */ 389 void (*vol_up_unmute)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 390 391 /** 392 * @brief Callback function for bt_vcp_vol_ctlr_vol_set(). 393 * 394 * Called when the set absolute volume procedure is completed. 395 * 396 * @param vol_ctlr Volume Controller instance pointer. 397 * @param err Error value. 0 on success, GATT error on positive 398 * value or errno on negative value. 399 */ 400 void (*vol_set)(struct bt_vcp_vol_ctlr *vol_ctlr, int err); 401 402 /** Volume Offset Control Service callbacks */ 403 struct bt_vocs_cb vocs_cb; 404 405 /** Audio Input Control Service callbacks */ 406 struct bt_aics_cb aics_cb; 407 408 /** @internal Internally used field for list handling */ 409 sys_snode_t _node; 410 }; 411 412 /** 413 * @brief Registers the callbacks used by the Volume Controller. 414 * 415 * @param cb The callback structure. 416 * 417 * @retval 0 on success 418 * @retval -EINVAL if @p cb is NULL 419 * @retval -EALREADY if @p cb was already registered 420 */ 421 int bt_vcp_vol_ctlr_cb_register(struct bt_vcp_vol_ctlr_cb *cb); 422 423 /** 424 * @brief Unregisters the callbacks used by the Volume Controller. 425 * 426 * @param cb The callback structure. 427 * 428 * @retval 0 on success 429 * @retval -EINVAL if @p cb is NULL 430 * @retval -EALREADY if @p cb was not registered 431 */ 432 int bt_vcp_vol_ctlr_cb_unregister(struct bt_vcp_vol_ctlr_cb *cb); 433 434 /** 435 * @brief Discover Volume Control Service and included services. 436 * 437 * This will start a GATT discovery and setup handles and subscriptions. 438 * This shall be called once before any other actions can be 439 * executed for the peer device, and the 440 * @ref bt_vcp_vol_ctlr_cb.discover callback will notify when it is possible to 441 * start remote operations. 442 * 443 * This shall only be done as the client, 444 * 445 * @param conn The connection to discover Volume Control Service for. 446 * @param[out] vol_ctlr Valid remote instance object on success. 447 * 448 * @return 0 if success, errno on failure. 449 */ 450 int bt_vcp_vol_ctlr_discover(struct bt_conn *conn, 451 struct bt_vcp_vol_ctlr **vol_ctlr); 452 453 /** 454 * @brief Get the volume controller from a connection pointer 455 * 456 * Get the Volume Control Profile Volume Controller pointer from a connection pointer. 457 * Only volume controllers that have been initiated via bt_vcp_vol_ctlr_discover() can be 458 * retrieved. 459 * 460 * @param conn Connection pointer. 461 * 462 * @retval Pointer to a Volume Control Profile Volume Controller instance 463 * @retval NULL if @p conn is NULL or if the connection has not done discovery yet 464 */ 465 struct bt_vcp_vol_ctlr *bt_vcp_vol_ctlr_get_by_conn(const struct bt_conn *conn); 466 467 /** 468 * @brief Get the connection pointer of a client instance 469 * 470 * Get the Bluetooth connection pointer of a Volume Control Service 471 * client instance. 472 * 473 * @param vol_ctlr Volume Controller instance pointer. 474 * @param[out] conn Connection pointer. 475 * 476 * @return 0 if success, errno on failure. 477 */ 478 int bt_vcp_vol_ctlr_conn_get(const struct bt_vcp_vol_ctlr *vol_ctlr, 479 struct bt_conn **conn); 480 481 /** 482 * @brief Get Volume Control Service included services. 483 * 484 * Returns a pointer to a struct that contains information about the 485 * Volume Control Service included service instances, such as pointers to the 486 * Volume Offset Control Service (Volume Offset Control Service) or 487 * Audio Input Control Service (AICS) instances. 488 * 489 * Requires that @kconfig{CONFIG_BT_VCP_VOL_CTLR_VOCS} or @kconfig{CONFIG_BT_VCP_VOL_CTLR_AICS} is 490 * enabled. 491 * 492 * @param vol_ctlr Volume Controller instance pointer. 493 * @param[out] included Pointer to store the result in. 494 * 495 * @return 0 if success, errno on failure. 496 */ 497 int bt_vcp_vol_ctlr_included_get(struct bt_vcp_vol_ctlr *vol_ctlr, 498 struct bt_vcp_included *included); 499 500 /** 501 * @brief Read the volume state of a remote Volume Renderer. 502 * 503 * @param vol_ctlr Volume Controller instance pointer. 504 * 505 * @return 0 if success, errno on failure. 506 */ 507 int bt_vcp_vol_ctlr_read_state(struct bt_vcp_vol_ctlr *vol_ctlr); 508 509 /** 510 * @brief Read the volume flags of a remote Volume Renderer. 511 * 512 * @param vol_ctlr Volume Controller instance pointer. 513 * 514 * @return 0 if success, errno on failure. 515 */ 516 int bt_vcp_vol_ctlr_read_flags(struct bt_vcp_vol_ctlr *vol_ctlr); 517 518 /** 519 * @brief Turn the volume down one step on a remote Volume Renderer 520 * 521 * @param vol_ctlr Volume Controller instance pointer. 522 * 523 * @return 0 if success, errno on failure. 524 */ 525 int bt_vcp_vol_ctlr_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr); 526 527 /** 528 * @brief Turn the volume up one step on a remote Volume Renderer 529 * 530 * @param vol_ctlr Volume Controller instance pointer. 531 * 532 * @return 0 if success, errno on failure. 533 */ 534 int bt_vcp_vol_ctlr_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr); 535 536 /** 537 * @brief Turn the volume down one step and unmute on a remote Volume Renderer 538 * 539 * @param vol_ctlr Volume Controller instance pointer. 540 * 541 * @return 0 if success, errno on failure. 542 */ 543 int bt_vcp_vol_ctlr_unmute_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr); 544 545 /** 546 * @brief Turn the volume up one step and unmute on a remote Volume Renderer 547 * 548 * @param vol_ctlr Volume Controller instance pointer. 549 * 550 * @return 0 if success, errno on failure. 551 */ 552 int bt_vcp_vol_ctlr_unmute_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr); 553 554 /** 555 * @brief Set the absolute volume on a remote Volume Renderer 556 * 557 * @param vol_ctlr Volume Controller instance pointer. 558 * @param volume The absolute volume to set. 559 * 560 * @return 0 if success, errno on failure. 561 */ 562 int bt_vcp_vol_ctlr_set_vol(struct bt_vcp_vol_ctlr *vol_ctlr, uint8_t volume); 563 564 /** 565 * @brief Unmute a remote Volume Renderer. 566 * 567 * @param vol_ctlr Volume Controller instance pointer. 568 * 569 * @return 0 if success, errno on failure. 570 */ 571 int bt_vcp_vol_ctlr_unmute(struct bt_vcp_vol_ctlr *vol_ctlr); 572 573 /** 574 * @brief Mute a remote Volume Renderer. 575 * 576 * @param vol_ctlr Volume Controller instance pointer. 577 * 578 * @return 0 if success, errno on failure. 579 */ 580 int bt_vcp_vol_ctlr_mute(struct bt_vcp_vol_ctlr *vol_ctlr); 581 582 #ifdef __cplusplus 583 } 584 #endif 585 586 /** 587 * @} 588 */ 589 590 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCP_H_ */ 591
