Line data Source code
1 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 1 : #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 1 : #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 1 : #define BT_VCP_ERR_INVALID_COUNTER 0x80
70 : /** An invalid opcode has been used in a control point procedure. */
71 1 : #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 1 : #define BT_VCP_STATE_UNMUTED 0x00
80 : /** The volume state is muted */
81 1 : #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 1 : struct bt_vcp_vol_rend_register_param {
89 : /** Initial step size (1-255) */
90 1 : uint8_t step;
91 :
92 : /** Initial mute state (0-1) */
93 1 : uint8_t mute;
94 :
95 : /** Initial volume level (0-255) */
96 1 : uint8_t volume;
97 :
98 : /** Register parameters for Volume Offset Control Services */
99 1 : struct bt_vocs_register_param vocs_param[BT_VCP_VOL_REND_VOCS_CNT];
100 :
101 : /** Register parameters for Audio Input Control Services */
102 1 : struct bt_aics_register_param aics_param[BT_VCP_VOL_REND_AICS_CNT];
103 :
104 : /** Volume Control Service callback structure. */
105 1 : 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 1 : struct bt_vcp_included {
116 : /** Number of Volume Offset Control Service instances */
117 1 : uint8_t vocs_cnt;
118 : /** Array of pointers to Volume Offset Control Service instances */
119 1 : struct bt_vocs **vocs;
120 :
121 : /** Number of Audio Input Control Service instances */
122 1 : uint8_t aics_cnt;
123 : /** Array of pointers to Audio Input Control Service instances */
124 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : void (*vol_set)(struct bt_vcp_vol_ctlr *vol_ctlr, int err);
401 :
402 : /** Volume Offset Control Service callbacks */
403 1 : struct bt_vocs_cb vocs_cb;
404 :
405 : /** Audio Input Control Service callbacks */
406 1 : struct bt_aics_cb aics_cb;
407 :
408 : /** @cond INTERNAL_HIDDEN */
409 : /** Internally used field for list handling */
410 : sys_snode_t _node;
411 : /** @endcond */
412 : };
413 :
414 : /**
415 : * @brief Registers the callbacks used by the Volume Controller.
416 : *
417 : * @param cb The callback structure.
418 : *
419 : * @retval 0 on success
420 : * @retval -EINVAL if @p cb is NULL
421 : * @retval -EALREADY if @p cb was already registered
422 : */
423 1 : int bt_vcp_vol_ctlr_cb_register(struct bt_vcp_vol_ctlr_cb *cb);
424 :
425 : /**
426 : * @brief Unregisters the callbacks used by the Volume Controller.
427 : *
428 : * @param cb The callback structure.
429 : *
430 : * @retval 0 on success
431 : * @retval -EINVAL if @p cb is NULL
432 : * @retval -EALREADY if @p cb was not registered
433 : */
434 1 : int bt_vcp_vol_ctlr_cb_unregister(struct bt_vcp_vol_ctlr_cb *cb);
435 :
436 : /**
437 : * @brief Discover Volume Control Service and included services.
438 : *
439 : * This will start a GATT discovery and setup handles and subscriptions.
440 : * This shall be called once before any other actions can be
441 : * executed for the peer device, and the
442 : * @ref bt_vcp_vol_ctlr_cb.discover callback will notify when it is possible to
443 : * start remote operations.
444 : *
445 : * This shall only be done as the client,
446 : *
447 : * @param conn The connection to discover Volume Control Service for.
448 : * @param[out] vol_ctlr Valid remote instance object on success.
449 : *
450 : * @return 0 if success, errno on failure.
451 : */
452 1 : int bt_vcp_vol_ctlr_discover(struct bt_conn *conn,
453 : struct bt_vcp_vol_ctlr **vol_ctlr);
454 :
455 : /**
456 : * @brief Get the volume controller from a connection pointer
457 : *
458 : * Get the Volume Control Profile Volume Controller pointer from a connection pointer.
459 : * Only volume controllers that have been initiated via bt_vcp_vol_ctlr_discover() can be
460 : * retrieved.
461 : *
462 : * @param conn Connection pointer.
463 : *
464 : * @retval Pointer to a Volume Control Profile Volume Controller instance
465 : * @retval NULL if @p conn is NULL or if the connection has not done discovery yet
466 : */
467 1 : struct bt_vcp_vol_ctlr *bt_vcp_vol_ctlr_get_by_conn(const struct bt_conn *conn);
468 :
469 : /**
470 : * @brief Get the connection pointer of a client instance
471 : *
472 : * Get the Bluetooth connection pointer of a Volume Control Service
473 : * client instance.
474 : *
475 : * @param vol_ctlr Volume Controller instance pointer.
476 : * @param[out] conn Connection pointer.
477 : *
478 : * @return 0 if success, errno on failure.
479 : */
480 1 : int bt_vcp_vol_ctlr_conn_get(const struct bt_vcp_vol_ctlr *vol_ctlr,
481 : struct bt_conn **conn);
482 :
483 : /**
484 : * @brief Get Volume Control Service included services.
485 : *
486 : * Returns a pointer to a struct that contains information about the
487 : * Volume Control Service included service instances, such as pointers to the
488 : * Volume Offset Control Service (Volume Offset Control Service) or
489 : * Audio Input Control Service (AICS) instances.
490 : *
491 : * Requires that @kconfig{CONFIG_BT_VCP_VOL_CTLR_VOCS} or @kconfig{CONFIG_BT_VCP_VOL_CTLR_AICS} is
492 : * enabled.
493 : *
494 : * @param vol_ctlr Volume Controller instance pointer.
495 : * @param[out] included Pointer to store the result in.
496 : *
497 : * @return 0 if success, errno on failure.
498 : */
499 1 : int bt_vcp_vol_ctlr_included_get(struct bt_vcp_vol_ctlr *vol_ctlr,
500 : struct bt_vcp_included *included);
501 :
502 : /**
503 : * @brief Read the volume state of a remote Volume Renderer.
504 : *
505 : * @param vol_ctlr Volume Controller instance pointer.
506 : *
507 : * @return 0 if success, errno on failure.
508 : */
509 1 : int bt_vcp_vol_ctlr_read_state(struct bt_vcp_vol_ctlr *vol_ctlr);
510 :
511 : /**
512 : * @brief Read the volume flags of a remote Volume Renderer.
513 : *
514 : * @param vol_ctlr Volume Controller instance pointer.
515 : *
516 : * @return 0 if success, errno on failure.
517 : */
518 1 : int bt_vcp_vol_ctlr_read_flags(struct bt_vcp_vol_ctlr *vol_ctlr);
519 :
520 : /**
521 : * @brief Turn the volume down one step on a remote Volume Renderer
522 : *
523 : * @param vol_ctlr Volume Controller instance pointer.
524 : *
525 : * @return 0 if success, errno on failure.
526 : */
527 1 : int bt_vcp_vol_ctlr_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr);
528 :
529 : /**
530 : * @brief Turn the volume up one step on a remote Volume Renderer
531 : *
532 : * @param vol_ctlr Volume Controller instance pointer.
533 : *
534 : * @return 0 if success, errno on failure.
535 : */
536 1 : int bt_vcp_vol_ctlr_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr);
537 :
538 : /**
539 : * @brief Turn the volume down one step and unmute on a remote Volume Renderer
540 : *
541 : * @param vol_ctlr Volume Controller instance pointer.
542 : *
543 : * @return 0 if success, errno on failure.
544 : */
545 1 : int bt_vcp_vol_ctlr_unmute_vol_down(struct bt_vcp_vol_ctlr *vol_ctlr);
546 :
547 : /**
548 : * @brief Turn the volume up one step and unmute on a remote Volume Renderer
549 : *
550 : * @param vol_ctlr Volume Controller instance pointer.
551 : *
552 : * @return 0 if success, errno on failure.
553 : */
554 1 : int bt_vcp_vol_ctlr_unmute_vol_up(struct bt_vcp_vol_ctlr *vol_ctlr);
555 :
556 : /**
557 : * @brief Set the absolute volume on a remote Volume Renderer
558 : *
559 : * @param vol_ctlr Volume Controller instance pointer.
560 : * @param volume The absolute volume to set.
561 : *
562 : * @return 0 if success, errno on failure.
563 : */
564 1 : int bt_vcp_vol_ctlr_set_vol(struct bt_vcp_vol_ctlr *vol_ctlr, uint8_t volume);
565 :
566 : /**
567 : * @brief Unmute a remote Volume Renderer.
568 : *
569 : * @param vol_ctlr Volume Controller instance pointer.
570 : *
571 : * @return 0 if success, errno on failure.
572 : */
573 1 : int bt_vcp_vol_ctlr_unmute(struct bt_vcp_vol_ctlr *vol_ctlr);
574 :
575 : /**
576 : * @brief Mute a remote Volume Renderer.
577 : *
578 : * @param vol_ctlr Volume Controller instance pointer.
579 : *
580 : * @return 0 if success, errno on failure.
581 : */
582 1 : int bt_vcp_vol_ctlr_mute(struct bt_vcp_vol_ctlr *vol_ctlr);
583 :
584 : #ifdef __cplusplus
585 : }
586 : #endif
587 :
588 : /**
589 : * @}
590 : */
591 :
592 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VCP_H_ */
|
