1.. _bluetooth_le_audio_arch: 2 3LE Audio Stack 4############## 5 6.. graphviz:: 7 :caption: Bluetooth Audio Architecture 8 9 digraph bluetooth_audio_arch { 10 r [shape=record, width=5, height=3 11 label="{{TMAP | HAP | PBP | GMAP | ...} | 12 GAF | 13 {{{ GATT | GAP } | Low-level protocols (L2CAP, ATT, etc.)} | GAP | ISO} 14 | HCI Driver (USB, UART, SPI, virtual, etc.)}" 15 ]; 16 } 17 18Overall design 19************** 20 21The overall design of the LE Audio stack is that the implementation follows the specifications 22as closely as possible, 23both in terms of structure but also naming. 24Most API functions are prefixed by the specification acronym 25(e.g. ``bt_bap`` for the Basic Audio Profile (BAP) and ``bt_vcp`` for the Volume Control Profile 26(VCP)). The functions are then further prefixed with the specific role from each profile where 27applicable (e.g. :c:func:`bt_bap_unicast_client_discover` and :c:func:`bt_vcp_vol_rend_set_vol`). 28There are usually a function per procedure defined by the profile or service specifications, 29and additional helper or meta functions that do not correspond to procedures. 30 31The structure of the files generally also follow this, 32where BAP related files are prefixed with ``bap`` and VCP related files are prefixed with ``vcp``. 33If the file is specific for a profile role, the role is also embedded in the file name. 34 35Generic Audio Framework (GAF) 36***************************** 37The Generic Audio Framework (GAF) is considered the middleware of the Bluetooth 38LE Audio architecture. The GAF contains the profiles and services that allows 39higher layer applications and profiles to set up streams, change volume, control 40media and telephony and more. The GAF builds on GATT, GAP and isochronous 41channels (ISO). 42 43GAF uses GAP to connect, advertise and synchronize to other devices. 44GAF uses GATT to configure streams, associate streams with content 45(e.g. media or telephony), control volume and more. 46GAF uses ISO for the audio streams themselves, both as unicast (connected) 47audio streams or broadcast (unconnected) audio streams. 48 49GAF mandates the use of the LC3 codec, but also supports other codecs. 50 51.. graphviz:: 52 :caption: Generic Audio Framework (GAF) 53 54 digraph gaf { 55 node [shape=record]; 56 edge [style=invis]; 57 compound=true; 58 nodesep=0.1; 59 60 subgraph hap_layer { 61 cluster=true; 62 label="HAP"; 63 HAS; 64 BAS [style=dashed]; 65 IAS [style=dashed]; 66 } 67 68 subgraph pbp_layer { 69 cluster=true; 70 label="PBP"; 71 PBS[style=invis]; // Make it possible to treat PBP like the others 72 } 73 74 subgraph tmap_layer { 75 cluster=true; 76 label="TMAP"; 77 TMAS; 78 } 79 80 subgraph gmap_layer { 81 cluster=true; 82 label="GMAP"; 83 GMAS; 84 } 85 86 subgraph gaf_layer { 87 cluster=true; 88 label="Generic Audio Framework"; 89 90 subgraph transition_and_coordination_control_layer { 91 cluster=true; 92 label="Transition and Coordination Control"; 93 style=dashed; 94 95 subgraph cap_layer { 96 cluster=true; 97 style=solid; 98 label="CAP"; 99 CAS; 100 } 101 102 subgraph csip_layer { 103 cluster=true; 104 style=solid; 105 label="CSIP"; 106 CSIS; 107 } 108 } 109 110 subgraph stream_control_layer { 111 cluster=true; 112 label="Stream Control"; 113 style=dashed; 114 115 subgraph bap_layer { 116 cluster=true; 117 label="BAP"; 118 style=solid; 119 PACS [style=dashed]; 120 ASCS [style=dashed]; 121 BASS [style=dashed]; 122 } 123 } 124 125 subgraph content_control_layer { 126 cluster=true; 127 label="Content Control"; 128 style=dashed; 129 130 subgraph mcp_layer { 131 cluster=true; 132 label="MCP"; 133 style=solid; 134 MCS; 135 } 136 137 subgraph ccp_layer { 138 cluster=true; 139 label="CCP"; 140 style=solid; 141 TBS; 142 } 143 } 144 145 subgraph rendering_and_capture_control_layer { 146 cluster=true; 147 label="Rendering and Capture Control"; 148 style=dashed; 149 150 subgraph micp_layer { 151 cluster=true; 152 label="MICP"; 153 style=solid; 154 MICS; 155 MICP_AICS [style=dashed]; 156 } 157 158 subgraph vcp_layer { 159 cluster=true; 160 label="VCP"; 161 style=solid; 162 VCS; 163 VOCS [style=dashed]; 164 VCP_AICS [style=dashed]; 165 } 166 } 167 } 168 169 HAS -> CAS; 170 PBS -> CAS; 171 TMAS -> CAS; 172 GMAS -> CAS; 173 174 CAS -> MCS; 175 CAS -> TBS; 176 CAS -> ASCS; 177 CAS -> PACS; 178 CAS -> BASS; 179 CAS -> MICS; 180 CAS -> MICP_AICS; 181 CAS -> VCS; 182 CAS -> VOCS; 183 CAS -> VCP_AICS; 184 185 CSIS -> MCS; 186 CSIS -> TBS; 187 CSIS -> ASCS; 188 CSIS -> PACS; 189 CSIS -> BASS; 190 CSIS -> MICS; 191 CSIS -> MICP_AICS; 192 CSIS -> VCS; 193 CSIS -> VOCS; 194 CSIS -> VCP_AICS; 195 } 196 197The top-level profiles TMAP and HAP are not part of the GAF, but rather provide 198top-level requirements for how to use the GAF. 199 200GAF and the top layer profiles gave been implemented in Zephyr with the following structure. 201 202.. graphviz:: 203 :caption: Zephyr Generic Audio Framework 204 205 digraph gaf { 206 node [shape=record]; 207 edge [style=invis]; 208 compound=true; 209 nodesep=0.1; 210 211 subgraph hap_layer { 212 cluster=true; 213 label="HAP"; 214 HAS_H [label="has.h"]; 215 BAS_H [label="bas.h"]; 216 IAS_H [label="ias.h"]; 217 } 218 219 subgraph pbp_layer { 220 cluster=true; 221 label="PBP"; 222 PBP_H [label="pbp.h"]; // Make it possible to treat PBP like the others 223 } 224 225 subgraph tmap_layer { 226 cluster=true; 227 label="TMAP"; 228 TMAP_H [label="tmap.h"]; 229 } 230 231 subgraph gmap_layer { 232 cluster=true; 233 label="GMAP"; 234 GMAP_H [label="gmap.h"]; 235 GMAP_PRESET_H [label="gmap_lc3_preset.h"]; 236 } 237 238 subgraph gaf_layer { 239 cluster=true; 240 label="Generic Audio Framework"; 241 AUDIO_H [label="audio.h"]; 242 LC3_H [label="lc3.h"]; 243 244 subgraph transition_and_coordination_control_layer { 245 cluster=true; 246 label="Transition and Coordination Control"; 247 style=dashed; 248 249 subgraph cap_layer { 250 cluster=true; 251 style=solid; 252 label="CAP"; 253 CAP_H [label="cap.h"]; 254 } 255 256 subgraph csip_layer { 257 cluster=true; 258 style=solid; 259 label="CSIP"; 260 CSIP_H [label="csip.h"]; 261 } 262 } 263 264 subgraph stream_control_layer { 265 cluster=true; 266 label="Stream Control"; 267 style=dashed; 268 269 subgraph bap_layer { 270 cluster=true; 271 label="BAP"; 272 style=solid; 273 PACS_H [label="pacs.h"]; 274 BAP_H [label="bap.h"]; 275 BAP_PRESET_H [label="bap_lc3_preset.h"]; 276 } 277 } 278 279 subgraph content_control_layer { 280 cluster=true; 281 label="Content Control"; 282 style=dashed; 283 284 subgraph mcp_layer { 285 cluster=true; 286 label="MCP"; 287 style=solid; 288 MCS_H [label="mcs.h"]; 289 MCC_H [label="mcc.h"]; 290 MP_H [label="media_proxy.h"]; 291 } 292 293 subgraph ccp_layer { 294 cluster=true; 295 label="CCP"; 296 style=solid; 297 CCP_H [label="ccp.h"]; 298 TBS_H [label="tbs.h"]; 299 } 300 } 301 302 subgraph rendering_and_capture_control_layer { 303 cluster=true; 304 label="Rendering and Capture Control"; 305 style=dashed; 306 307 subgraph micp_layer { 308 cluster=true; 309 label="MICP"; 310 style=solid; 311 MICP_H [label="micp.h"]; 312 AICS_H [label="aics.h"]; 313 } 314 315 subgraph vcp_layer { 316 cluster=true; 317 label="VCP"; 318 style=solid; 319 VCP_H [label="vcp.h"]; 320 VOCS_H [label="vocs.h"]; 321 AICS_H [label="aics.h"]; 322 } 323 } 324 } 325 326 HAS_H -> CAP_H; 327 PBP_H -> CAP_H; 328 TMAP_H -> CAP_H; 329 GMAP_H -> CAP_H; 330 GMAP_PRESET_H -> CAP_H; 331 332 CAP_H -> MCS_H; 333 CAP_H -> MCC_H; 334 CAP_H -> MP_H; 335 CAP_H -> CCP_H; 336 CAP_H -> TBS_H; 337 CAP_H -> BAP_H; 338 CAP_H -> BAP_PRESET_H; 339 CAP_H -> PACS_H; 340 CAP_H -> MICP_H; 341 CAP_H -> VCP_H; 342 343 CSIP_H -> MCS_H; 344 CSIP_H -> MCC_H; 345 CSIP_H -> MP_H; 346 CSIP_H -> CCP_H; 347 CSIP_H -> TBS_H; 348 CSIP_H -> BAP_H; 349 CSIP_H -> BAP_PRESET_H; 350 CSIP_H -> PACS_H; 351 CSIP_H -> MICP_H; 352 CSIP_H -> VCP_H; 353 } 354 355Profile Dependencies 356==================== 357 358The LE Audio profiles depend on other profiles and services, as outlined in the following tables. 359In these tables 'Server' refers to acting in the GATT server role, and 'Client' refers to acting in the GATT client role for the specific 360service. 361If a profile role depends on another profile that depends on a service, then that dependency is implicitly also applied to that profile. 362For example, if the CAP Acceptor uses the BAP Unicast Server role, then the requirements on the ASCS Server and PACS Server also apply to the CAP Acceptor. 363 364The dependencies for Stream Control (BAP) are in the following table. 365 366.. table:: BAP dependencies 367 :widths: auto 368 :align: center 369 370 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 371 | | Unicast Server | Unicast Client | Broadcast Source | Broadcast Sink | Scan Delegator | Broadcast Assistant | 372 +====================+================+================+==================+================+================+=====================+ 373 | BAP Scan Delegator | | | | M | | | 374 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 375 | ASCS Client | | M | | | | | 376 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 377 | ASCS Server | M | | | | | | 378 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 379 | PACS Client | | M | | | | O | 380 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 381 | PACS Server | M | | | M | | | 382 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 383 | BASS Client | | | | | | M | 384 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 385 | BASS Server | | | | | M | | 386 +--------------------+----------------+----------------+------------------+----------------+----------------+---------------------+ 387 388Note: 389 390* As the table shows, the Broadcast Source role has no dependencies on other LE Audio profiles or services 391 392The dependencies for Content Control (MCP and CCP) are in the following tables. 393 394.. table:: MCP dependencies 395 :widths: auto 396 :align: center 397 398 +-------------+----------------------+----------------------+ 399 | | Media Control Server | Media Control Client | 400 +=============+======================+======================+ 401 | GMCS Server | M | | 402 +-------------+----------------------+----------------------+ 403 | GMCS Client | | M | 404 +-------------+----------------------+----------------------+ 405 | MCS Server | O | | 406 +-------------+----------------------+----------------------+ 407 | MCS Client | | O | 408 +-------------+----------------------+----------------------+ 409 | OTS Server | O | | 410 +-------------+----------------------+----------------------+ 411 | OTS Client | | O | 412 +-------------+----------------------+----------------------+ 413 414.. table:: CCP dependencies 415 :widths: auto 416 :align: center 417 418 +--------------+---------------------+---------------------+ 419 | | Call Control Server | Call Control Client | 420 +==============+=====================+=====================+ 421 | GTBS Server | M | | 422 +--------------+---------------------+---------------------+ 423 | GTBS Client | | M | 424 +--------------+---------------------+---------------------+ 425 | TBS Server | M | | 426 +--------------+---------------------+---------------------+ 427 | TBS Client | | M | 428 +--------------+---------------------+---------------------+ 429 430 431The dependencies for Rendering Control (MICP and VCP) are in the following tables. 432 433.. table:: MICP dependencies 434 :widths: auto 435 :align: center 436 437 +-------------+-----------------------+-------------------+ 438 | | Microphone Controller | Microphone Device | 439 +=============+=======================+===================+ 440 | MICS Server | M | | 441 +-------------+-----------------------+-------------------+ 442 | MICS Client | | M | 443 +-------------+-----------------------+-------------------+ 444 | AICS Server | O | | 445 +-------------+-----------------------+-------------------+ 446 | AICS Client | | O | 447 +-------------+-----------------------+-------------------+ 448 449.. table:: VCP dependencies 450 :widths: auto 451 :align: center 452 453 +-------------+------------------+-------------------+ 454 | | Volume Renderer | Volume Controller | 455 +=============+==================+===================+ 456 | VCS Server | M | | 457 +-------------+------------------+-------------------+ 458 | VCS Client | | M | 459 +-------------+------------------+-------------------+ 460 | VOCS Server | O | | 461 +-------------+------------------+-------------------+ 462 | VOCS Client | | O | 463 +-------------+------------------+-------------------+ 464 | AICS Server | O | | 465 +-------------+------------------+-------------------+ 466 | AICS Client | | O | 467 +-------------+------------------+-------------------+ 468 469The last element in GAF is Transition and Coordination Control (CAP and CSIP) with the dependencies from the following tables. 470 471.. table:: CAP dependencies 472 :widths: auto 473 :align: center 474 475 +----------------------------+----------+-----------+-----------+ 476 | | Acceptor | Initiator | Commander | 477 +============================+==========+===========+===========+ 478 | CAS Server | M | | C.8 | 479 +----------------------------+----------+-----------+-----------+ 480 | CAS Client | | M | M | 481 +----------------------------+----------+-----------+-----------+ 482 | BAP Unicast Client | | C.1 | | 483 +----------------------------+----------+-----------+-----------+ 484 | BAP Unicast Server | C.2 | | | 485 +----------------------------+----------+-----------+-----------+ 486 | BAP Broadcast Source | | C.1 | | 487 +----------------------------+----------+-----------+-----------+ 488 | BAP Broadcast Sink | C.2 | | | 489 +----------------------------+----------+-----------+-----------+ 490 | BAP Broadcast Assistant | | | C.4, C.6 | 491 +----------------------------+----------+-----------+-----------+ 492 | BAP Scan Delegator | C.3 | | C.6 | 493 +----------------------------+----------+-----------+-----------+ 494 | VCP Volume Controller | | | C.6 | 495 +----------------------------+----------+-----------+-----------+ 496 | VCP Volume Renderer | O | | | 497 +----------------------------+----------+-----------+-----------+ 498 | MICP Microphone Controller | | | C.6 | 499 +----------------------------+----------+-----------+-----------+ 500 | MICP Microphone Device | O | | | 501 +----------------------------+----------+-----------+-----------+ 502 | CCP Call Control Server | | O | | 503 +----------------------------+----------+-----------+-----------+ 504 | CCP Call Control Client | O | | C.6 | 505 +----------------------------+----------+-----------+-----------+ 506 | MCP Media Control Server | | O | | 507 +----------------------------+----------+-----------+-----------+ 508 | MCP Media Control Client | O | | C.6 | 509 +----------------------------+----------+-----------+-----------+ 510 | CSIP Set Coordinator | | C.5 | M | 511 +----------------------------+----------+-----------+-----------+ 512 | CSIP Set Member | C.7 | | | 513 +----------------------------+----------+-----------+-----------+ 514 515Notes: 516 517* C.1: Support at least one of BAP Unicast Client or BAP Broadcast Source 518* C.2: Support at least one of BAP Unicast Server or BAP Broadcast Sink 519* C.3: Mandatory if BAP Broadcast Sink 520* C.4: Mandatory if BAP Scan Delegator 521* C.5: Mandatory if BAP Unicast Client 522* C.6: Support at least one 523* C.7: Mandatory if part of a coordinated set 524* C.8: Mandatory if the Commander transmits CAP announcements 525 526 527.. table:: CSIP dependencies 528 :widths: auto 529 :align: center 530 531 +------------+------------+-----------------+ 532 | | Set Member | Set Coordinator | 533 +============+============+=================+ 534 | CSIS Server| M | | 535 +------------+------------+-----------------+ 536 | CSIS Client| | M | 537 +------------+------------+-----------------+ 538 539 540The dependencies of the higher level profiles (GMAP, HAP, PBP and TMAP) are listed in the following tables. 541 542.. table:: GMAP dependencies 543 :widths: auto 544 :align: center 545 546 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 547 | | Unicast Game Gateway | Unicast Game Terminal | Broadcast Game Sender | Broadcast Game Receiver | 548 +============================+======================+=======================+=======================+=========================+ 549 | GMAS Server | M | M | O | M | 550 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 551 | GMAS Client | M | O | O | O | 552 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 553 | CAP Initiator | M | | M | | 554 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 555 | CAP Acceptor | | M | | M | 556 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 557 | CAP Commander | M | | M | | 558 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 559 | BAP Broadcast Source | | | M | | 560 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 561 | BAP Broadcast Sink | | | | M | 562 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 563 | BAP Unicast Client | M | | | | 564 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 565 | BAP Unicast Server | | M | | | 566 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 567 | VCP Volume Controller | M | | | | 568 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 569 | VCP Volume Renderer | | C.1 | | M | 570 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 571 | MICP Microphone Controller | O | | | | 572 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 573 | MICP Microphone Device | | C.2 | | | 574 +----------------------------+----------------------+-----------------------+-----------------------+-------------------------+ 575 576Notes: 577 578* C.1 Mandatory if the UGT supports the UGT Sink feature 579* C.2 Optional if the UGT supports the UGT Source feature 580 581.. table:: HAP dependencies 582 :widths: auto 583 :align: center 584 585 +----------------------------+-------------+----------------------------+-------------------------------+ 586 | | Hearing Aid | Hearing Aid Unicast Client | Hearing Aid Remote Controller | 587 +============================+=============+============================+===============================+ 588 | HAS Client | | | M | 589 +----------------------------+-------------+----------------------------+-------------------------------+ 590 | HAS Server | M | | | 591 +----------------------------+-------------+----------------------------+-------------------------------+ 592 | CAP Initiator | | M | | 593 +----------------------------+-------------+----------------------------+-------------------------------+ 594 | CAP Acceptor | M | | | 595 +----------------------------+-------------+----------------------------+-------------------------------+ 596 | CAP Commander | | | M | 597 +----------------------------+-------------+----------------------------+-------------------------------+ 598 | BAP Unicast Client | | M | | 599 +----------------------------+-------------+----------------------------+-------------------------------+ 600 | BAP Unicast Server | M | | | 601 +----------------------------+-------------+----------------------------+-------------------------------+ 602 | VCP Volume Controller | | | M | 603 +----------------------------+-------------+----------------------------+-------------------------------+ 604 | VCP Volume Renderer | M | | | 605 +----------------------------+-------------+----------------------------+-------------------------------+ 606 | VOCS Server | C.1 | | | 607 +----------------------------+-------------+----------------------------+-------------------------------+ 608 | AICS Server | O | | | 609 +----------------------------+-------------+----------------------------+-------------------------------+ 610 | MICP Microphone Controller | | | O | 611 +----------------------------+-------------+----------------------------+-------------------------------+ 612 | MICP Microphone Device | C.2 | | | 613 +----------------------------+-------------+----------------------------+-------------------------------+ 614 | CCP Call Control Client | O | | | 615 +----------------------------+-------------+----------------------------+-------------------------------+ 616 | CCP Call Control Server | | O | | 617 +----------------------------+-------------+----------------------------+-------------------------------+ 618 | CSIP Set Coordinator | | M | M | 619 +----------------------------+-------------+----------------------------+-------------------------------+ 620 | CSIP Set Member | C.3 | | | 621 +----------------------------+-------------+----------------------------+-------------------------------+ 622 | BAS Server | C.4 | | | 623 +----------------------------+-------------+----------------------------+-------------------------------+ 624 | IAS Server | O | | | 625 +----------------------------+-------------+----------------------------+-------------------------------+ 626 627Notes: 628 629* C.1 Mandatory if the HA supports the Volume Baslance feature and is part of a Binaural Hearing Aid Set 630* C.2 Mandatory if the HA supports the BAP Audio Source Role 631* C.3 Mandatory if the HA is capable of being part of a Binaural Hearing Aid set 632* C.4 If equipped with batteries 633* C.5 If CCP Call Control Server is supported 634 635.. table:: PBP dependencies 636 :widths: auto 637 :align: center 638 639 +-------------------------+-------------------------+-----------------------+----------------------------+ 640 | | Public Broadcast Source | Public Broadcast sink | Public Broadcast Assistant | 641 +=========================+=========================+=======================+============================+ 642 | CAP Initiator | M | | | 643 +-------------------------+-------------------------+-----------------------+----------------------------+ 644 | CAP Acceptor | | M | | 645 +-------------------------+-------------------------+-----------------------+----------------------------+ 646 | CAP Commander | | | M | 647 +-------------------------+-------------------------+-----------------------+----------------------------+ 648 | BAP Broadcast Assistant | | | M | 649 +-------------------------+-------------------------+-----------------------+----------------------------+ 650 651.. table:: TMAP dependencies 652 :widths: auto 653 :align: center 654 655 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 656 | | Call Gateway | Call Terminal | Unicast Media Sender | Unicast Media Receiver | Broadcast Media Sender | Broadcast Media Receiver | 657 +===================================+==============+===============+======================+========================+========================+==========================+ 658 | TMAS Server | M | M | M | M | O | M | 659 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 660 | TMAS Client | O | O | O | O | O | O | 661 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 662 | CAP Initiator | M | | M | | M | | 663 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 664 | CAP Acceptor | | M | | M | | M | 665 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 666 | CAP Commander | M | O | M | O | O | O | 667 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 668 | BAP Broadcast Source | | | | | M | | 669 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 670 | BAP Broadcast Sink | | | | | | M | 671 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 672 | BAP Unicast Client | M | | M | | | | 673 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 674 | BAP Unicast Server | | M | | M | | | 675 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 676 | VCP Volume Controller | M | | M | | | | 677 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 678 | VCP Volume Renderer | | C.1 | | M | | M | 679 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 680 | MCP Media Control Server | | | M | | | | 681 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 682 | CCP Call Control Server | M | | | | | | 683 +-----------------------------------+--------------+---------------+----------------------+------------------------+------------------------+--------------------------+ 684 685Notes: 686 687* C.1 Mandatory to support if the BAP Unicast Server is acting as an Audio Sink 688 689Bluetooth Audio Stack Status 690============================ 691 692The following table shows the current status and support of the profiles in the 693Bluetooth Audio Stack. 694 695.. table:: Bluetooth Audio Profile status 696 :widths: auto 697 698 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 699 | Module | Role | Version | Added in Release | Status | Remaining | 700 +========+===============================+=========+==================+=======================+==================================================+ 701 | VCP | Volume Renderer | 1.0 | 2.6 | - Feature complete | - Sample Application | 702 | | | | | - Shell Module | | 703 | | | | | - BSIM test | | 704 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 705 | | Volume Controller | 1.0 | 2.6 | - Feature complete | - Sample Application | 706 | | | | | - Shell Module | | 707 | | | | | - BSIM test | | 708 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 709 | MICP | Microphone Device | 1.0 | 2.7 | - Feature complete | - Sample Application | 710 | | | | | - Shell Module | | 711 | | | | | - BSIM test | | 712 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 713 | | Microphone Controller | 1.0 | 2.7 | - Feature complete | - Sample Application | 714 | | | | | - Shell Module | | 715 | | | | | - BSIM test | | 716 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 717 | CSIP | Set Member | 1.0.1 | 3.0 | - Feature complete | - Sample Application | 718 | | | | | - Shell Module | | 719 | | | | | - BSIM test | | 720 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 721 | | Set Coordinator | 1.0.1 | 3.0 | - Feature complete | - Sample Application | 722 | | | | | - Shell Module | | 723 | | | | | - BSIM test | | 724 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 725 | CCP | Call Control Server | 1.0 | 3.0 | - Feature complete | - API refactor (in progress) | 726 | | | | | - Shell Module | - Sample Application (in progress) | 727 | | | | | - BSIM test | | 728 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 729 | | Call Control Client | 1.0 | 3.0 | - Feature complete | - API refactor (in progress) | 730 | | | | | - Shell Module | - Sample Application (in progress) | 731 | | | | | - BSIM test | | 732 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 733 | MCP | Media Control Server | 1.0 | 3.0 | - Feature complete | - API refactor | 734 | | | | | - Shell Module | - Support for multiple instances and connections | 735 | | | | | - BSIM test | - Sample Application | 736 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 737 | | Media Control Client | 1.0 | 3.0 | - Feature complete | - API refactor | 738 | | | | | - Shell Module | - Sample Application | 739 | | | | | - BSIM test | | 740 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 741 | BAP | Unicast Server | 1.0.1 | 3.0 | - Feature complete | | 742 | | | | | - Shell Module | | 743 | | | | | - BSIM test | | 744 | | | | | - Sample Application | | 745 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 746 | | Unicast Client | 1.0.1 | 3.0 | - Feature complete | | 747 | | | | | - Shell Module | | 748 | | | | | - BSIM test | | 749 | | | | | - Sample Application | | 750 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 751 | | Broadcast Source | 1.0.1 | 3.0 | - Feature complete | | 752 | | | | | - Shell Module | | 753 | | | | | - BSIM test | | 754 | | | | | - Sample Application | | 755 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 756 | | Broadcast Sink | 1.0.1 | 3.0 | - Feature complete | | 757 | | | | | - Shell Module | | 758 | | | | | - BSIM test | | 759 | | | | | - Sample Application | | 760 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 761 | | Scan Delegator | 1.0.1 | 3.3 | - Feature complete | | 762 | | | | | - Shell Module | | 763 | | | | | - BSIM test | | 764 | | | | | - Sample Application | | 765 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 766 | | Broadcast Assistant | 1.0.1 | 3.3 | - Feature complete | | 767 | | | | | - Shell Module | | 768 | | | | | - BSIM test | | 769 | | | | | - Sample Application | | 770 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 771 | CAP | Acceptor | 1.0 | 3.2 | - Feature complete | | 772 | | | | | - Shell Module | | 773 | | | | | - BSIM test | | 774 | | | | | - Sample Application | | 775 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 776 | | Initiator | 1.0 | 3.3 | - Feature complete | | 777 | | | | | - Shell Module | | 778 | | | | | - BSIM test | | 779 | | | | | - Sample Application | | 780 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 781 | | Commander | | | - WIP | - Feature complete | 782 | | | | | | - Shell Module | 783 | | | | | | - BSIM test | 784 | | | | | | - Sample Application | 785 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 786 | HAP | Hearing Aid | 1.0 | 3.1 | - Feature complete | | 787 | | | | | - Shell Module | | 788 | | | | | - BSIM test | | 789 | | | | | - Sample Application | | 790 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 791 | | Hearing Aid Unicast Client | 1.0 | 3.1 | - Feature complete | | 792 | | | | | - Shell Module | | 793 | | | | | - BSIM test | | 794 | | | | | - Sample Application | | 795 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 796 | | Hearing Aid Remote Controller | | | - WIP | - Feature complete | 797 | | | | | | - Shell Module | 798 | | | | | | - BSIM test | 799 | | | | | | - Sample Application | 800 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 801 | TMAP | Call Gateway | 1.0 | 3.4 | - Feature complete | | 802 | | | | | - Shell Module | | 803 | | | | | - BSIM test | | 804 | | | | | - Sample Application | | 805 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 806 | | Call Terminal | 1.0 | 3.4 | - Feature complete | | 807 | | | | | - Shell Module | | 808 | | | | | - BSIM test | | 809 | | | | | - Sample Application | | 810 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 811 | | Unicast Media Sender | 1.0 | 3.4 | - Feature complete | | 812 | | | | | - Shell Module | | 813 | | | | | - BSIM test | | 814 | | | | | - Sample Application | | 815 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 816 | | Unicast Media Receiver | 1.0 | 3.4 | - Feature complete | | 817 | | | | | - Shell Module | | 818 | | | | | - BSIM test | | 819 | | | | | - Sample Application | | 820 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 821 | | Broadcast Media Sender | 1.0 | 3.4 | - Feature complete | | 822 | | | | | - Shell Module | | 823 | | | | | - BSIM test | | 824 | | | | | - Sample Application | | 825 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 826 | | Broadcast Media Receiver | 1.0 | 3.4 | - Feature complete | | 827 | | | | | - Shell Module | | 828 | | | | | - BSIM test | | 829 | | | | | - Sample Application | | 830 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 831 | PBP | Public Broadcast Source | | 3.5 | - Feature complete | | 832 | | | | | - Shell Module | | 833 | | | | | - BSIM test | | 834 | | | | | - Sample Application | | 835 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 836 | | Public Broadcast Sink | | 3.5 | - Feature complete | | 837 | | | | | - Shell Module | | 838 | | | | | - BSIM test | | 839 | | | | | - Sample Application | | 840 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 841 | | Public Broadcast Assistant | | | | - Feature complete | 842 | | | | | | - Shell Module | 843 | | | | | | - BSIM test | 844 | | | | | | - Sample Application | 845 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 846 | GMAP | Unicast Game Gateway | | 3.5 | - Feature complete | - Sample Application | 847 | | | | | - Shell Module | | 848 | | | | | - BSIM test | | 849 | | | | | | | 850 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 851 | | Unicast Game Terminal | | 3.5 | - Feature complete | - Sample Application | 852 | | | | | - Shell Module | | 853 | | | | | - BSIM test | | 854 | | | | | | | 855 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 856 | | Broadcast Game Sender | | 3.5 | - Feature complete | - Sample Application | 857 | | | | | - Shell Module | | 858 | | | | | - BSIM test | | 859 | | | | | | | 860 | +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 861 | | Broadcast Game Receiver | | 3.5 | - Feature complete | - Sample Application | 862 | | | | | - Shell Module | | 863 | | | | | - BSIM test | | 864 | | | | | | | 865 +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+ 866 867Using the Bluetooth Audio Stack 868=============================== 869 870To use any of the profiles in the Bluetooth Audio Stack, including the top-level 871profiles outside of GAF, :kconfig:option:`CONFIG_BT_AUDIO` shall be enabled. 872This Kconfig option allows the enabling of the individual profiles inside of the 873Bluetooth Audio Stack. Each profile can generally be enabled on its own, but 874enabling higher-layer profiles (such as CAP, TMAP and HAP) will typically 875require enabling some of the lower layer profiles. 876 877It is, however, possible to create a device that uses e.g. only Stream Control 878(with just the BAP), without using any of the content control or 879rendering/capture control profiles, or vice versa. Using the higher layer 880profiles will however typically provide a better user experience and better 881interoperability with other devices. 882 883Common Audio Profile (CAP) 884-------------------------- 885 886The Common Audio Profile introduces restrictions and requirements on the lower layer profiles. 887The procedures in CAP works on one or more streams for one or more devices. Is it thus possible via 888CAP to do a single function call to setup multiple streams across multiple devices. 889 890The figure below shows a complete structure of the procedures in CAP and 891how they correspond to procedures from the other profiles. The circles with I, A and C show whether 892the procedure has active involvement or requirements from the CAP Initiator, CAP Accept and CAP 893Commander roles respectively. 894 895.. figure:: img/cap_proc.svg 896 :align: center 897 :alt: Common Audio Profile Procedures 898 899 Common Audio Profile Procedures 900 901The API reference for CAP can be found in :ref:`Common Audio Profile <bluetooth_cap>`. 902 903Stream Control (BAP) 904-------------------- 905 906Stream control is implemented by the Basic Audio Profile. This profile 907defines multiple roles: 908 909* Unicast Client 910* Unicast Server 911* Broadcast Source 912* Broadcast Sink 913* Scan Delegator 914* Broadcast Assistant 915 916Each role can be enabled individually, and it is possible to support more than 917one role. 918 919Notes about the stream control services 920~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 921 922There are 3 services primarily used by stream control using the Basic Audio Profile. 923 924Audio Stream Control Service (ASCS) 925^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 926 927ASCS is a service used exclusively for setting up unicast streams, 928and is located on the BAP Unicast Server device. 929The service exposes one or more endpoints that can either be a sink or source endpoint, 930from the perspective of the Unicast Server. 931That means a sink endpoint is always audio from the Unicast Client to the Unicast Server, 932and a source endpoint is always from the Unicast Server to the Unicast Client. 933 934Unlike most other GATT services, 935ASCS require that each characteristic in the service has unique data per client. 936This means that if a Unicast Server is connected to multiple Unicast Clients, 937the Unicast Clients are not able to see or control the endpoints configured by the other clients. 938For example if a person's smartphone is streaming audio to a headset, 939then the same person will not be able to see or control that stream from their smartwatch. 940 941Broadcast Audio Scan Service (BASS) 942^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 943 944BASS is a service that is exclusively used by the Scan Delegator and Broadcast Assistant. 945The main purpose of the service is to offload scanning from low power peripherals to e.g. phones 946and PCs. 947Unlike ASCS where the data is required to be unique per client, 948the data in BASS (called receive states) are (usually) shared among all connected clients. 949That means it is possible for a person to tell their headphones to synchronize to a 950Broadcast Source using their phone, 951and then later tell their headphones to stop synchronizing using their smartwatch. 952 953A Broadcast Assistant can be any device, 954and may only support this one role without any audio capabilities. 955This allows legacy devices that do not support periodic advertisements or isochronous channels to 956still provide an interface and scan offloading for peripherals. 957The Bluetooth SIG have provided a guide on how to develop such legacy Broadcast Assistants that can 958be found at 959https://www.bluetooth.com/bluetooth-resources/developing-auracast-receivers-with-an-assistant-application-for-legacy-smartphones/. 960An important note about this guide is that many operating systems (especially on phones), 961do not allow generic usage of the BASS UUID, 962effectively making it impossible to implement your own Broadcast Assistant, 963because you cannot access the BASS. 964 965Published Audio Capabilities Service (PACS) 966^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 967 968PACS is used to expose a device's audio capabilities in Published Audio Capabilities (PAC) records. 969PACS is used by nearly all roles, 970where the Unicast Client and Broadcast Assistant will act as PACS clients, 971and Unicast Server and Broadcast Sink will act as PACS servers. 972These records contain information about the codec, and which values are supported by each codec. 973The values for the LC3 codec are defined by the Bluetooth Assigned numbers 974(https://www.bluetooth.com/specifications/assigned-numbers/), and the values for other codecs such 975as SBC are left undefined/implementation specific for BAP. 976 977PACS also usually share the same data between each connected client, 978but by using functions such as :c:func:`bt_pacs_conn_set_available_contexts_for_conn`, 979it is possible to set specific values for specific clients. 980 981The API reference for stream control can be found in 982:ref:`Bluetooth Audio <bluetooth_audio>`. 983 984 985Rendering and Capture Control 986----------------------------- 987 988Rendering and capture control is implemented by the Volume Control Profile 989(VCP) and Microphone Control Profile (MICP). 990 991The VCP implementation supports the following roles 992 993* Volume Control Service (VCS) Server 994* Volume Control Service (VCS) Client 995 996The MICP implementation supports the following roles 997 998* Microphone Control Profile (MICP) Microphone Device (server) 999* Microphone Control Profile (MICP) Microphone Controller (client) 1000 1001The API reference for volume control can be found in 1002:ref:`Bluetooth Volume Control <bluetooth_volume>`. 1003 1004The API reference for Microphone Control can be found in 1005:ref:`Bluetooth Microphone Control <bluetooth_microphone>`. 1006 1007 1008Content Control 1009--------------- 1010 1011Content control is implemented by the Call Control Profile (CCP) and 1012Media Control Profile (MCP). 1013 1014The CCP implementation is not yet implemented in Zephyr. 1015 1016The MCP implementation supports the following roles 1017 1018* Media Control Service (MCS) Server via the Media Proxy module 1019* Media Control Client (MCC) 1020 1021The API reference for media control can be found in 1022:ref:`Bluetooth Media Control <bluetooth_media>`. 1023 1024Generic TBS and Generic MCS 1025~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1026 1027Both the Telephone Bearer Service (TBS) used by CCP and the Media Control Service (MCS) used by MCP 1028have the concept of generic instances of the services called Generic TBS (GTBS) and 1029Generic MCS (GMCS). 1030 1031While these share a common name prefix, the behavior of these two may be significantly different. 1032 1033Generic TBS 1034^^^^^^^^^^^ 1035 1036The TBS spec defines GTBS as 1037 1038 GTBS provides a single point of access and exposes a representation of its internal telephone 1039 bearers into a single telephone bearer. 1040 This service provides telephone status and control of the device as a single unit with a 1041 single set of characteristics. 1042 It is left up to the implementation to determine what telephone bearer a characteristic of 1043 GTBS represents at any time. 1044 There is no specified manner of representing a characteristic from each individual TBS that 1045 resides on the device to the same characteristic of the GTBS. 1046 1047 For example, if there is more than one TBS on a device and each has a unique telephone bearer 1048 name (e.g., Name1 and Name2), 1049 the way the GTBS represents the telephone bearer name is left up to the implementation. 1050 GTBS is suited for clients that do not need to access or control all the 1051 information available on specific telephone bearers. 1052 1053This means that a GTBS instance represents one or more telephone bearers. 1054A telephone bearer could be any application on a device that can handle (telephone) calls, 1055such as the default Call application on a smartphone, 1056but also other applications such as Signal, Discord, Teams, Slack, etc. 1057 1058GTBS may be standalone (i.e.the device only has a GTBS instance without any TBS instances), 1059and the behavior of the GTBS is mostly left up to the implementation. 1060In Zephyr the implementation of GBTS is that it contains some generic information, 1061such as the provider name which is defined to simply be "Generic TBS", 1062but the majority of the information in the GTBS instance in Zephyr has been implemented to be a 1063union of the data of the other bearers. 1064For example if you have a bearer for regular phone calls and 1065Teams and have an active call in both bearers, 1066then each of those bearers will report a single call, 1067but the GTBS instance will report 2 calls, 1068making it possible for a simple Call Control Client to control all calls from a single bearer. 1069Similarly the supported URIs for each bearer are also made into a union in GTBS, and when placing 1070a call using the GTBS the server will pick the most suited bearer depending on the URI. 1071For example calls with URI ``tel`` would go to the regular phone application, 1072and calls with the URI ``skype`` would go to the Teams application. 1073 1074In conclusion the GTBS implementation in Zephyr is a union of the non-generic telephone bearers. 1075 1076Generic MCS 1077^^^^^^^^^^^ 1078 1079The MCS spec defines GMCS as 1080 1081 The GMCS provides status and control of media playback for the device as a single unit. 1082 An MCS instance describes and controls the media playback for a 1083 specific media player within the device. 1084 A device implements MCS instances to allow clients to access the 1085 separate internal media player entities. 1086 1087and where the behavior of GMCS is defined as 1088 1089 ... the behavior of MCS and GMCS is identical, 1090 and all the characteristics and the characteristics' behaviors are the same. 1091 The term “MCS” is used throughout the document. 1092 Unless otherwise specifically stated in this specification, 1093 the same meaning applies to GMCS as well. 1094 1095This means that a GMCS instance works the same way as an MCS instance, 1096and it follows that GMCS 1097 1098 controls the media playback for a specific media player within the device 1099 1100A media player on a device could be anything that plays media, 1101such as a Spotify or Youtube application on a smartphone. 1102Thus if a device has multiple MCS instances, 1103then each of these control media for that specific application, 1104but the GMCS also controls media playback for a specific media player. 1105GMCS can thus be considered a pointer to a specific MCS instance, 1106and control either e.g. Spotify or Youtube, but not both. 1107 1108The MCS spec does however provide an example of GMCS where a device can 1109 1110 Implement a GMCS that provides status and control of media playback for the device as a whole. 1111 1112Which may indicate that an implementation may use GMCS to represent all media players with GMCS and 1113not a specific media player as stated above. In the case where a device does not have any MCS 1114instances and only GMCS, then GMCS will point to a generic instance. 1115 1116The Zephyr implementation of MCS and GMCS is incomplete, 1117and currently only supports instantiating a single instance that can either be an MCS or GMCS. 1118This means that the implementation is neither complete nor spec-compliant. 1119 1120Difference between GTBS and GMCS 1121^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1122 1123The definitions and implementations of GTBS and GMCS as stated above are notably different. 1124GTBS works as a union between the other TBS instances (if any), 1125and GMCS works as a pointer to a specific MCS instance (if any). 1126This effectively means that a simple Call Control Client can control all calls just using GTBS, 1127but a Media Control Client may only be able to control a single player using GMCS. 1128 1129Coordinated Sets 1130---------------- 1131 1132Coordinated Sets is implemented by the Coordinated Sets Identification Profile 1133(CSIP). 1134 1135The CSIP implementation supports the following roles 1136 1137* Coordinated Set Identification Service (CSIP) Set Member 1138* Coordinated Set Identification Service (CSIP) Set Coordinator 1139 1140The API reference for media control can be found in 1141:ref:`Bluetooth Coordinated Sets <bluetooth_coordinated_sets>`. 1142 1143Specification correctness and data location 1144------------------------------------------- 1145 1146The implementations are designed to ensure specification compliance as much as possible. 1147When a specification introduces a requirement with e.g. a **shall** then the implementation should 1148attempt to ensure that this requirement is always followed. 1149Depending on the context of this, 1150the implementation ensures this by rejecting invalid parameters from the application, 1151or from the remote devices. 1152 1153Some requirements from the specifications are not or can not be handled by the stack itself for 1154various reasons. 1155One reason when the stack cannot handle a requirement is if the data related to the requirement is 1156exclusively controlled by the application. 1157An example of this is the advertising data, 1158where multiple service have requirements for what to advertise and when, 1159but where both the advertising state and data is exclusively controlled by the application. 1160 1161Oppositely there are also requirements from the specification, 1162where the data related to the requirement is exclusively controlled by the stack. 1163An example of this is the Volume Control Service (VCS) state, 1164where the specifications mandata that the VCP Volume Renderer (VCS server) modify the values 1165without a choice, 1166e.g. when setting the absolutely volume. 1167In cases like this the application is only notified about the change with a callback, 1168but cannot reject the request (the stack will reject any invalid requests). 1169 1170Generally when the data is simple (like the VCS state which only take up a few bytes), 1171the data is kept in and controlled by the stack, 1172as this can ensure that the requirements can be handled by the stack, 1173making it easier to use a profile role correctly. 1174When the data is more complex (e.g. the PAC records), 1175the data may be kept by the application and the stack only contains a reference to it. 1176When the data is very application specific (e.g. advertising data), 1177the data is kept in and controlled by the application. 1178 1179As a rule of thumb, the return types of the callbacks for each profile implementation indicate 1180whether the data is controlled by the stack or the application. 1181For example all the callbacks for the VCP Volume Renderer have the return type of ``void``, 1182but the return type of the BAP Unicast Server callbacks are ``int``, 1183indicating that the application not only controls a lot of the Unicast Server data, 1184but can also reject the requests. 1185The choice of what the return type of the callbacks often depend on the specifications, 1186and how much control the role has in a given context. 1187 1188Things worth knowing or considering when using LE Audio 1189======================================================= 1190 1191This section describes a few tings to consider when contributing to or using LE Audio in Zephyr. 1192The things described by this section are not unique to Zephyr as they are defined by the 1193specifications. 1194 1195Security requirements 1196--------------------- 1197 1198All LE Audio services require Security Level 2 but where the key must be 128-bit and derived via an 1199OOB method or via LE Secure connections. 1200There is no Core-spec defined way of reporting this in GATT, 1201as ATT does not have a specific error code for missing OOB method or LE Secure Connections 1202(although there is a way to report wrong key size). 1203 1204In Zephyr we do not force the device to always use these, as a device that uses LE Audio may also 1205use other profiles and services that do not require such security. 1206We guard all access to services using a custom security check implemented in 1207:zephyr_file:`subsys/bluetooth/audio/audio.c`, where all LE Audio services must use the 1208internal :c:macro:`BT_AUDIO_CHRC` macro for proper security verification. 1209 1210Access to the LTK for encrypted SIRKs in CSIS 1211--------------------------------------------- 1212 1213The Coordinated Set Identification Service (CSIS) may encrypt the SIRK (set identity resolving key). 1214The process of encrypting the SIRK requires the LTK as the encryption key, 1215which is typically not exposed to higher layer implementations such as CSIS. 1216This does not have any effect on the security though. 1217 1218MTU requirements 1219---------------- 1220 1221The Basic Audio Profile (BAP) has a requirement that both sides shall support a minimum ATT_MTU of 1222at least 64 on the unenhanced ATT bearer or at least one enhanced ATT bearer. 1223The requirement comes from the preferred (or sometimes mandatory) use of GATT Write Without 1224Response, and where support for Write Long Characteristic Value is optional in most cases. 1225 1226If a ASCS device supports values larger than the minimum ATT_MTU of 64 octets, then it shall support 1227Read long Characteristic Value by setting :kconfig:option:`CONFIG_BT_ATT_PREPARE_COUNT` to a 1228non-zero value. 1229 1230LE Audio resources 1231################## 1232 1233This section contains some links and reference to resources that are useful for either contributors 1234to the LE Audio Stack in Zephyr, LE Audio application developers or both. 1235 1236The LE audio channel on Discord 1237******************************* 1238 1239Zephyr has a specific Discord channel for LE Audio development, which is open to all. 1240Find it here at https://discordapp.com/channels/720317445772017664/1207326649591271434 or simply 1241search for "bt-audio" from within Discord. 1242Since the ``#bt-audio`` channel is open for all, 1243we cannot discuss any specifications that are in development in that channel. 1244For discussions that require a Bluetooth SIG membership we refer to the ``#bt-sig`` 1245Discord channel found at https://discordapp.com/channels/720317445772017664/869172014018097162. 1246 1247Zephyr weekly meetings 1248********************** 1249 1250Anyone who is a Bluetooth SIG member and a Zephyr member can join the weekly meetings where we 1251discuss and plan the development of LE Audio in Zephyr. You can find the time of the meetings by 1252joining the Bluetooth-sig group at https://lists.zephyrproject.org/g/Bluetooth-sig. 1253 1254Github project 1255************** 1256 1257LE Audio in Zephyr has its own Github project available at 1258https://github.com/orgs/zephyrproject-rtos/projects/26. 1259The project is mostly automated, 1260and the LE Audio contributors almost only rely on the automated workflows 1261to present the state of development. 1262Anyone is able to pick any of the open issues and work on it. 1263If you cannot assign the issue to yourself, 1264please leave a comment in the issue itself or ping the Discord channel for help. 1265 1266Bluetooth SIG errata for LE Audio 1267********************************* 1268 1269There are many specifications for LE Audio, 1270and several of them are still being updated and developed. 1271To get an overview of the errata for the LE Audio specifications you can visit 1272 1273* Generic Audio (GA) errata https://bluetooth.atlassian.net/wiki/spaces/GA/pages/1634402349/GAWG+Errata+Lists 1274* Hearing Aid (HA) errata https://bluetooth.atlassian.net/wiki/spaces/HA/pages/1634140216/HA+WG+Errata+List 1275* Audio, Telephony and Automotive (ATA) errata https://bluetooth.atlassian.net/wiki/spaces/ATA/pages/1668481034/ATA+Errata+Lists 1276 1277Access to errata requires a Bluetooth SIG membership. 1278 1279Bluetooth SIG working groups for LE Audio 1280***************************************** 1281 1282There are 3 working groups in the Bluetooth SIG related to LE Audio: 1283 1284* Generic Audio (GA) https://www.bluetooth.org/groups/group.aspx?gId=665 1285* Hearing Aid (HA) https://www.bluetooth.org/groups/group.aspx?gId=605 1286* Audio, Telephony, and Automotive (ATA) https://www.bluetooth.org/groups/group.aspx?gId=659 1287 1288By joining these groups you will also get emails from their respective mailing lists, 1289where multiple questions and discussions are handled. 1290The working groups also have scheduled weekly meetings, 1291where issues and the development of the specifications are handled. 1292 1293Access to the Bluetooth SIG working groups requires a Bluetooth SIG membership. 1294 1295The LE Audio Book 1296***************** 1297 1298There is a free ebook on LE Audio at https://www.bluetooth.com/bluetooth-resources/le-audio-book/. 1299The book was released in January 2022, 1300and thus before some of the specifications were finalized, 1301but also before some of the released updates to the specifications. 1302Nevertheless the book still provides a good explanation for many of the concepts and ideas, 1303but please refer to the individual specifications for technical information. 1304 1305Bluetooth SIG informational papers, reports and guides 1306****************************************************** 1307 1308The Bluetooth SIG occasionally release new informational papers, report and guides. 1309These can be found at https://www.bluetooth.com/bluetooth-resources/?tags=le-audio&keyword. 1310Here you will also find the aforementioned LE Audio book, among many other good resources. 1311
