1Zephyr HCI Extensions 2********************* 3 4 5Introduction 6============ 7 8This document describes a set of vendor specific HCI commands and events for 9Zephyr based Bluetooth Classic and Low Energy controllers. 10 11 12Zephyr Vendor Configuration Parameters 13====================================== 14 15 16Zephyr Vendor Supported Commands 17================================ 18 19The Supported Commands configuration parameter lists which vendor commands the 20local Controller supports. It is implied that if a command is listed as 21supported, the feature underlying that command is also supported. 22 23The Supported Commands is a 64 octet bit field. If a bit is set to 1, then this 24command is supported. 25 26 +-------+------+--------------------------------------------+ 27 | Octet | Bit | Command Supported | 28 +-------+------+--------------------------------------------+ 29 | 0 | 0 | Read Version Information | 30 | | 1 | Read Supported Commands | 31 | | 2 | Read Supported Features | 32 | | 3 | Set Event Mask | 33 | | 4 | Reset | 34 | | 5 | Write BD_ADDR | 35 | | 6 | Set Trace Enable | 36 | | 7 | Read Build Information | 37 +-------+------+--------------------------------------------+ 38 | 1 | 0 | Read Static Addresses | 39 | | 1 | Read Key Hierarchy Roots | 40 | | 2 | Read Chip Temperature | 41 | | 3 | Read Host Stack Commands | 42 | | 4 | Set Scan Request Reports | 43 | | 5 | Write Tx Power Level (per Role/Connection) | 44 | | 6 | Read Tx Power Level (per Role/Connection) | 45 | | 7 | Read USB Supported Transport Modes | 46 +-------+------+--------------------------------------------+ 47 | 2 | 0 | Set USB Transport Mode | 48 +-------+------+--------------------------------------------+ 49 50Only Read_Version_Information and Read_Supported_Commands commands are 51mandatory. 52 53 54Zephyr Vendor Supported Features 55================================ 56 57The Supported Features configuration parameter lists vendor specific features 58that either extend commands or don't have a vendor command. Most features are 59indicated by the support its respective vendor command. The Supported Features 60are represented as an 8 octet bit mask. For each feature a single bit is 61specified which shall be set to 1 if the feature is supported and set to 0 62otherwise. 63 64 +-------+------+--------------------------------------------+ 65 | Octet | Bit | Feature Supported | 66 +-------+------+--------------------------------------------+ 67 | 0 | 0 | Vendor Diagnostic Channel | 68 | | 1 | Reserved | 69 | | 2 | Reserved | 70 | | 3 | Reserved | 71 | | 4 | Reserved | 72 | | 5 | Reserved | 73 | | 6 | Reserved | 74 | | 7 | Reserved | 75 +-------+------+--------------------------------------------+ 76 77 78Zephyr Vendor Event Mask 79======================== 80 81The Event Mask configuration parameter lists the events that are indicated by 82the controller. By default no vendor events are reported. 83 84 +-------+------+--------------------------------------------+ 85 | Octet | Bit | Event | 86 +-------+------+--------------------------------------------+ 87 | 0 | 0 | Reserved | 88 | | 1 | Fatal Error | 89 | | 2 | Trace Information Event | 90 | | 3 | Scan Request Received Event | 91 | | 4 | Connectionless IQ Report Event | 92 | | 5 | Connection IQ Report Event | 93 | | 6 | Reserved | 94 | | 7 | Reserved | 95 +-------+------+--------------------------------------------+ 96 97The support for Fatal_Error event is mandatory. The default event mask after 98bootup and vendor specific Reset command includes the Fatal_Error event. 99 100 101Zephyr Hardware Platforms 102========================= 103 104Hardware platforms are assigned numbers to allow identification of the hardware 105manufacturer. 106 107 Hardware_Platform: Size: 2 Octets 108 +--------------------+--------------------------------------+ 109 | Value | Parameter Description | 110 +--------------------+--------------------------------------+ 111 | 0x0001 | Intel Corporation | 112 | 0x0002 | Nordic Semiconductor | 113 | 0x0003 | NXP Semiconductors | 114 | All other values | Reserved for future use | 115 +--------------------+--------------------------------------+ 116 117The Hardware_Platform name is independent from the Manufacture Name provided 118by HCI version information. This information identifies the actual chip while 119the standard HCI version information identifies the unique implementation of 120a Bluetooth Controller. 121 122 123Zephyr Hardware Variants 124======================== 125 126Hardware variants are platform specific. They are specified to allow detailed 127identification of the hardware running Zephyr. 128 129 Hardware_Variant (Nordic): Size: 2 Octets 130 +--------------------+--------------------------------------+ 131 | Value | Parameter Description | 132 +--------------------+--------------------------------------+ 133 | 0x0001 | nRF51x | 134 | 0x0002 | nRF52x | 135 | All other values | Reserved for future use | 136 +--------------------+--------------------------------------+ 137 138The Hardware_Variant value assignment depends on the Hardware_Platform value. 139Each hardware platform has its own variant namespace. 140 141 142Zephyr Trace Information Format 143=============================== 144 145The trace information used the Trace Information event and in the Diagnostic 146Channel are following the same packet format. 147 1480 8 16 24 149+--------------+--------------+--------------+--------------+ 150| Type | Connection_Handle | Parameters 151+--------------+--------------+--------------+--------------+ 152 153 154Zephyr Vendor Commands 155====================== 156 157Vendor specific HCI commands use the OGF 0x3F. All defined OCF are listed 158below. Undefined OCF are reserved for future use. 159 160 161Zephyr Read Version Information Command 162======================================= 163 164This command reads the values for the vendor version information for the local 165Controller. 166 167+--------------------------+-------+--------------------+--------------------+ 168| Command | OCF | Command | Return | 169| | | Parameters | Parameters | 170+--------------------------+-------+--------------------+--------------------+ 171| Read_Version_Information | 0x001 | | Status, | 172| | | | Hardware_Platform, | 173| | | | Hardware_Variant, | 174| | | | Firmware_Variant, | 175| | | | Firmware_Version, | 176| | | | Firmware_Revision, | 177| | | | Firmware_Build | 178+--------------------------+-------+--------------------+--------------------+ 179 180The Hardware_Platform information defines the hardware manufacturer 181information. The Hardware_Variant is manufacturer specific and defines the 182hardware platform from that manufacturer. 183 184The Firmware_Variant defines the type of firmware. It is possible to provide 185HCI firmware with limited functionality for example for bootloader operation. 186The Firmware_Version and Firmware_Revision define version information of the 187Firmware_Variant that is currently active. The Firmware_Build defines an 188additional counter for incremental builds. 189 190 Status: Size: 1 Octet 191 +--------------------+--------------------------------------+ 192 | Value | Parameter Description | 193 +--------------------+--------------------------------------+ 194 | 0x00 | Command succeeded | 195 | 0x01-0xFF | Command failed | 196 +--------------------+--------------------------------------+ 197 198 Hardware_Platform: Size: 2 Octets 199 +--------------------+--------------------------------------+ 200 | Value | Parameter Description | 201 +--------------------+--------------------------------------+ 202 | 0xXXXX | Assigned hardware manufacturer | 203 +--------------------+--------------------------------------+ 204 205 Hardware_Variant: Size: 2 Octets 206 +--------------------+--------------------------------------+ 207 | Value | Parameter Description | 208 +--------------------+--------------------------------------+ 209 | 0xXXXX | Assigned platform specific value | 210 +--------------------+--------------------------------------+ 211 212 Firmware_Variant: Size: 1 Octet 213 +--------------------+--------------------------------------+ 214 | Value | Parameter Description | 215 +--------------------+--------------------------------------+ 216 | 0x00 | Standard Bluetooth controller | 217 | 0x01 | Vendor specific controller | 218 | 0x02 | Firmware loader | 219 | 0x03 | Rescue image | 220 | All other values | Reserved for future use | 221 +--------------------+--------------------------------------+ 222 223 Firmware_Version: Size: 1 Octet 224 +--------------------+--------------------------------------+ 225 | Value | Parameter Description | 226 +--------------------+--------------------------------------+ 227 | 0xXX | Implementation specific | 228 +--------------------+--------------------------------------+ 229 230 Firmware_Revision: Size: 2 Octets 231 +--------------------+--------------------------------------+ 232 | Value | Parameter Description | 233 +--------------------+--------------------------------------+ 234 | 0xXXXX | Implementation specific | 235 +--------------------+--------------------------------------+ 236 237 Firmware_Build: Size: 4 Octets 238 +--------------------+--------------------------------------+ 239 | Value | Parameter Description | 240 +--------------------+--------------------------------------+ 241 | 0xXXXXXXXX | Implementation specific | 242 +--------------------+--------------------------------------+ 243 244When the Read_Version_Information command has completed, a Command Complete 245event shall be generated. 246 247 248Zephyr Read Supported Commands Command 249====================================== 250 251This command reads the list of vendor commands supported for the local 252Controller. 253 254+--------------------------+-------+--------------------+--------------------+ 255| Command | OCF | Command | Return | 256| | | Parameters | Parameters | 257+--------------------------+-------+--------------------+--------------------+ 258| Read_Supported_Commands | 0x002 | | Status, | 259| | | | Supported_Commands | 260+--------------------------+-------+--------------------+--------------------+ 261 262This command shall return the Supported_Commands configuration parameter. It is 263implied that if a command is listed as supported, the feature underlying that 264command is also supported. 265 266 Status: Size: 1 Octet 267 +--------------------+--------------------------------------+ 268 | Value | Parameter Description | 269 +--------------------+--------------------------------------+ 270 | 0x00 | Command succeeded | 271 | 0x01-0xFF | Command failed | 272 +--------------------+--------------------------------------+ 273 274 Supported_Commands: Size: 64 Octets 275 +--------------------+--------------------------------------+ 276 | Value | Parameter Description | 277 +--------------------+--------------------------------------+ 278 | | Bit mask for each vendor command | 279 | | | 280 | | If a bit is 1, the Controller | 281 | | supports the corresponding command | 282 | | and the features required for the | 283 | | command, unsupported or undefined | 284 | | commands shall be set to 0 | 285 +--------------------+--------------------------------------+ 286 287When the Read_Supported_Commands command has completed, a Command Complete 288event shall be generated. 289 290 291Zephyr Read Supported Features Command 292====================================== 293 294This command reads the list of vendor features supported by the local Controller. 295 296+--------------------------+-------+--------------------+--------------------+ 297| Command | OCF | Command | Return | 298| | | Parameters | Parameters | 299+--------------------------+-------+--------------------+--------------------+ 300| Read_Supported_Features | 0x003 | | Status, | 301| | | | Supported_Features | 302+--------------------------+-------+--------------------+--------------------+ 303 304This command shall return the Supported_Features configuration parameter. The 305features list is only used for features not covered by supported commands. 306 307 Status: Size: 1 Octet 308 +--------------------+--------------------------------------+ 309 | Value | Parameter Description | 310 +--------------------+--------------------------------------+ 311 | 0x00 | Command succeeded | 312 | 0x01-0xFF | Command failed | 313 +--------------------+--------------------------------------+ 314 315 Supported_Features: Size: 8 Octets 316 +--------------------+--------------------------------------+ 317 | Value | Parameter Description | 318 +--------------------+--------------------------------------+ 319 | 0xXXXXXXXXXXXXXXXX | Bit Mask List of vendor features | 320 +--------------------+--------------------------------------+ 321 322When the Read_Supported_Features command has completed, a Command Complete 323event shall be generated. 324 325 326Zephyr Set Event Mask Command 327============================= 328 329This command is used to control which vendor events are generated by the HCI 330for the Host. 331 332+--------------------------+-------+--------------------+--------------------+ 333| Command | OCF | Command | Return | 334| | | Parameters | Parameters | 335+--------------------------+-------+--------------------+--------------------+ 336| Set_Event_Mask | 0x004 | Event_Mask | Status | 337+--------------------------+-------+--------------------+--------------------+ 338 339If the bit in the Event_Mask is set to a one, then the event associated with 340that bit will be enabled. The Host has to deal with each event that is 341generated by a Controller. The event mask allows the Host to control which 342events will interrupt it. 343 344The vendor specific Reset command shall reset this event mask back to its 345default value, but the standard HCI Reset command shall not reset this command 346back to its default value. 347 348 Event_Mask: Size: 8 Octets 349 +--------------------+--------------------------------------+ 350 | Value | Parameter Description | 351 +--------------------+--------------------------------------+ 352 | 0x0000000000000003 | Default enabled vendor events | 353 | 0xXXXXXXXXXXXXXXXX | Bit Mask List of vendor events | 354 +--------------------+--------------------------------------+ 355 356 Status: Size: 1 Octet 357 +--------------------+--------------------------------------+ 358 | Value | Parameter Description | 359 +--------------------+--------------------------------------+ 360 | 0x00 | Command succeeded | 361 | 0x01-0xFF | Command failed | 362 +--------------------+--------------------------------------+ 363 364When the Set_Event_Mask command has completed, a Command Complete event shall 365be generated. 366 367 368Zephyr Reset Command 369==================== 370 371This command resets the vendor portion of the local Controller. 372 373+--------------------------+-------+--------------------+--------------------+ 374| Command | OCF | Command | Return | 375| | | Parameters | Parameters | 376+--------------------------+-------+--------------------+--------------------+ 377| Reset | 0x005 | Reset_Type | Status | 378+--------------------------+-------+--------------------+--------------------+ 379 380The Host shall not send additional HCI commands before the Command Complete 381event related to the Reset command has been received. 382 383The Soft reset and Hard reset both include all actions taken by the standard 384HCI Reset command. While the standard HCI Reset command does not reset any 385vendor specific settings, this command will reset everything back to defaults. 386 387The Hard reset will cause a full reboot of the hardware. 388 389 Reset_Type: Size: 1 Octet 390 +--------------------+--------------------------------------+ 391 | Value | Parameter Description | 392 +--------------------+--------------------------------------+ 393 | 0x00 | Soft reset | 394 | 0x01 | Hard reset | 395 | All other values | Reserved for future use | 396 +--------------------+--------------------------------------+ 397 398 Status: Size: 1 Octet 399 +--------------------+--------------------------------------+ 400 | Value | Parameter Description | 401 +--------------------+--------------------------------------+ 402 | 0x00 | Command succeeded | 403 | 0x01-0xFF | Command failed | 404 +--------------------+--------------------------------------+ 405 406When the Reset command has completed, a Command Complete event shall be 407generated. 408 409 410Zephyr Write BD_ADDR Command 411============================ 412 413This command writes the BD_ADDR (Bluetooth public device address) value 414to the volatile memory. It is kept over Reset and can be read out by 415Read_BD_ADDR command. 416 417+--------------------------+-------+--------------------+--------------------+ 418| Command | OCF | Command | Return | 419| | | Parameters | Parameters | 420+--------------------------+-------+--------------------+--------------------+ 421| Write_BD_ADDR | 0x006 | BD_ADDR | Status | 422+--------------------------+-------+--------------------+--------------------+ 423 424To activate this address the standard HCI Reset command is required to be 425executed. Until then the current BD_ADDR is still active and reported by 426Read_BD_ADDR. The vendor specific Reset command will reset the BD_ADDR to its 427non-volatile default if available. Otherwise the BD_ADDR shall be reset to the 428invalid / non-existent 00:00:00:00:00:00 address value. 429 430 BD_ADDR: Size: 6 Octets 431 +--------------------+--------------------------------------+ 432 | Value | Parameter Description | 433 +--------------------+--------------------------------------+ 434 | 0xXXXXXXXXXXXX | BD_ADDR of the Device | 435 +--------------------+--------------------------------------+ 436 437 Status: Size: 1 Octet 438 +--------------------+--------------------------------------+ 439 | Value | Parameter Description | 440 +--------------------+--------------------------------------+ 441 | 0x00 | Command succeeded | 442 | 0x01-0xFF | Command failed | 443 +--------------------+--------------------------------------+ 444 445When the Write_BD_ADDR command has completed, a Command Complete event shall 446be generated. 447 448 449Zephyr Set Trace Enable Command 450=============================== 451 452This command is used to enable or disable the tracing functionality. 453 454+--------------------------+-------+--------------------+--------------------+ 455| Command | OCF | Command | Return | 456| | | Parameters | Parameters | 457+--------------------------+-------+--------------------+--------------------+ 458| Set_Trace_Enable | 0x007 | Enable, | Status | 459| | | Type | | 460+--------------------------+-------+--------------------+--------------------+ 461 462When enabled the Controller will send link layer and link manager tracing 463information to the Host. 464 465When Enable is set to 0x00 then Type shall be set to 0x00 as well. The 466diagnostic channel type shall only supported when the feature bit is also set. 467 468The support for trace information reporting via HCI events is mandatory to 469support when the Set_Trace_Enable command is supported. 470 471 Enable: Size: 1 Octet 472 +--------------------+--------------------------------------+ 473 | Value | Parameter Description | 474 +--------------------+--------------------------------------+ 475 | 0x00 | Tracing disabled | 476 | 0x01 | Tracing enabled | 477 | All other values | Reserved for future use | 478 +--------------------+--------------------------------------+ 479 480 Type: Size: 1 Octet 481 +--------------------+--------------------------------------+ 482 | Value | Parameter Description | 483 +--------------------+--------------------------------------+ 484 | 0x00 | Use HCI events | 485 | 0x01 | Use Vendor Diagnostic Channel | 486 | All other values | Reserved for future use | 487 +--------------------+--------------------------------------+ 488 489 Status: Size: 1 Octet 490 +--------------------+--------------------------------------+ 491 | Value | Parameter Description | 492 +--------------------+--------------------------------------+ 493 | 0x00 | Command succeeded | 494 | 0x01-0xFF | Command failed | 495 +--------------------+--------------------------------------+ 496 497When the Set_Trace_Enable command has completed, a Command Complete event shall 498be generated. 499 500 501Zephyr Read Build Information Command 502===================================== 503 504This commands reads the controller firmware build information string. 505 506+--------------------------+-------+--------------------+--------------------+ 507| Command | OCF | Command | Return | 508| | | Parameters | Parameters | 509+--------------------------+-------+--------------------+--------------------+ 510| Read_Build_Information | 0x008 | | Status, | 511| | | | Build_Info | 512+--------------------------+-------+--------------------+--------------------+ 513 514This command shall return the build information encoded as an UTF-8 string. 515 516 Status: Size: 1 Octet 517 +--------------------+--------------------------------------+ 518 | Value | Parameter Description | 519 +--------------------+--------------------------------------+ 520 | 0x00 | Command succeeded | 521 | 0x01-0xFF | Command failed | 522 +--------------------+--------------------------------------+ 523 524 Build_Info: Size: variable 525 +--------------------+--------------------------------------+ 526 | Value | Parameter Description | 527 +--------------------+--------------------------------------+ 528 | | UTF-8 encoded build information | 529 +--------------------+--------------------------------------+ 530 531When the Read_Build_Information command has completed, a Command Complete 532event shall be generated. 533 534 535Zephyr Read Static Addresses Command 536==================================== 537 538This commands reads the controller specific static addresses. 539 540+--------------------------+-------+--------------------+--------------------+ 541| Command | OCF | Command | Return | 542| | | Parameters | Parameters | 543+--------------------------+-------+--------------------+--------------------+ 544| Read_Static_Addresses | 0x009 | | Status, | 545| | | | Num_Addresses, | 546| | | | Static_Address[i], | 547| | | | Identity_Root[i] | 548+--------------------------+-------+--------------------+--------------------+ 549 550This command shall return the static addresses programmed by the vendor at 551manufacturing time. 552 553Each returned static address shall confirm to the Static Device Address 554definition. The two most significant bits of the address shall be equal to 1. 555At least one bit of the random part of the address shall be 0. At least one bit 556of the random part of the address shall be 1. 557 558The Identity_Root parameter may be all zeros to indicate no identity root key 559being available for a given static address. The identity root key returned from 560Read_Key_Hierarchy_Roots command shall not be returned from this command. 561 562Note: If no public address is provided and a static address is available, then 563it is recommended to return an identity root key (if available) from this 564command. In case a public address is provided, then it is recommended to use 565the Read_Key_Hierarchy_Roots command to return the identity root key (if only 566one is available). 567 568 Status: Size: 1 Octet 569 +--------------------+--------------------------------------+ 570 | Value | Parameter Description | 571 +--------------------+--------------------------------------+ 572 | 0x00 | Command succeeded | 573 | 0x01-0xFF | Command failed | 574 +--------------------+--------------------------------------+ 575 576 Num_Addresses: Size: 1 Octet 577 +--------------------+--------------------------------------+ 578 | Value | Parameter Description | 579 +--------------------+--------------------------------------+ 580 | 0xXX | Number of static device addresses | 581 +--------------------+--------------------------------------+ 582 583 Static_Address[i]: Size: 6 Octets 584 +--------------------+--------------------------------------+ 585 | Value | Parameter Description | 586 +--------------------+--------------------------------------+ 587 | 0xXXXXXXXXXXXX | Static device address | 588 +--------------------+--------------------------------------+ 589 590 Identity_Root[i]: Size: 16 Octets 591 +--------------------+--------------------------------------+ 592 | Value | Parameter Description | 593 +--------------------+--------------------------------------+ 594 | | Identity root key (IR) for static | 595 | | device address | 596 | | | 597 | | All zero parameter value indicates | 598 | | missing identity root key. | 599 +--------------------+--------------------------------------+ 600 601When the Read_Static_Addresses command has completed, a Command Complete event 602shall be generated. 603 604 605Zephyr Read Key Hierarchy Roots Command 606======================================= 607 608This commands reads the controller specific identify and encryption root keys. 609 610+--------------------------+-------+--------------------+--------------------+ 611| Command | OCF | Command | Return | 612| | | Parameters | Parameters | 613+--------------------------+-------+--------------------+--------------------+ 614| Read_Key_Hierarchy_Roots | 0x00A | | Status, | 615| | | | Identity_Root, | 616| | | | Encryption_Root | 617+--------------------------+-------+--------------------+--------------------+ 618 619This command shall return the identity root key and encryption root key 620programmed by the vendor at manufacturing time. If a key is set to all zeros, 621then the associated key is not available and it should not be used in the key 622hierarchy. 623 624The identity root key and encryption root key may be used for the controllers 625public device address or a static random address generated by the host. It 626shall not be used for static addresses returned by Read_Static_Addresses 627command that have its dedicated identity root key assigned. 628 629Note: For addresses returned by Read_Static_Addresses with an all zeros 630identity root key, the returned Identity_Root value may be used. It is however 631important that it only gets assigned to a single address (either public or 632static random). 633 634Note: The Encryption_Root parameter is only useful for Legacy Pairing. In case 635of Secure Connections it can not be used. The parameter is provided here for 636completeness, but it is encouraged that Controller implementations set this 637value to all zeros. 638 639 Status: Size: 1 Octet 640 +--------------------+--------------------------------------+ 641 | Value | Parameter Description | 642 +--------------------+--------------------------------------+ 643 | 0x00 | Command succeeded | 644 | 0x01-0xFF | Command failed | 645 +--------------------+--------------------------------------+ 646 647 Identity_Root: Size: 16 Octets 648 +--------------------+--------------------------------------+ 649 | Value | Parameter Description | 650 +--------------------+--------------------------------------+ 651 | | Identity root key (IR) | 652 +--------------------+--------------------------------------+ 653 654 Encryption_Root: Size: 16 Octets 655 +--------------------+--------------------------------------+ 656 | Value | Parameter Description | 657 +--------------------+--------------------------------------+ 658 | | Encryption root key (ER) | 659 +--------------------+--------------------------------------+ 660 661When the Read_Key_Hierarchy_Roots command has completed, a Command Complete 662event shall be generated. 663 664 665Zephyr Read Chip Temperature Command 666==================================== 667 668This commands reads the controller chip temperature. 669 670+--------------------------+-------+--------------------+--------------------+ 671| Command | OCF | Command | Return | 672| | | Parameters | Parameters | 673+--------------------------+-------+--------------------+--------------------+ 674| Read_Chip_Temperature | 0x00B | | Status, | 675| | | | Temperature | 676+--------------------------+-------+--------------------+--------------------+ 677 678This command shall return the current chip temperature in degrees Celsius. 679 680 Status: Size: 1 Octet 681 +--------------------+--------------------------------------+ 682 | Value | Parameter Description | 683 +--------------------+--------------------------------------+ 684 | 0x00 | Command succeeded | 685 | 0x01-0xFF | Command failed | 686 +--------------------+--------------------------------------+ 687 688 Temperature: Size: 1 Octet 689 +--------------------+--------------------------------------+ 690 | Value | Parameter Description | 691 +--------------------+--------------------------------------+ 692 | | The measured temperature converted | 693 | | to degrees Celsius (signed integer) | 694 | | Range: -128 ≤ N ≤ 127 | 695 +--------------------+--------------------------------------+ 696 697When the Read_Chip_Temperature command has completed, a Command Complete event 698shall be generated. 699 700 701Zephyr Read Host Stack Commands Command 702======================================= 703 704This command reads the list of host stack operation system defined vendor 705commands supported for the local Controller. 706 707+--------------------------+-------+--------------------+--------------------+ 708| Command | OCF | Command | Return | 709| | | Parameters | Parameters | 710+--------------------------+-------+--------------------+--------------------+ 711| Read_Host_Stack_Commands | 0x00C | | Status, | 712| | | | Num_Commands, | 713| | | | Vendor_ID[i], | 714| | | | Opcode_Base[i] | 715+--------------------------+-------+--------------------+--------------------+ 716 717This command shall return the list of host stack operation defined vendor 718commands. They are defined based on a vendor identifier and a base opcode. 719 720With this command it is possible to incorporate external defined HCI commands 721designed for host stack operation that extend the standard and vendor specific 722Controller commands. See Android [1][2] and Microsoft [3] defined extensions. 723 724The Opcode_Base parameter points to an opcode that will identify the external 725command set. Ideally all external commands are multiplexed through that single 726opcode and also define a flexible interface for external events. 727 728 Status: Size: 1 Octet 729 +--------------------+--------------------------------------+ 730 | Value | Parameter Description | 731 +--------------------+--------------------------------------+ 732 | 0x00 | Command succeeded | 733 | 0x01-0xFF | Command failed | 734 +--------------------+--------------------------------------+ 735 736 Num_Commands: Size: 1 Octet 737 +--------------------+--------------------------------------+ 738 | Value | Parameter Description | 739 +--------------------+--------------------------------------+ 740 | 0xXX | Total number of commands | 741 +--------------------+--------------------------------------+ 742 743 Vendor_ID[i]: Size: 2 Octets 744 +--------------------+--------------------------------------+ 745 | Value | Parameter Description | 746 +--------------------+--------------------------------------+ 747 | 0x0001 | Android specific HCI commands | 748 | 0x0002 | Microsoft specific HCI commands | 749 | All other values | Reserved for future use | 750 +--------------------+--------------------------------------+ 751 752 Opcode_Base[i]: Size: 2 Octets 753 +--------------------+--------------------------------------+ 754 | Value | Parameter Description | 755 +--------------------+--------------------------------------+ 756 | 0xXXXX | Base opcode of command | 757 +--------------------+--------------------------------------+ 758 759When the Read_Host_Stack_Commands command has completed, a Command Complete 760event shall be generated. 761 762 763Zephyr Set Scan Request Reports Command 764======================================= 765 766This commands configures the report of Scan_Request_Received events. 767 768+--------------------------+-------+--------------------+--------------------+ 769| Command | OCF | Command | Return | 770| | | Parameters | Parameters | 771+--------------------------+-------+--------------------+--------------------+ 772| Set_Scan_Request_Reports | 0x00D | Enable | Status | 773+--------------------------+-------+--------------------+--------------------+ 774 775The Enable parameter indicates with the Controller shall send the 776Scan_Request_Received event upon receipt of a scan request PDU that is in an 777response to an advertisement from the specified advertising set that contains 778its device address and is from a scanner that is allowed by the advertising 779filter policy. 780 781Note: In case Extended Advertising configuration is used for setting up 782advertising sets, this shall not generate any vendor events. 783 784 Status: Size: 1 Octet 785 +--------------------+--------------------------------------+ 786 | Value | Parameter Description | 787 +--------------------+--------------------------------------+ 788 | 0x00 | Command succeeded | 789 | 0x01-0xFF | Command failed | 790 +--------------------+--------------------------------------+ 791 792 Enable: Size: 1 Octet 793 +--------------------+--------------------------------------+ 794 | Value | Parameter Description | 795 +--------------------+--------------------------------------+ 796 | 0x00 | Scan request reporting disabled | 797 | 0x01 | Scan request reporting enabled | 798 | All other values | Reserved for future use | 799 +--------------------+--------------------------------------+ 800 801When the Set_Scan_Request_Reports command has completed, a Command Complete 802event shall be generated. 803 804 805Zephyr Write Tx Power Level (per Role/Connection) Command 806========================================================= 807 808This command dynamically modifies BLE Tx power level given a handle and a 809handle type (advertiser, scanner, connection). 810 811+--------------------------+-------+--------------------+--------------------+ 812| Command | OCF | Command | Return | 813| | | Parameters | Parameters | 814+--------------------------+-------+--------------------+--------------------+ 815| Write_Tx_Power_Level | 0x00E | Handle_Type, | Status, | 816| | | Handle, | Handle_Type, | 817| | | Tx_Power_Level | Handle, | 818| | | | Selected_Tx_Power | 819+--------------------------+-------+--------------------+--------------------+ 820 821The Tx power of the BLE radio interface is modified for any low-level link by 822the controller with a high degree of flexibility. The BLE link whose power is 823set is identified based on a handle type (advertiser, scanner, connection) and 824handle pair. 825 826The role/state defining input parameter is the Handle_Type, whereas its 827corresponding handle is provided by the Handle input parameter. Note that 828for Advertisements, the Handle input parameter is ignored in the case that 829Advertising Extensions are not configured, whereas Advertising Sets are to be 830identified by their corresponding Handle in case Advertising Extensions are 831enabled. 832 833The desired transmitter power level for the selected link instance is inputted 834as Tx_Power_Level. The power setup and control can be performed dynamically 835without the need of restarting the advertiser and scanner role/states. In case 836of connections, the Tx power changes take effect only if the connections are 837in a connected state. 838 839The inputs Handle_Type and Handle are passed through as outputs to aid the 840asynchronous service of the command as well. In addition, the command returns 841also with the Selected_Tx_Power by the controller which addresses and corrects 842the possible mismatches between the desired Tx_Power_Level and the achievable 843Tx powers given each individual controller capabilities. 844 845 Handle_Type: Size: 1 Octet 846 +--------------------+--------------------------------------+ 847 | Value | Parameter Description | 848 +--------------------+--------------------------------------+ 849 | 0x00 | Handle of type Advertiser (Adv) | 850 | 0x01 | Handle of type Scanner (Scan) | 851 | 0x02 | Handle of type Connection (Conn) | 852 | 0x03-0xFF | Reserved (HCI command error) | 853 +--------------------+--------------------------------------+ 854 855 Handle: Size: 2 Octets 856 +--------------------+--------------------------------------+ 857 | Value | Parameter Description | 858 +--------------------+--------------------------------------+ 859 | | Handle of the selected Handle_Type | 860 | | that identifies the instance to set | 861 | | the power of. See below for a | 862 | | description corresponding to each | 863 | | Handle_Type | 864 | | | 865 | | Handle_Type_Adv: | 866 | 0x0000 - 0xFFFF | Legacy Advertisement Handle | 867 | | (Handle value is ignored) | 868 | 0x0000 - 0x00EF | Advertisement Extensions (AE) | 869 | | enabled Advertisement set | 870 | | Handle | 871 | | | 872 | | Handle_Type_Scan: | 873 | 0x0000 - 0xFFFF | Scanner Handle (Handle value is | 874 | | ignored) | 875 | | | 876 | | Handle_Type_Conn: | 877 | 0x0000 - 0x0EFF | Connection Handle | 878 +--------------------+--------------------------------------+ 879 880 Tx_Power_Level: Size: 1 Octet 881 +--------------------+--------------------------------------+ 882 | Value | Parameter Description | 883 +--------------------+--------------------------------------+ 884 | -127 <= N <= 126 | The desired Tx_Power_Level in signed | 885 | | 1 octet integer format to be set to | 886 | | the Handle_Type and Handle pair. The | 887 | | controller shall choose a power | 888 | | level lower than or equal to the one | 889 | | specified by the host unless the host| 890 | | desired power is lower than the | 891 | | minimum supported Tx power of the | 892 | | controller, in which case the | 893 | | controller shall use its minimum Tx | 894 | | power. | 895 | | Units: dBm | 896 | | | 897 | 127 | No preference for the Tx_Power_Level,| 898 | | the controller shall revert to using | 899 | | its default setting for Tx power. | 900 +--------------------+--------------------------------------+ 901 902 Status: Size: 1 Octet 903 +--------------------+--------------------------------------+ 904 | Value | Parameter Description | 905 +--------------------+--------------------------------------+ 906 | 0x00 | Command succeeded | 907 | 0x01-0xFF | Command failed | 908 +--------------------+--------------------------------------+ 909 910 Selected_Tx_Power: Size: 1 Octet 911 +--------------------+--------------------------------------+ 912 | Value | Parameter Description | 913 +--------------------+--------------------------------------+ 914 | -127 <= N <= 126 | The controller selected Tx power to | 915 | | set for the given Handle_Type and | 916 | | and pair formatted as a 1 octet | 917 | | signed integer. The controller shall | 918 | | not modify this transmit power unless| 919 | | it is directed to do so by the Host. | 920 | | Units: dBm | 921 +--------------------+--------------------------------------+ 922 923When the Write_Tx_Power_Level command has completed, a Command Complete 924event shall be generated. 925 926 927Zephyr Read Tx Power Level (per Role/Connection) Command 928======================================================== 929 930This command reads the BLE Tx power level. In contrast to the standardized HCI 931command, i.e. Read_Transmit_Power_Level, which returns the transmitted power 932level only for a specified connection handle, this command operates for both 933connected and unconnected states. It gets the BLE Tx power level for any given 934handle type (advertiser, scanner, connection) and handle. 935 936+--------------------------+-------+--------------------+--------------------+ 937| Command | OCF | Command | Return | 938| | | Parameters | Parameters | 939+--------------------------+-------+--------------------+--------------------+ 940| Read_Tx_Power_Level | 0x00F | Handle_Type, | Status, | 941| | | Handle | Handle_Type, | 942| | | | Handle, | 943| | | | Tx_Power_Level | 944+--------------------------+-------+--------------------+--------------------+ 945 946The Tx power of the BLE radio interface used for a low-level link identified 947by a pair of Handle_Type and Handle is retrieved from the controller. 948 949The role/state defining input parameter is the Handle_Type, whereas its 950corresponding handle is provided by the Handle input parameter. Note that 951for Advertisements, the Handle input parameter is ignored in the case that 952Advertising Extensions are not configured, whereas Advertising Sets are to be 953identified by their corresponding Handle in case Advertising Extensions are 954enabled. 955 956The command returns with an operational Status, and the replicated Handle_Type 957and Handle input parameters supplemented by the current Tx_Power_Level in use 958by the controller for the requested Handle_Type and Handle. 959 960 Handle_Type: Size: 1 Octet 961 +--------------------+--------------------------------------+ 962 | Value | Parameter Description | 963 +--------------------+--------------------------------------+ 964 | 0x00 | Handle of type Advertiser (Adv) | 965 | 0x01 | Handle of type Scanner (Scan) | 966 | 0x02 | Handle of type Connection (Conn) | 967 | 0x03-0xFF | Reserved (HCI command error) | 968 +--------------------+--------------------------------------+ 969 970 Handle: Size: 2 Octets 971 +--------------------+--------------------------------------+ 972 | Value | Parameter Description | 973 +--------------------+--------------------------------------+ 974 | | Handle of the selected Handle_Type | 975 | | that identifies the instance to read | 976 | | the power of. See below for a | 977 | | description corresponding to each | 978 | | Handle_Type | 979 | | | 980 | | Handle_Type_Adv: | 981 | 0x0000 - 0xFFFF | Legacy Advertisement Handle | 982 | | (Handle value is ignored) | 983 | 0x0000 - 0x00EF | Advertisement Extensions (AE) | 984 | | enabled Advertisement set | 985 | | Handle | 986 | | | 987 | | Handle_Type_Scan: | 988 | 0x0000 - 0xFFFF | Scanner Handle (Handle value is | 989 | | ignored) | 990 | | | 991 | | | 992 | | Handle_Type_Conn: | 993 | 0x0000 - 0x0EFF | Connection Handle | 994 +--------------------+--------------------------------------+ 995 996 Status: Size: 1 Octet 997 +--------------------+--------------------------------------+ 998 | Value | Parameter Description | 999 +--------------------+--------------------------------------+ 1000 | 0x00 | Command succeeded | 1001 | 0x01-0xFF | Command failed | 1002 +--------------------+--------------------------------------+ 1003 1004 Tx_Power_Level: Size: 1 Octet 1005 +--------------------+--------------------------------------+ 1006 | Value | Parameter Description | 1007 +--------------------+--------------------------------------+ 1008 | -127 <= N <= 126 | The current Tx_Power_Level formatted | 1009 | | as a 1 octet signed integer at which | 1010 | | the controller is operating the | 1011 | | low-level link identified by the | 1012 | | Handle_Type and Handle pair. | 1013 | | Units: dBm | 1014 +--------------------+--------------------------------------+ 1015 1016When the Read_Tx_Power_Level command has completed, a Command Complete 1017event shall be generated. 1018 1019Zephyr Read Supported USB Transport Modes Command 1020================================================= 1021 1022This command read the supported USB transport modes. 1023 1024+--------------------------+-------+--------------------+--------------------+ 1025| Command | OCF | Command | Return | 1026| | | Parameters | Parameters | 1027+--------------------------+-------+--------------------+--------------------+ 1028| Read_USB_Transport_Modes | 0x010 | | Status | 1029| | | | Num_Supported_Modes| 1030| | | | Supported_Mode[i] | 1031+--------------------------+-------+--------------------+--------------------+ 1032 1033 Supported_Mode: Size: 1 Octet 1034 +--------------------+--------------------------------------+ 1035 | Value | Parameter Description | 1036 +--------------------+--------------------------------------+ 1037 | 0x00 | USB standard (H:2) transport mode. | 1038 | | Standard mode which use dedicated | 1039 | | endpoints for commands, events and | 1040 | | data. | 1041 | 0x01 | Serial (H:4) transport mode. | 1042 | | Serialize all traffic into bulk | 1043 | | endpoints. | 1044 | All other values | Reserved for future use | 1045 +--------------------+--------------------------------------+ 1046 1047When the Read_USB_Transport_Mode command has completed, a Command Complete 1048event shall be generated. 1049 1050Zephyr Set USB Transport Mode Command 1051===================================== 1052 1053This command set the host transport mode and reset the controller states like 1054an HCI Reset command. 1055 1056+--------------------------+-------+--------------------+--------------------+ 1057| Command | OCF | Command | Return | 1058| | | Parameters | Parameters | 1059+--------------------------+-------+--------------------+--------------------+ 1060| Set_USB_Transport_Mode | 0x011 | Mode | Status | 1061+--------------------------+-------+--------------------+--------------------+ 1062 1063When the Set_USB_Transport_Mode command has completed, a Command Complete 1064event shall be generated. 1065 1066Zephyr Vendor Events 1067==================== 1068 1069The Vendor Event is used to encapsulate all vendor specific events. The event 1070code of all vendor events shall be 0xFF. The subevent code is the first octet 1071of the event parameters. The subevent code shall be set to one of the valid 1072subevent codes from a vendor specific event. All other subevent parameters are 1073defined in the vendor specific events. 1074 1075 1076Zephyr Fatal Error 1077================== 1078 1079This event reports a fatal non-recoverable error from the local Controller. 1080The event may represent Hard Fault, Bluetooth Controller assert or some other 1081non-recoverable error. The content of the event depends on a type of error it 1082represents. 1083 1084+-------------------------------+------------+-------------------------------+ 1085| Event | Event Code | Event Parameters | 1086+-------------------------------+------------+-------------------------------+ 1087| Fatal_Error | 0xFF | Subevent_Code, | 1088| | | Error_Data_Type, | 1089| | | Error_Data | 1090+-------------------------------+------------+-------------------------------+ 1091 1092The Error_Data_Type provides an information about what is the Error_Data size 1093and content. 1094 1095 Error_Data_Type: Size: 1 Octet 1096 +--------------------+--------------------------------------+ 1097 | Value | Parameter Description | 1098 +--------------------+--------------------------------------+ 1099 | 0x01 | Stack frame | 1100 | 0x02 | Controller assert data | 1101 | 0x03 | Trace data | 1102 +--------------------+--------------------------------------+ 1103 1104 Error_Data: Size: variable 1105 +--------------------+--------------------------------------+ 1106 | Value | Parameter Description | 1107 +--------------------+--------------------------------------+ 1108 | | Content and size of the parameter | 1109 | | depends on the Error_Data_Type | 1110 +--------------------+--------------------------------------+ 1111 1112Zephyr Fatal Error event with Stack Frame data represents a Hard Fault error. 1113The event is tightly related with an architecture of a CPU the Controller is 1114running on. 1115 1116 +------------------------+--------------------+ 1117 | Error Data Type | Parameters | 1118 +------------------------+--------------------+ 1119 | Stack_Frame | Error_Reason, | 1120 | | Cpu_Type, | 1121 | | Cpu_Data | 1122 +------------------------+--------------------+ 1123 1124The Cpu_Type provides information about architecture the event was 1125generated for. Cpu_Data size and content depends on Cpu_Type. This kind of a 1126Zephyr Fatal Error event may be generated by k_sys_fatal_error_handler. 1127 1128 Error_Reason: Size: 4 Octets 1129 +--------------------+--------------------------------------+ 1130 | Value | Parameter Description | 1131 +--------------------+--------------------------------------+ 1132 | 0xXXXXXXXX | The reason for the fatal error | 1133 +--------------------+--------------------------------------+ 1134 1135 Cpu Type: Size: 1 Octet 1136 +--------------------+--------------------------------------+ 1137 | Value | Parameter Description | 1138 +--------------------+--------------------------------------+ 1139 | 0x01 | Cortex-M | 1140 +--------------------+--------------------------------------+ 1141 1142 Cpu Data: Size: variable 1143 +--------------------+--------------------------------------+ 1144 | Value | Parameter Description | 1145 +--------------------+--------------------------------------+ 1146 | | CPU architecture dependent data that | 1147 | | represent a stack frame | 1148 +--------------------+--------------------------------------+ 1149 1150 CPU Data Cortex-M: 1151 +--------------------+----------+---------------------------------+ 1152 | Parameters | Size | Description | 1153 +--------------------+----------+---------------------------------+ 1154 | a1 | 4 octets | General purpose register | 1155 | a2 | 4 octets | General purpose register | 1156 | a3 | 4 octets | General purpose register | 1157 | a4 | 4 octets | General purpose register | 1158 | ip | 4 octets | Instruction pointer register | 1159 | lr | 4 octets | Link register | 1160 | xpsr | 4 octets | Program status register | 1161 +--------------------+--------------------------------------------+ 1162 1163Zephyr Fatal Error event with Controller Assert data can be generated by the 1164bt_ctlr_assert_handle. 1165 1166 +------------------------+--------------------+ 1167 | Error Data Type | Parameters | 1168 +------------------------+--------------------+ 1169 | Controller_Assert_Data | File_Name | 1170 | | Line_Number | 1171 +------------------------+--------------------+ 1172 1173 File Name: Size: variable 1174 +--------------------+--------------------------------------+ 1175 | Value | Parameter Description | 1176 +--------------------+--------------------------------------+ 1177 | | Null terminated string with file | 1178 | | name where an assert happened | 1179 +--------------------+--------------------------------------+ 1180 1181 Line Number: Size: 4 Octets 1182 +--------------------+--------------------------------------+ 1183 | Value | Parameter Description | 1184 +--------------------+--------------------------------------+ 1185 | 0xXXXXXXXX | Line number where assert happened | 1186 +--------------------+--------------------------------------+ 1187 1188Other kinds of a non-recoverable system errors can be represented by Zephyr 1189Fatal Error with Trace data. 1190 1191 +------------------------+--------------------+ 1192 | Error Data Type | Parameters | 1193 +------------------------+--------------------+ 1194 | Trace_Data | Program_Counter | 1195 | | Error_Info | 1196 +------------------------+--------------------+ 1197 1198 Program_Counter: Size: 8 Octets 1199 +--------------------+--------------------------------------+ 1200 | Value | Parameter Description | 1201 +--------------------+--------------------------------------+ 1202 | 0xXXXXXXXXXXXXXXXX | Program counter where the error | 1203 | | occurred | 1204 +--------------------+--------------------------------------+ 1205 1206 Error_Info: Size: variable 1207 +--------------------+--------------------------------------+ 1208 | Value | Parameter Description | 1209 +--------------------+--------------------------------------+ 1210 | | UTF-8 encoded error information | 1211 +--------------------+--------------------------------------+ 1212 1213The event is reported by default unless masked away by Set_Event_Mask command. 1214 1215 1216Zephyr Trace Information Event 1217============================== 1218 1219This event reports the link manager and link layer trace information. 1220 1221+-------------------------------+------------+-------------------------------+ 1222| Event | Event Code | Event Parameters | 1223+-------------------------------+------------+-------------------------------+ 1224| Trace_Information | 0xFF | Subevent_Code, | 1225| | | Trace_Type, | 1226| | | Trace_Data | 1227+-------------------------------+------------+-------------------------------+ 1228 1229The trace type provides information about the link manager protocol or link 1230layer control protocol direction information. The trace data is the specific to 1231the trace type and represents the protocol specific data. 1232 1233 Subevent_Code: Size: 1 Octet 1234 +--------------------+--------------------------------------+ 1235 | Value | Parameter Description | 1236 +--------------------+--------------------------------------+ 1237 | 0x03 | Subevent code for Trace Information | 1238 | | event | 1239 +--------------------+--------------------------------------+ 1240 1241 Trace_Type: Size: 1 Octet 1242 +--------------------+--------------------------------------+ 1243 | Value | Parameter Description | 1244 +--------------------+--------------------------------------+ 1245 | 0x01 | LMP TX | 1246 | 0x02 | LMP RX | 1247 | 0x03 | LLCP TX | 1248 | 0x04 | LLCP RX | 1249 | 0x05 | LE CONN_IND | 1250 | All other values | Reserved for future use | 1251 +--------------------+--------------------------------------+ 1252 1253 Trace_Data: Size: variable 1254 +--------------------+--------------------------------------+ 1255 | Value | Parameter Description | 1256 +--------------------+--------------------------------------+ 1257 | | Trace packet data | 1258 +--------------------+--------------------------------------+ 1259 1260The event is only reported when unmasked by Set_Event_Mask command. 1261 1262 1263Zephyr Scan Request Received Event 1264================================== 1265 1266This event indicates that a SCAN_REQ PDU has been received by an advertiser. 1267 1268+-------------------------------+------------+-------------------------------+ 1269| Event | Event Code | Event Parameters | 1270+-------------------------------+------------+-------------------------------+ 1271| Scan_Request_Received | 0xFF | Subevent_Code, | 1272| | | Address_Type, | 1273| | | Address, | 1274| | | RSSI | 1275+-------------------------------+------------+-------------------------------+ 1276 1277The request contains a device address from a scanner that is allowed by the 1278advertising filter policy. 1279 1280Note: In case Extended Advertising configuration is used for setting up 1281advertising sets, this event shall not be generated. 1282 1283 Subevent_Code: Size: 1 Octet 1284 +--------------------+--------------------------------------+ 1285 | Value | Parameter Description | 1286 +--------------------+--------------------------------------+ 1287 | 0x04 | Subevent code for Scan Request | 1288 | | Received event | 1289 +--------------------+--------------------------------------+ 1290 1291 Address_Type: Size: 1 Octet 1292 +--------------------+--------------------------------------+ 1293 | Value | Parameter Description | 1294 +--------------------+--------------------------------------+ 1295 | 0x00 | Public Device Address | 1296 | 0x01 | Random Device Address | 1297 | 0x02 | Public Identity Address | 1298 | 0x03 | Random (static) Identity Address | 1299 | All other values | Reserved for future use | 1300 +--------------------+--------------------------------------+ 1301 1302 Address: Size: 6 Octets 1303 +--------------------+--------------------------------------+ 1304 | Value | Parameter Description | 1305 +--------------------+--------------------------------------+ 1306 | 0xXXXXXXXXXXXX | Public Device Address, Random Device | 1307 | | Address, Public Identity Address or | 1308 | | Random (static) Identity Address of | 1309 | | the advertising device. | 1310 +--------------------+--------------------------------------+ 1311 1312 RSSI: Size: 1 Octet 1313 +--------------------+--------------------------------------+ 1314 | Value | Parameter Description | 1315 +--------------------+--------------------------------------+ 1316 | N | Size: 1 Octet (signed integer) | 1317 | | Range: -127 <= N <= +20 | 1318 | | Units: dBm | 1319 +--------------------+--------------------------------------+ 1320 | 127 | RSSI is not available | 1321 +--------------------+--------------------------------------+ 1322 | 21 to 126 | Reserved for future use | 1323 +--------------------+--------------------------------------+ 1324 1325The event is only reported when unmasked by Set_Event_Mask command. 1326 1327 1328Zephyr LE Connectionless IQ Report Event 1329======================================== 1330 1331This event indicates that periodic advertising PDU including Constant Tone 1332Extension was received and sampled. 1333 1334+-------------------------------+------------+-------------------------------+ 1335| Event | Event Code | Event Parameters | 1336+-------------------------------+------------+-------------------------------+ 1337| LE_Connectionless_IQ_Report | 0xFF | Subevent_Code, | 1338| | | Sync_Handle, | 1339| | | Channel_Index, | 1340| | | RSSI, | 1341| | | RSSI_Antenna_ID, | 1342| | | CTE_Type, | 1343| | | Slot_Durations, | 1344| | | Packet_Status, | 1345| | | Periodic_Event_Counter, | 1346| | | Sample_Count, | 1347| | | I_Sample[i], | 1348| | | Q_Sample[i] | 1349+-------------------------------+------------+-------------------------------+ 1350 1351 The event provides collected IQ samples that are stored as 16 bit signed 1352 integers. It is an extension to LE Connectionless IQ Report Event provided 1353 by Bluetooth Core 5.3 Vol 4, Part E section 7.7.65.21. The BT Core defined 1354 counterpart provides IQ samples that are 8 bit signed integers. 1355 1356 Subevent_Code: Size: 1 Octet 1357 +--------------------+--------------------------------------+ 1358 | Value | Parameter Description | 1359 +--------------------+--------------------------------------+ 1360 | 0x05 | Subevent code for LE Connectionless | 1361 | | IQ Report event | 1362 +--------------------+--------------------------------------+ 1363 1364 Sync_Handle: Size: 2 octets (12 bits meaningful) 1365 +--------------------+--------------------------------------+ 1366 | Value | Parameter Description | 1367 +--------------------+--------------------------------------+ 1368 | 0xXXXX | Sync_Handle identifying the periodic | 1369 | | advertising train. | 1370 | | Range: 0x0000 to 0x0EFF | 1371 +--------------------+--------------------------------------+ 1372 | 0x0FFF | Receiver Test. | 1373 +--------------------+--------------------------------------+ 1374 1375 Channel_Index: Size: 1 octet 1376 +--------------------+--------------------------------------+ 1377 | Value | Parameter Description | 1378 +--------------------+--------------------------------------+ 1379 | 0x00 to 0x27 | The index of the channel on which the| 1380 | | packet was received. Note: 0x25 to | 1381 | | 0x27 can be used only for packets | 1382 | | generated during test modes. | 1383 +--------------------+--------------------------------------+ 1384 | All other values | Reserved for future use | 1385 +--------------------+--------------------------------------+ 1386 1387 RSSI: Size: 2 octets 1388 +--------------------+--------------------------------------+ 1389 | Value | Parameter Description | 1390 +--------------------+--------------------------------------+ 1391 | 0xXXXX | RSSI of the packet | 1392 | | Range: -1270 to +200 | 1393 | | Units: 0.1 dBm | 1394 +--------------------+--------------------------------------+ 1395 1396 1397 RSSI_Antenna_ID: Size: 1 octet 1398 +--------------------+--------------------------------------+ 1399 | Value | Parameter Description | 1400 +--------------------+--------------------------------------+ 1401 | 0xXX | Antenna ID | 1402 +--------------------+--------------------------------------+ 1403 1404 CTE_Type: Size: 1 octet 1405 +--------------------+--------------------------------------+ 1406 | Value | Parameter Description | 1407 +--------------------+--------------------------------------+ 1408 | 0x00 | AoA Constant Tone Extension | 1409 +--------------------+--------------------------------------+ 1410 | 0x01 | AoD Constant Tone Extension with | 1411 | | 1 us slots | 1412 +--------------------+--------------------------------------+ 1413 | 0x02 | AoD Constant Tone Extension with | 1414 | | 2 us slots | 1415 +--------------------+--------------------------------------+ 1416 | All other values | Reserved for future use | 1417 +--------------------+--------------------------------------+ 1418 1419 1420 Slot_Durations: Size: 1 octet 1421 +--------------------+--------------------------------------+ 1422 | Value | Parameter Description | 1423 +--------------------+--------------------------------------+ 1424 | 0x01 | Switching and sampling slots are | 1425 | | 1 µs each | 1426 +--------------------+--------------------------------------+ 1427 | 0x02 | Switching and sampling slots are | 1428 | | 2 µs each | 1429 +--------------------+--------------------------------------+ 1430 | All other values | Reserved for future use | 1431 +--------------------+--------------------------------------+ 1432 1433 Packet_Status: Size: 1 octet 1434 +--------------------+--------------------------------------+ 1435 | Value | Parameter Description | 1436 +--------------------+--------------------------------------+ 1437 | 0x00 | Packet_Status | 1438 +--------------------+--------------------------------------+ 1439 | 0x01 | CRC was incorrect and the Length and | 1440 | | CTETime fields of the packet were | 1441 | | used to determine sampling points | 1442 +--------------------+--------------------------------------+ 1443 | 0x02 | CRC was incorrect but the Controller | 1444 | | has determined the position and | 1445 | | length of the Constant Tone Extension| 1446 | | in some other way | 1447 +--------------------+--------------------------------------+ 1448 | 0xFF | Insufficient resources to sample | 1449 | | (Channel_Index, CTE_Type, and | 1450 | | Slot_Durations invalid). | 1451 +--------------------+--------------------------------------+ 1452 | All other values | Reserved for future use | 1453 +--------------------+--------------------------------------+ 1454 1455 Periodic_Event_Counter: Size: 2 octets 1456 +--------------------+--------------------------------------+ 1457 | Value | Parameter Description | 1458 +--------------------+--------------------------------------+ 1459 | 0xXXXX | The value of paEventCounter (see | 1460 | | [Vol 6] Part B, Section 4.4.2.1) for | 1461 | | the reported AUX_SYNC_IND PDU | 1462 +--------------------+--------------------------------------+ 1463 1464 Sample_Count: Size: 1 octet 1465 +--------------------+--------------------------------------+ 1466 | Value | Parameter Description | 1467 +--------------------+--------------------------------------+ 1468 | 0x00 | No samples provided (only permitted | 1469 | | if Packet_Status is 0xFF). | 1470 +--------------------+--------------------------------------+ 1471 | 0x09 to 0x52 | Total number of sample pairs (there | 1472 | | shall be the same number of I samples| 1473 | | and Q samples). | 1474 | | Note: This number is dependent on the| 1475 | | switch and sample slot durations used| 1476 +--------------------+--------------------------------------+ 1477 | All other values | Reserved for future use | 1478 +--------------------+--------------------------------------+ 1479 1480 I_Sample[i]: Size: Sample_count x 2 octets 1481 +--------------------+--------------------------------------+ 1482 | Value | Parameter Description | 1483 +--------------------+--------------------------------------+ 1484 | 0x8000 | No valid sample available or sample | 1485 | | is saturated | 1486 +--------------------+--------------------------------------+ 1487 | All other values | I sample for the reported packet | 1488 | | (signed integer). | 1489 | | The list in the order of the sampling| 1490 | | points within the packet. | 1491 +--------------------+--------------------------------------+ 1492 1493 Q_Sample[i]: Size: Sample_count x 2 octets 1494 +--------------------+--------------------------------------+ 1495 | Value | Parameter Description | 1496 +--------------------+--------------------------------------+ 1497 | 0x8000 | No valid sample available or sample | 1498 | | is saturated | 1499 +--------------------+--------------------------------------+ 1500 | All other values | Q sample for the reported packet | 1501 | | (signed integer). | 1502 | | The list in the order of the sampling| 1503 | | points within the packet. | 1504 +--------------------+--------------------------------------+ 1505 1506Zephyr LE Connection IQ Report Event 1507==================================== 1508 1509This event indicates that there was received and sampled a PDU including 1510Constant Tone Extension associated with a given connection. 1511 1512+-------------------------------+------------+-------------------------------+ 1513| Event | Event Code | Event Parameters | 1514+-------------------------------+------------+-------------------------------+ 1515| LE_Connection_IQ_Report | 0xFF | Subevent_Code, | 1516| | | Connection_Handle, | 1517| | | RF_PHY, | 1518| | | Data_Channel_Index, | 1519| | | RSSI, | 1520| | | RSSI_Antenna_ID, | 1521| | | CTE_Type, | 1522| | | Slot_Durations, | 1523| | | Packet_Status, | 1524| | | Connection_Event_Counter, | 1525| | | Sample_Count, | 1526| | | I_Sample[i], | 1527| | | Q_Sample[i] | 1528+-------------------------------+------------+-------------------------------+ 1529 1530 The event provides collected IQ samples that are stored as 16 bit signed 1531 integers. It is an extension to LE Connection IQ Report Event provided 1532 by Bluetooth Core 5.3 Vol 4, Part E section 7.7.65.22. The BT Core defined 1533 counterpart provides IQ samples that are 8 bit signed integers. 1534 1535 Subevent_Code: Size: 1 Octet 1536 +--------------------+--------------------------------------+ 1537 | Value | Parameter Description | 1538 +--------------------+--------------------------------------+ 1539 | 0x06 | Subevent code for LE Connection IQ | 1540 | | Report event | 1541 +--------------------+--------------------------------------+ 1542 1543 Connection_Handle: Size: 2 octets (12 bits meaningful) 1544 +--------------------+--------------------------------------+ 1545 | Value | Parameter Description | 1546 +--------------------+--------------------------------------+ 1547 | 0xXXXX | Connection_Handle identifying the | 1548 | | connection. | 1549 | | Range: 0x0000 to 0x0EFF | 1550 +--------------------+--------------------------------------+ 1551 1552 RF_PHY: Size: 1 octet 1553 +--------------------+--------------------------------------+ 1554 | Value | Parameter Description | 1555 +--------------------+--------------------------------------+ 1556 | 0x01 | The receiver PHY for the connection | 1557 | | is LE 1M | 1558 +--------------------+--------------------------------------+ 1559 | 0x02 | The receiver PHY for the connection | 1560 | | is LE 2M | 1561 +--------------------+--------------------------------------+ 1562 | All other values | Reserved for future use | 1563 +--------------------+--------------------------------------+ 1564 1565 Data_Channel_Index: Size: 1 octet 1566 +--------------------+--------------------------------------+ 1567 | Value | Parameter Description | 1568 +--------------------+--------------------------------------+ 1569 | 0x00 to 0x24 | The index of the data channel on | 1570 | | which the Data Physical Channel PDU | 1571 | | was received. | 1572 +--------------------+--------------------------------------+ 1573 | All other values | Reserved for future use | 1574 +--------------------+--------------------------------------+ 1575 1576 RSSI: Size: 2 octets 1577 +--------------------+--------------------------------------+ 1578 | Value | Parameter Description | 1579 +--------------------+--------------------------------------+ 1580 | 0xXXXX | RSSI of the packet | 1581 | | Range: -1270 to +200 | 1582 | | Units: 0.1 dBm | 1583 +--------------------+--------------------------------------+ 1584 1585 RSSI_Antenna_ID: Size: 1 octet 1586 +--------------------+--------------------------------------+ 1587 | Value | Parameter Description | 1588 +--------------------+--------------------------------------+ 1589 | 0xXX | Antenna ID | 1590 +--------------------+--------------------------------------+ 1591 1592 CTE_Type: Size: 1 octet 1593 +--------------------+--------------------------------------+ 1594 | Value | Parameter Description | 1595 +--------------------+--------------------------------------+ 1596 | 0x00 | AoA Constant Tone Extension | 1597 +--------------------+--------------------------------------+ 1598 | 0x01 | AoD Constant Tone Extension with | 1599 | | 1 us slots | 1600 +--------------------+--------------------------------------+ 1601 | 0x02 | AoD Constant Tone Extension with | 1602 | | 2 us slots | 1603 +--------------------+--------------------------------------+ 1604 | All other values | Reserved for future use | 1605 +--------------------+--------------------------------------+ 1606 1607 Slot_Durations: Size: 1 octet 1608 +--------------------+--------------------------------------+ 1609 | Value | Parameter Description | 1610 +--------------------+--------------------------------------+ 1611 | 0x01 | Switching and sampling slots are | 1612 | | 1 µs each | 1613 +--------------------+--------------------------------------+ 1614 | 0x02 | Switching and sampling slots are | 1615 | | 2 µs each | 1616 +--------------------+--------------------------------------+ 1617 | All other values | Reserved for future use | 1618 +--------------------+--------------------------------------+ 1619 1620 Packet_Status: Size: 1 octet 1621 +--------------------+--------------------------------------+ 1622 | Value | Parameter Description | 1623 +--------------------+--------------------------------------+ 1624 | 0x00 | Packet_Status | 1625 +--------------------+--------------------------------------+ 1626 | 0x01 | CRC was incorrect and the Length and | 1627 | | CTETime fields of the packet were | 1628 | | used to determine sampling points | 1629 +--------------------+--------------------------------------+ 1630 | 0x02 | CRC was incorrect but the Controller | 1631 | | has determined the position and | 1632 | | length of the Constant Tone Extension| 1633 | | in some other way | 1634 +--------------------+--------------------------------------+ 1635 | 0xFF | Insufficient resources to sample | 1636 | | (Channel_Index, CTE_Type, and | 1637 | | Slot_Durations invalid). | 1638 +--------------------+--------------------------------------+ 1639 | All other values | Reserved for future use | 1640 +--------------------+--------------------------------------+ 1641 1642 Connection_Event_Counter: Size: 2 octets 1643 +--------------------+--------------------------------------+ 1644 | Value | Parameter Description | 1645 +--------------------+--------------------------------------+ 1646 | 0xXXXX | The value of connEventCounter (see | 1647 | | [Vol 6] Part B, Section 4.5.1) for | 1648 | | the reported PDU | 1649 +--------------------+--------------------------------------+ 1650 1651 Sample_Count: Size: 1 octet 1652 +--------------------+--------------------------------------+ 1653 | Value | Parameter Description | 1654 +--------------------+--------------------------------------+ 1655 | 0x00 | No samples provided (only permitted | 1656 | | if Packet_Status is 0xFF). | 1657 +--------------------+--------------------------------------+ 1658 | 0x09 to 0x52 | Total number of sample pairs (there | 1659 | | shall be the same number of I samples| 1660 | | and Q samples). | 1661 | | Note: This number is dependent on the| 1662 | | switch and sample slot durations used| 1663 +--------------------+--------------------------------------+ 1664 | All other values | Reserved for future use | 1665 +--------------------+--------------------------------------+ 1666 1667 I_Sample[i]: Size: Sample_count x 2 octets 1668 +--------------------+--------------------------------------+ 1669 | Value | Parameter Description | 1670 +--------------------+--------------------------------------+ 1671 | 0x8000 | No valid sample available or sample | 1672 | | is saturated | 1673 +--------------------+--------------------------------------+ 1674 | All other values | I sample for the reported packet | 1675 | | (signed integer). | 1676 | | The list in the order of the sampling| 1677 | | points within the packet. | 1678 +--------------------+--------------------------------------+ 1679 1680 Q_Sample[i]: Size: Sample_count x 2 octets 1681 +--------------------+--------------------------------------+ 1682 | Value | Parameter Description | 1683 +--------------------+--------------------------------------+ 1684 | 0x8000 | No valid sample available or sample | 1685 | | is saturated | 1686 +--------------------+--------------------------------------+ 1687 | All other values | Q sample for the reported packet | 1688 | | (signed integer). | 1689 | | The list in the order of the sampling| 1690 | | points within the packet. | 1691 +--------------------+--------------------------------------+ 1692 1693 Zephyr Vendor Diagnostic Channel 1694================================ 1695 1696The vendor diagnostic channel allows for an independent side channel to provide 1697extra information from the local Controller to the Host. 1698 16990 8 16 24 1700+--------------+--------------+--------------+--------------+ 1701| Channel Code | Parameter | Channel Parameters 1702| | Total Length | 1703+--------------+--------------+--------------+--------------+ 1704 1705The diagnostic channel provides multiplexing of diagnostic information based on 1706a channel code. The channel parameters content depends on the channel code. 1707 1708 Channel_Code: Size: 1 Octet 1709 +--------------------+--------------------------------------+ 1710 | Value | Parameter Description | 1711 +--------------------+--------------------------------------+ 1712 | 0x00 | Trace Information | 1713 | TBD | Debug information | 1714 | All other values | Reserved for future use | 1715 +--------------------+--------------------------------------+ 1716 1717 Parameter_Total_Length: Size: 1 Octet 1718 +--------------------+--------------------------------------+ 1719 | Value | Parameter Description | 1720 +--------------------+--------------------------------------+ 1721 | 0xXX | Length of all of the parameters | 1722 | | contained in this packet, measured | 1723 | | in octets | 1724 +--------------------+--------------------------------------+ 1725 1726For UART transport (H:4) the type 0xFF shall be used. For USB transport (H:2) 1727an extra USB endpoint shall be used. 1728 1729 1730References 1731========== 1732 1733[1] https://source.android.com/devices/Android-5.0-Bluetooth-HCI-Reqs.pdf 1734[2] https://source.android.com/devices/Android-6.0-Bluetooth-HCI-Reqs.pdf 1735[3] https://msdn.microsoft.com/en-us/library/windows/hardware/dn917903.aspx 1736
