doc/mgmt-api.txt

   1 Bluetooth Management API
   2 *************************
   3
   4 Copyright (C) 2008-2009  Marcel Holtmann <marcel@holtmann.org>
   5
   6
   7 Overview
   8 ========
   9
  10 This document describes the format of data used for communicating with
  11 the kernel using a so-called Bluetooth Management sockets. These sockets
  12 are available starting with Linux kernel version 3.4
  13
  14 The following kernel versions introduced new commands, new events or
  15 important fixes to the Bluetooth Management API:
  16
  17 Linux kernel v3.4       Version 1.0
  18 Linux kernel v3.5       Version 1.1
  19 Linux kernel v3.7       Version 1.2
  20 Linux kernel v3.9       Version 1.3
  21 Linux kernel v3.13      Version 1.4
  22 Linux kernel v3.15      Version 1.5
  23 Linux kernel v3.16      Version 1.6
  24 Linux kernel v3.17      Version 1.7
  25 Linux kernel v3.19      Version 1.8
  26 Linux kernel v4.1       Version 1.9
  27 Linux kernel v4.2       Version 1.10
  28 Linux kernel v4.5       Version 1.11 (not yet released)
  29
  30 Version 1.1 introduces Set Device ID command.
  31
  32 Version 1.2 introduces Passkey Notify event.
  33
  34 Version 1.3 does not introduce any new command or event.
  35
  36 Version 1.4 introduces Set Advertising, Set BR/EDR, Set Static Address
  37 and Set Scan Parameters commands. The existing Set Discoverable command
  38 gained an extra setting for limited discoverable mode. The device name
  39 is now provided in the scan response data for Low Energy.
  40
  41 Version 1.5 introduces Set Secure Connections, Set Debug Keys, Set Privacy
  42 and Load Identity Resolving Keys commands. It also introduces New Identity
  43 Resolving Key and New Signature Resolving Key events.
  44
  45 Version 1.6 introduces Get Connection Information command. It also updates
  46 the Device Found event to combine advertising data and scan response data
  47 into a single event.
  48
  49 Version 1.7 introduces Get Clock Information, Add Device, Remove Device,
  50 Load Connection Parameters, Read Unconfigured Index List, Read Controller
  51 Configuration Information, Set External Configuration and Set Public Address
  52 commands. It also introduces Device Added, Device Removed, New Connection
  53 Parameter, Unconfigured Index Added, Unconfigured Index Removed and New
  54 Configuration Options events. The existing Set Debug Keys command gained
  55 an extra setting for enabling SSP debug mode.
  56
  57 Version 1.8 introduces Start Service Discovery command. It also adds new
  58 Long Term Key types for LE Secure Connection feature.
  59
  60 Version 1.9 introduces Read Local Out Of Band Extended, Data, Read Extended
  61 Controller Index List, Read Advertising Features, Add Advertising and Remove
  62 Advertising commands. It also introduces Extended Index Added, Extended Index
  63 Removed, Local Out Of Band Extended Data Updated, Advertising Added and
  64 Advertising Removed events. The existing Set Advertising command gained an
  65 extra setting for enabling undirected connectable advertising. It provides
  66 support for a new static address setting and allows the usage of Set Fast
  67 Connectable when controller is powered off.
  68
  69 Version 1.10 does not introduce any new command or event. It extends the
  70 advertising feature to support 5 parallel advertising instances.
  71
  72 Version 1.11 introduces Get Advertising Size Information command.
  73
  74
  75 Example
  76 =======
  77
  78 The Bluetooth management sockets can be created by setting the hci_channel
  79 member of struct sockaddr_hci to HCI_CHANNEL_CONTROL (3) when creating a
  80 raw HCI socket. In C the needed code would look something like the following:
  81
  82 int mgmt_create(void)
  83 {
  84         struct sockaddr_hci addr;
  85         int fd;
  86
  87         fd = socket(PF_BLUETOOTH, SOCK_RAW | SOCK_CLOEXEC | SOCK_NONBLOCK,
  88                                                                 BTPROTO_HCI);
  89         if (fd < 0)
  90                 return -errno;
  91
  92         memset(&addr, 0, sizeof(addr));
  93         addr.hci_family = AF_BLUETOOTH;
  94         addr.hci_dev = HCI_DEV_NONE;
  95         addr.hci_channel = HCI_CHANNEL_CONTROL;
  96
  97         if (bind(fd, (struct sockaddr *) &addr, sizeof(addr)) < 0) {
  98                 int err = -errno;
  99                 close(fd);
 100                 return err;
 101         }
 102
 103         return fd;
 104 }
 105
 106 The process creating the mgmt socket is required to have the
 107 CAP_NET_ADMIN capability (e.g. root would have this).
 108
 109
 110 Packet Structures
 111 =================
 112
 113         Commands:
 114
 115         0    4    8   12   16   22   24   28   31   35   39   43   47
 116         +-------------------+-------------------+-------------------+
 117         |  Command Code     |  Controller Index |  Parameter Length |
 118         +-------------------+-------------------+-------------------+
 119         |                                                           |
 120
 121         Events:
 122
 123         0    4    8   12   16   22   24   28   31   35   39   43   47
 124         +-------------------+-------------------+-------------------+
 125         |  Event Code       |  Controller Index |  Parameter Length |
 126         +-------------------+-------------------+-------------------+
 127         |                                                           |
 128
 129 All fields are in little-endian byte order (least significant byte first).
 130
 131 Controller Index can have a special value <non-controller> to indicate that
 132 command or event is not related to any controller. Possible values:
 133
 134         <controller id>         0x0000 to 0xFFFE
 135         <non-controller>        0xFFFF
 136
 137
 138 Error Codes
 139 ===========
 140
 141 The following values have been defined for use with the Command Status
 142 and Command Complete events:
 143
 144 0x00    Success
 145 0x01    Unknown Command
 146 0x02    Not Connected
 147 0x03    Failed
 148 0x04    Connect Failed
 149 0x05    Authentication Failed
 150 0x06    Not Paired
 151 0x07    No Resources
 152 0x08    Timeout
 153 0x09    Already Connected
 154 0x0A    Busy
 155 0x0B    Rejected
 156 0x0C    Not Supported
 157 0x0D    Invalid Parameters
 158 0x0E    Disconnected
 159 0x0F    Not Powered
 160 0x10    Cancelled
 161 0x11    Invalid Index
 162 0x12    RFKilled
 163 0x13    Already Paired
 164 0x14    Permission Denied
 165
 166 As a general rule all commands generate the events as specified below,
 167 however invalid lengths or unknown commands will always generate a
 168 Command Status response (with Unknown Command or Invalid Parameters
 169 status). Sending a command with an invalid Controller Index value will
 170 also always generate a Command Status event with the Invalid Index
 171 status code.
 172
 173
 174 Read Management Version Information Command
 175 ===========================================
 176
 177         Command Code:           0x0001
 178         Controller Index:       <non-controller>
 179         Command Parameters:
 180         Return Parameters:      Version (1 Octets)
 181                                 Revision (2 Octets)
 182
 183         This command returns the Management version and revision.
 184         Besides, being informational the information can be used to
 185         determine whether certain behavior has changed or bugs fixed
 186         when interacting with the kernel.
 187
 188         This command generates a Command Complete event on success or
 189         a Command Status event on failure.
 190
 191
 192 Read Management Supported Commands Command
 193 ==========================================
 194
 195         Command Code:           0x0002
 196         Controller Index:       <non-controller>
 197         Command Parameters:
 198         Return Parameters:      Num_Of_Commands (2 Octets)
 199                                 Num_Of_Events (2 Octets)
 200                                 Command1 (2 Octets)
 201                                 Command2 (2 Octets)
 202                                 ...
 203                                 Event1 (2 Octets)
 204                                 Event2 (2 Octets)
 205                                 ...
 206
 207         This command returns the list of supported Management commands
 208         and events.
 209
 210         The commands Read Management Version Information and Read
 211         management Supported Commands are not included in this list.
 212         Both commands are always supported and mandatory.
 213
 214         The events Command Status and Command Complete are not included
 215         in this list. Both are implicit and mandatory.
 216
 217         This command generates a Command Complete event on success or
 218         a Command Status event on failure.
 219
 220
 221 Read Controller Index List Command
 222 ==================================
 223
 224         Command Code:           0x0003
 225         Controller Index:       <non-controller>
 226         Command Parameters:
 227         Return Parameters:      Num_Controllers (2 Octets)
 228                                 Controller_Index[i] (2 Octets)
 229
 230         This command returns the list of currently known controllers.
 231         Controllers added or removed after calling this command can be
 232         monitored using the Index Added and Index Removed events.
 233
 234         This command generates a Command Complete event on success or
 235         a Command Status event on failure.
 236
 237
 238 Read Controller Information Command
 239 ===================================
 240
 241         Command Code:           0x0004
 242         Controller Index:       <controller id>
 243         Command Parameters:
 244         Return Parameters:      Address (6 Octets)
 245                                 Bluetooth_Version (1 Octet)
 246                                 Manufacturer (2 Octets)
 247                                 Supported_Settings (4 Octets)
 248                                 Current_Settings (4 Octets)
 249                                 Class_Of_Device (3 Octets)
 250                                 Name (249 Octets)
 251                                 Short_Name (11 Octets)
 252
 253         This command is used to retrieve the current state and basic
 254         information of a controller. It is typically used right after
 255         getting the response to the Read Controller Index List command
 256         or an Index Added event.
 257
 258         The Address parameter describes the controllers public address
 259         and it can be expected that it is set. However in case of single
 260         mode Low Energy only controllers it can be 00:00:00:00:00:00. To
 261         power on the controller in this case, it is required to configure
 262         a static address using Set Static Address command first.
 263
 264         If the public address is set, then it will be used as identity
 265         address for the controller. If no public address is available,
 266         then the configured static address will be used as identity
 267         address.
 268
 269         In the case of a dual-mode controller with public address that
 270         is configured as Low Energy only device (BR/EDR switched off),
 271         the static address is used when set and public address otherwise.
 272
 273         If no short name is set the Short_Name parameter will be empty
 274         (begin with a nul byte).
 275
 276         Current_Settings and Supported_Settings is a bitmask with
 277         currently the following available bits:
 278
 279                 0       Powered
 280                 1       Connectable
 281                 2       Fast Connectable
 282                 3       Discoverable
 283                 4       Bondable
 284                 5       Link Level Security (Sec. mode 3)
 285                 6       Secure Simple Pairing
 286                 7       Basic Rate/Enhanced Data Rate
 287                 8       High Speed
 288                 9       Low Energy
 289                 10      Advertising
 290                 11      Secure Connections
 291                 12      Debug Keys
 292                 13      Privacy
 293                 14      Controller Configuration
 294                 15      Static Address
 295
 296         This command generates a Command Complete event on success or
 297         a Command Status event on failure.
 298
 299         Possible errors:        Invalid Parameters
 300                                 Invalid Index
 301
 302
 303 Set Powered Command
 304 ===================
 305
 306         Command Code:           0x0005
 307         Controller Index:       <controller id>
 308         Command Parameters:     Powered (1 Octet)
 309         Return Parameters:      Current_Settings (4 Octets)
 310
 311         This command is used to power on or off a controller. The
 312         allowed Powered command parameter values are 0x00 and 0x01. All
 313         other values will return Invalid Parameters.
 314
 315         If discoverable setting is activated with a timeout, then
 316         switching the controller off will expire this timeout and
 317         disable discoverable.
 318
 319         Settings programmed via Set Advertising and Add/Remove
 320         Advertising while the controller was powered off will be activated
 321         when powering the controller on.
 322
 323         Switching the controller off will permanently cancel and remove
 324         all advertising instances with a timeout set, i.e. time limited
 325         advertising instances are not being remembered across power cycles.
 326         Advertising Removed events will be issued accordingly.
 327
 328         This command generates a Command Complete event on success or
 329         a Command Status event on failure.
 330
 331         Possible errors:        Busy
 332                                 Invalid Parameters
 333                                 Invalid Index
 334
 335
 336 Set Discoverable Command
 337 ========================
 338
 339         Command Code:           0x0006
 340         Controller Index:       <controller id>
 341         Command Parameters:     Discoverable (1 Octet)
 342                                 Timeout (2 Octets)
 343         Return Parameters:      Current_Settings (4 Octets)
 344
 345         This command is used to set the discoverable property of a
 346         controller. The allowed Discoverable command parameter values
 347         are 0x00, 0x01 and 0x02. All other values will return Invalid
 348         Parameters.
 349
 350         Timeout is the time in seconds and is only meaningful when
 351         Discoverable is set to 0x01 or 0x02. Providing a timeout
 352         with 0x00 return Invalid Parameters. For 0x02, the timeout
 353         value is required.
 354
 355         The value 0x00 disables discoverable, the value 0x01 enables
 356         general discoverable and the value 0x02 enables limited
 357         discoverable.
 358
 359         This command is only available for BR/EDR capable controllers
 360         (e.g. not for single-mode LE ones). It will return Not Supported
 361         otherwise.
 362
 363         This command can be used when the controller is not powered and
 364         all settings will be programmed once powered.
 365
 366         However using a timeout when the controller is not powered will
 367         return Not Powered error.
 368
 369         When switching discoverable on and the connectable setting is
 370         off it will return Rejected error.
 371
 372         This command generates a Command Complete event on success or
 373         a Command Status event on failure.
 374
 375         Possible errors:        Busy
 376                                 Rejected
 377                                 Not Supported
 378                                 Invalid Parameters
 379                                 Not Powered
 380                                 Invalid Index
 381
 382
 383 Set Connectable Command
 384 =======================
 385
 386         Command Code:           0x0007
 387         Controller Index:       <controller id>
 388         Command Parameters:     Connectable (1 Octet)
 389         Return Parameters:      Current_Settings (4 Octets)
 390
 391         This command is used to set the connectable property of a
 392         controller. The allowed Connectable command parameter values are
 393         0x00 and 0x01. All other values will return Invalid Parameters.
 394
 395         This command is available for BR/EDR, LE-only and also dual
 396         mode controllers. For BR/EDR is changes the page scan setting
 397         and for LE controllers it changes the advertising type. For
 398         dual mode controllers it affects both settings.
 399
 400         For LE capable controllers the connectable setting takes effect
 401         when advertising is enabled (peripheral) or when directed
 402         advertising events are received (central).
 403
 404         This command can be used when the controller is not powered and
 405         all settings will be programmed once powered.
 406
 407         When switching connectable off, it will also switch off the
 408         discoverable setting. Switching connectable back on will not
 409         restore a previous discoverable. It will stay off and needs
 410         to be manually switched back on.
 411
 412         When switching connectable off, it will expire a discoverable
 413         setting with a timeout.
 414
 415         This setting does not affect known devices from Add Device
 416         command. These devices are always allowed to connect.
 417
 418         This command generates a Command Complete event on success or
 419         a Command Status event on failure.
 420
 421         Possible errors:        Busy
 422                                 Not Supported
 423                                 Invalid Parameters
 424                                 Invalid Index
 425
 426
 427 Set Fast Connectable Command
 428 ============================
 429
 430         Command Code:           0x0008
 431         Controller Index:       <controller id>
 432         Command Parameters:     Enable (1 Octet)
 433         Return Parameters:      Current_Settings (4 Octets)
 434
 435         This command is used to set the controller into a connectable
 436         state where the page scan parameters have been set in a way to
 437         favor faster connect times with the expense of higher power
 438         consumption.
 439
 440         The allowed values of the Enable command parameter are 0x00 and
 441         0x01. All other values will return Invalid Parameters.
 442
 443         This command is only available for BR/EDR capable controllers
 444         (e.g. not for single-mode LE ones). It will return Not Supported
 445         otherwise.
 446
 447         This command can be used when the controller is not powered and
 448         all settings will be programmed once powered.
 449
 450         The setting will be remembered during power down/up toggles.
 451
 452         This command generates a Command Complete event on success or
 453         a Command Status event on failure.
 454
 455         Possible errors:        Failed
 456                                 Busy
 457                                 Not Supported
 458                                 Invalid Parameters
 459                                 Invalid Index
 460
 461
 462 Set Bondable Command
 463 ====================
 464
 465         Command Code:           0x0009
 466         Controller Index:       <controller id>
 467         Command Parameters:     Bondable (1 Octet)
 468         Return Parameters:      Current_Settings (4 Octets)
 469
 470         This command is used to set the bondable property of an
 471         controller. The allowed values for the Bondable command
 472         parameter are 0x00 and 0x01. All other values will return
 473         Invalid Parameters.
 474
 475         This command can be used when the controller is not powered and
 476         all settings will be programmed once powered.
 477
 478         Turning bondable on will not automatically switch the controller
 479         into connectable mode. That needs to be done separately.
 480
 481         The setting will be remembered during power down/up toggles.
 482
 483         This command generates a Command Complete event on success or
 484         a Command Status event on failure.
 485
 486         Possible errors:        Invalid Parameters
 487                                 Invalid Index
 488
 489
 490 Set Link Security Command
 491 =========================
 492
 493         Command Code:           0x000A
 494         Controller Index:       <controller id>
 495         Command Parameters:     Link_Security (1 Octet)
 496         Return Parameters:      Current_Settings (4 Octets)
 497
 498         This command is used to either enable or disable link level
 499         security for an controller (also known as Security Mode 3). The
 500         allowed values for the Link_Security command parameter are 0x00
 501         and 0x01. All other values will return Invalid Parameters.
 502
 503         This command is only available for BR/EDR capable controllers
 504         (e.g. not for single-mode LE ones). It will return Not Supported
 505         otherwise.
 506
 507         This command can be used when the controller is not powered and
 508         all settings will be programmed once powered.
 509
 510         This command generates a Command Complete event on success or
 511         a Command Status event on failure.
 512
 513         Possible errors:        Busy
 514                                 Not Supported
 515                                 Invalid Parameters
 516                                 Invalid Index
 517
 518
 519 Set Secure Simple Pairing Command
 520 =================================
 521
 522         Command Code:           0x000B
 523         Controller Index:       <controller id>
 524         Command Parameters:     Secure_Simple_Pairing (1 Octet)
 525         Return Parameters:      Current_Settings (4 Octets)
 526
 527         This command is used to enable/disable Secure Simple Pairing
 528         support for a controller. The allowed values for the
 529         Secure_Simple_Pairing command parameter are 0x00 and 0x01. All
 530         other values will return Invalid Parameters.
 531
 532         This command is only available for BR/EDR capable controllers
 533         supporting the core specification version 2.1 or greater
 534         (e.g. not for single-mode LE controllers or pre-2.1 ones).
 535
 536         This command can be used when the controller is not powered and
 537         all settings will be programmed once powered.
 538
 539         In case the controller does not support Secure Simple Pairing,
 540         the command will fail regardless with Not Supported error.
 541
 542         This command generates a Command Complete event on success or
 543         a Command Status event on failure.
 544
 545         Possible errors:        Busy
 546                                 Not Supported
 547                                 Invalid Parameters
 548                                 Invalid Index
 549
 550 Set High Speed Command
 551 ======================
 552
 553         Command Code:           0x000C
 554         Controller Index:       <controller id>
 555         Command Parameters:     High_Speed (1 Octet)
 556         Return Parameters:      Current_Settings (4 Octets)
 557
 558         This command is used to enable/disable Bluetooth High Speed
 559         support for a controller. The allowed values for the High_Speed
 560         command parameter are 0x00 and 0x01. All other values will
 561         return Invalid Parameters.
 562
 563         This command is only available for BR/EDR capable controllers
 564         (e.g. not for single-mode LE ones).
 565
 566         This command can be used when the controller is not powered and
 567         all settings will be programmed once powered.
 568
 569         To enable High Speed support, it is required that Secure Simple
 570         Pairing support is enabled first. High Speed support is not
 571         possible for connections without Secure Simple Pairing.
 572
 573         When switching Secure Simple Pairing off, the support for High
 574         Speed will be switched off as well. Switching Secure Simple
 575         Pairing back on, will not re-enable High Speed support. That
 576         needs to be done manually.
 577
 578         This command generates a Command Complete event on success or
 579         a Command Status event on failure.
 580
 581         Possible errors:        Not Supported
 582                                 Invalid Parameters
 583                                 Invalid Index
 584
 585
 586 Set Low Energy Command
 587 ======================
 588
 589         Command Code:           0x000D
 590         Controller Index:       <controller id>
 591         Command Parameters:     Low_Energy (1 Octet)
 592         Return Parameters:      Current_Settings (4 Octets)
 593
 594         This command is used to enable/disable Low Energy support for a
 595         controller. The allowed values of the Low_Energy command
 596         parameter are 0x00 and 0x01. All other values will return
 597         Invalid Parameters.
 598
 599         This command is only available for LE capable controllers and
 600         will yield in a Not Supported error otherwise.
 601
 602         This command can be used when the controller is not powered and
 603         all settings will be programmed once powered.
 604
 605         In case the kernel subsystem does not support Low Energy or the
 606         controller does not either, the command will fail regardless.
 607
 608         Disabling LE support will permanently disable and remove all
 609         advertising instances configured with the Add Advertising
 610         command. Advertising Removed events will be issued accordingly.
 611
 612         This command generates a Command Complete event on success or
 613         a Command Status event on failure.
 614
 615         Possible errors:        Busy
 616                                 Not Supported
 617                                 Invalid Parameters
 618                                 Invalid Index
 619
 620
 621 Set Device Class
 622 ================
 623
 624         Command Code:           0x000E
 625         Controller Index:       <controller id>
 626         Command Parameters:     Major_Class (1 Octet)
 627                                 Minor_Class (1 Octet)
 628         Return Parameters:      Class_Of_Device (3 Octets)
 629
 630         This command is used to set the major and minor device class for
 631         BR/EDR capable controllers.
 632
 633         This command will also implicitly disable caching of pending CoD
 634         and EIR updates.
 635
 636         This command is only available for BR/EDR capable controllers
 637         (e.g. not for single-mode LE ones).
 638
 639         This command can be used when the controller is not powered and
 640         all settings will be programmed once powered.
 641
 642         In case the controller is powered off, 0x000000 will be returned
 643         for the class of device parameter. And after power on the new
 644         value will be announced via class of device changed event.
 645
 646         This command generates a Command Complete event on success or
 647         a Command Status event on failure.
 648
 649         Possible errors:        Busy
 650                                 Not Supported
 651                                 Invalid Parameters
 652                                 Invalid Index
 653
 654
 655 Set Local Name Command
 656 ======================
 657
 658         Command Code:           0x000F
 659         Controller Index:       <controller id>
 660         Command Parameters:     Name (249 Octets)
 661                                 Short_Name (11 Octets)
 662         Return Parameters:      Name (249 Octets)
 663                                 Short_Name (11 Octets)
 664
 665         This command is used to set the local name of a controller. The
 666         command parameters also include a short name which will be used
 667         in case the full name doesn't fit within EIR/AD data.
 668
 669         The name parameters need to always end with a null byte (failure
 670         to do so will cause the command to fail).
 671
 672         This command can be used when the controller is not powered and
 673         all settings will be programmed once powered.
 674
 675         The values of name and short name will be remembered when
 676         switching the controller off and back on again. So the name
 677         and short name only have to be set once when a new controller
 678         is found and will stay until removed.
 679
 680         This command generates a Command Complete event on success or
 681         a Command Status event on failure.
 682
 683         Possible errors:        Invalid Parameters
 684                                 Invalid Index
 685
 686
 687 Add UUID Command
 688 ================
 689
 690         Command Code:           0x0010
 691         Controller Index:       <controller id>
 692         Command Parameters:     UUID (16 Octets)
 693                                 SVC_Hint (1 Octet)
 694         Return Parameters:      Class_Of_Device (3 Octets)
 695
 696         This command is used to add a UUID to be published in EIR data.
 697         The accompanied SVC_Hint parameter is used to tell the kernel
 698         whether the service class bits of the Class of Device value need
 699         modifying due to this UUID.
 700
 701         This command can be used when the controller is not powered and
 702         all settings will be programmed once powered.
 703
 704         In case the controller is powered off, 0x000000 will be returned
 705         for the class of device parameter. And after power on the new
 706         value will be announced via class of device changed event.
 707
 708         This command generates a Command Complete event on success or
 709         a Command Status event on failure.
 710
 711         Possible errors:        Busy
 712                                 Invalid Parameters
 713                                 Invalid Index
 714
 715
 716 Remove UUID Command
 717 ===================
 718
 719         Command Code:           0x0011
 720         Controller Index:       <controller id>
 721         Command Parameters:     UUID (16 Octets)
 722         Return Parameters:      Class_Of_Device (3 Octets)
 723
 724         This command is used to remove a UUID previously added using the
 725         Add UUID command.
 726
 727         When the UUID parameter is an empty UUID (16 x 0x00), then all
 728         previously loaded UUIDs will be removed.
 729
 730         This command can be used when the controller is not powered and
 731         all settings will be programmed once powered.
 732
 733         In case the controller is powered off, 0x000000 will be returned
 734         for the class of device parameter. And after power on the new
 735         value will be announced via class of device changed event.
 736
 737         This command generates a Command Complete event on success or
 738         a Command Status event on failure.
 739
 740         Possible errors:        Busy
 741                                 Invalid Parameters
 742                                 Invalid Index
 743
 744
 745 Load Link Keys Command
 746 ======================
 747
 748         Command Code:           0x0012
 749         Controller Index:       <controller id>
 750         Command Parameters:     Debug_Keys (1 Octet)
 751                                 Key_Count (2 Octets)
 752                                 Key1 {
 753                                         Address (6 Octets)
 754                                         Address_Type (1 Octet)
 755                                         Key_Type (1 Octet)
 756                                         Value (16 Octets)
 757                                         PIN_Length (1 Octet)
 758                                 }
 759                                 Key2 { }
 760                                 ...
 761         Return Parameters:
 762
 763         This command is used to feed the kernel with currently known
 764         link keys. The command does not need to be called again upon the
 765         receipt of New Link Key events since the kernel updates its list
 766         automatically.
 767
 768         The Debug_Keys parameter is used to tell the kernel whether to
 769         accept the usage of debug keys or not. The allowed values for
 770         this parameter are 0x00 and 0x01. All other values will return
 771         an Invalid Parameters response.
 772
 773         Usage of the Debug_Keys parameter is deprecated and has been
 774         replaced with the Set Debug Keys command. When setting the
 775         Debug_Keys option via Load Link Keys command it has the same
 776         affect as setting it via Set Debug Keys and applies to all
 777         keys in the system.
 778
 779         Possible values for the Address_Type parameter:
 780                 0       BR/EDR
 781                 1       Reserved (not in use)
 782                 2       Reserved (not in use)
 783
 784         Public and random LE addresses are not valid and will be rejected.
 785
 786         Currently defined Key_Type values are:
 787
 788                 0x00    Combination key
 789                 0x01    Local Unit key
 790                 0x02    Remote Unit key
 791                 0x03    Debug Combination key
 792                 0x04    Unauthenticated Combination key from P-192
 793                 0x05    Authenticated Combination key from P-192
 794                 0x06    Changed Combination key
 795                 0x07    Unauthenticated Combination key from P-256
 796                 0x08    Authenticated Combination key from P-256
 797
 798         This command can be used when the controller is not powered.
 799
 800         This command generates a Command Complete event on success or
 801         a Command Status event on failure.
 802
 803         Possible errors:        Invalid Parameters
 804                                 Invalid Index
 805
 806
 807 Load Long Term Keys Command
 808 ===========================
 809
 810         Command Code:           0x0013
 811         Controller Index:       <controller id>
 812         Command Parameters:     Key_Count (2 Octets)
 813                                 Key1 {
 814                                         Address (6 Octets)
 815                                         Address_Type (1 Octet)
 816                                         Key_Type (1 Octet)
 817                                         Master (1 Octet)
 818                                         Encryption_Size (1 Octet)
 819                                         Encryption_Diversifier (2 Octets)
 820                                         Random_Number (8 Octets)
 821                                         Value (16 Octets)
 822                                 }
 823                                 Key2 {  }
 824                                 ...
 825         Return Parameters:
 826
 827         This command is used to feed the kernel with currently known
 828         (SMP) Long Term Keys. The command does not need to be called
 829         again upon the receipt of New Long Term Key events since the
 830         kernel updates its list automatically.
 831
 832         Possible values for the Address_Type parameter:
 833                 0       Reserved (not in use)
 834                 1       LE Public
 835                 2       LE Random
 836
 837         The provided Address and Address_Type are the identity of
 838         a device. So either its public address or static random address.
 839
 840         Unresolvable random addresses and resolvable random addresses are
 841         not valid and will be rejected.
 842
 843         Currently defined Key_Type values are:
 844
 845                 0x00    Unauthenticated key
 846                 0x01    Authenticated key
 847
 848         This command can be used when the controller is not powered.
 849
 850         This command generates a Command Complete event on success or
 851         a Command Status event on failure.
 852
 853         Possible errors:        Invalid Parameters
 854                                 Invalid Index
 855
 856
 857 Disconnect Command
 858 ==================
 859
 860         Command Code:           0x0014
 861         Controller Index:       <controller id>
 862         Command Parameters:     Address (6 Octets)
 863                                 Address_Type (1 Octet)
 864         Return Parameters:      Address (6 Octets)
 865                                 Address_Type (1 Octet)
 866
 867         This command is used to force the disconnection of a currently
 868         connected device.
 869
 870         Possible values for the Address_Type parameter:
 871                 0       BR/EDR
 872                 1       LE Public
 873                 2       LE Random
 874
 875         This command can only be used when the controller is powered.
 876
 877         This command generates a Command Complete event on success
 878         or failure.
 879
 880         Possible errors:        Not Connected
 881                                 Busy
 882                                 Invalid Parameters
 883                                 Not Powered
 884                                 Invalid Index
 885
 886
 887 Get Connections Command
 888 =======================
 889
 890         Command Code:           0x0015
 891         Controller Index:       <controller id>
 892         Command Parameters:
 893         Return Parameters:      Connection_Count (2 Octets)
 894                                 Address1 {
 895                                         Address (6 Octets)
 896                                         Address_Type (1 Octet)
 897                                 }
 898                                 Address2 { }
 899                                 ...
 900
 901         This command is used to retrieve a list of currently connected
 902         devices.
 903
 904         Possible values for the Address_Type parameter:
 905                 0       BR/EDR
 906                 1       LE Public
 907                 2       LE Random
 908
 909         For devices using resolvable random addresses with a known
 910         identity resolving key, the Address and Address_Type will
 911         contain the identity information.
 912
 913         This command can only be used when the controller is powered.
 914
 915         This command generates a Command Complete event on success or
 916         a Command Status event on failure.
 917
 918         Possible errors:        Invalid Parameters
 919                                 Not Powered
 920                                 Invalid Index
 921
 922
 923 PIN Code Reply Command
 924 =======================
 925
 926         Command Code:           0x0016
 927         Controller Index:       <controller id>
 928         Command Parameters:     Address (6 Octets)
 929                                 Address_Type (1 Octet)
 930                                 PIN_Length (1 Octet)
 931                                 PIN_Code (16 Octets)
 932         Return Parameters:      Address (6 Octets)
 933                                 Address_Type (1 Octet)
 934
 935         This command is used to respond to a PIN Code request event.
 936
 937         Possible values for the Address_Type parameter:
 938                 0       BR/EDR
 939                 1       LE Public
 940                 2       LE Random
 941
 942         This command can only be used when the controller is powered.
 943
 944         This command generates a Command Complete event on success
 945         or failure.
 946
 947         Possible errors:        Not Connected
 948                                 Invalid Parameters
 949                                 Not Powered
 950                                 Invalid Index
 951
 952
 953 PIN Code Negative Reply Command
 954 ===============================
 955
 956         Command Code:           0x0017
 957         Controller Index:       <controller id>
 958         Command Parameters:     Address (6 Octets)
 959                                 Address_Type (1 Octet)
 960         Return Parameters:      Address (6 Octets)
 961                                 Address_Type (1 Octet)
 962
 963         This command is used to return a negative response to a PIN Code
 964         Request event.
 965
 966         Possible values for the Address_Type parameter:
 967                 0       BR/EDR
 968                 1       LE Public
 969                 2       LE Random
 970
 971         This command can only be used when the controller is powered.
 972
 973         This command generates a Command Complete event on success
 974         or failure.
 975
 976         Possible errors:        Not Connected
 977                                 Invalid Parameters
 978                                 Not Powered
 979                                 Invalid Index
 980
 981
 982 Set IO Capability Command
 983 =========================
 984
 985         Command Code:           0x0018
 986         Controller Index:       <controller id>
 987         Command Parameters:     IO_Capability (1 Octet)
 988         Return Parameters:
 989
 990         This command is used to set the IO Capability used for pairing.
 991         The command accepts both SSP and SMP values.
 992
 993         Possible values for the IO_Capability parameter:
 994                 0       DisplayOnly
 995                 1       DisplayYesNo
 996                 2       KeyboardOnly
 997                 3       NoInputNoOutput
 998                 4       KeyboardDisplay
 999
1000         Passing a value 4 (KeyboardDisplay) will cause the kernel to
1001         convert it to 1 (DisplayYesNo) in the case of a BR/EDR
1002         connection (as KeyboardDisplay is specific to SMP).
1003
1004         This command can be used when the controller is not powered.
1005
1006         This command generates a Command Complete event on success or
1007         a Command Status event on failure.
1008
1009         Possible errors:        Invalid Parameters
1010                                 Invalid Index
1011
1012
1013 Pair Device Command
1014 ===================
1015
1016         Command Code:           0x0019
1017         Controller Index:       <controller id>
1018         Command Parameters:     Address (6 Octets)
1019                                 Address_Type (1 Octet)
1020                                 IO_Capability (1 Octet)
1021         Return Parameters:      Address (6 Octets)
1022                                 Address_Type (1 Octet)
1023
1024         This command is used to trigger pairing with a remote device.
1025         The IO_Capability command parameter is used to temporarily (for
1026         this pairing event only) override the global IO Capability (set
1027         using the Set IO Capability command).
1028
1029         Possible values for the Address_Type parameter:
1030                 0       BR/EDR
1031                 1       LE Public
1032                 2       LE Random
1033
1034         Possible values for the IO_Capability parameter:
1035                 0       DisplayOnly
1036                 1       DisplayYesNo
1037                 2       KeyboardOnly
1038                 3       NoInputNoOutput
1039                 4       KeyboardDisplay
1040
1041         Passing a value 4 (KeyboardDisplay) will cause the kernel to
1042         convert it to 1 (DisplayYesNo) in the case of a BR/EDR
1043         connection (as KeyboardDisplay is specific to SMP).
1044
1045         The Address and Address_Type of the return parameters will
1046         return the identity address if known. In case of resolvable
1047         random address given as command parameters and the remote
1048         provides an identity resolving key, the return parameters
1049         will provide the resolved address.
1050
1051         To allow tracking of which resolvable random address changed
1052         into which identity address, the New Identity Resolving Key
1053         event will be sent before receiving Command Complete event
1054         for this command.
1055
1056         This command can only be used when the controller is powered.
1057
1058         This command generates a Command Complete event on success
1059         or failure.
1060
1061         Reject status is used when requested transport is not enabled.
1062
1063         Not Supported status is used if controller is not capable with
1064         requested transport.
1065
1066         Possible errors:        Rejected
1067                                 Not Supported
1068                                 Connect Failed
1069                                 Busy
1070                                 Invalid Parameters
1071                                 Not Powered
1072                                 Invalid Index
1073                                 Already Paired
1074
1075
1076 Cancel Pair Device Command
1077 ==========================
1078
1079         Command Code:           0x001A
1080         Controller Index:       <controller id>
1081         Command Parameters:     Address (6 Octets)
1082                                 Address_Type (1 Octet)
1083         Return Parameters:      Address (6 Octets)
1084                                 Address_Type (1 Octet)
1085
1086         The Address and Address_Type parameters should match what was
1087         given to a preceding Pair Device command.
1088
1089         Possible values for the Address_Type parameter:
1090                 0       BR/EDR
1091                 1       LE Public
1092                 2       LE Random
1093
1094         This command can only be used when the controller is powered.
1095
1096         This command generates a Command Complete event on success
1097         or failure.
1098
1099         Possible errors:        Invalid Parameters
1100                                 Not Powered
1101                                 Invalid Index
1102
1103
1104 Unpair Device Command
1105 =====================
1106
1107         Command Code:           0x001B
1108         Controller Index:       <controller id>
1109         Command Parameters:     Address (6 Octets)
1110                                 Address_Type (1 Octet)
1111                                 Disconnect (1 Octet)
1112         Return Parameters:      Address (6 Octets)
1113                                 Address_Type (1 Octet)
1114
1115         Removes all keys associated with the remote device.
1116
1117         Possible values for the Address_Type parameter:
1118                 0       BR/EDR
1119                 1       LE Public
1120                 2       LE Random
1121
1122         The Disconnect parameter tells the kernel whether to forcefully
1123         disconnect any existing connections to the device. It should in
1124         practice always be 1 except for some special GAP qualification
1125         test-cases where a key removal without disconnecting is needed.
1126
1127         When unpairing a device its link key, long term key and if
1128         provided identity resolving key will be purged.
1129
1130         For devices using resolvable random addresses where the identity
1131         resolving key was available, after this command they will now no
1132         longer be resolved. The device will essentially become private
1133         again.
1134
1135         This command can only be used when the controller is powered.
1136
1137         This command generates a Command Complete event on success
1138         or failure.
1139
1140         Possible errors:        Not Paired
1141                                 Invalid Parameters
1142                                 Not Powered
1143                                 Invalid Index
1144
1145
1146 User Confirmation Reply Command
1147 ===============================
1148
1149         Command Code:           0x001C
1150         Controller Index:       <controller id>
1151         Command Parameters:     Address (6 Octets)
1152                                 Address_Type (1 Octet)
1153         Return Parameters:      Address (6 Octets)
1154                                 Address_Type (1 Octet)
1155
1156         This command is used to respond to a User Confirmation Request
1157         event.
1158
1159         Possible values for the Address_Type parameter:
1160                 0       BR/EDR
1161                 1       LE Public
1162                 2       LE Random
1163
1164         This command can only be used when the controller is powered.
1165
1166         This command generates a Command Complete event on success
1167         or failure.
1168
1169         Possible errors:        Not Connected
1170                                 Invalid Parameters
1171                                 Not Powered
1172                                 Invalid Index
1173
1174
1175 User Confirmation Negative Reply Command
1176 ========================================
1177
1178         Command Code:           0x001D
1179         Controller Index:       <controller id>
1180         Command Parameters:     Address (6 Octets)
1181                                 Address_Type (1 Octet)
1182         Return Parameters:      Address (6 Octets)
1183                                 Address_Type (1 Octet)
1184
1185         This command is used to return a negative response to a User
1186         Confirmation Request event.
1187
1188         Possible values for the Address_Type parameter:
1189                 0       BR/EDR
1190                 1       LE Public
1191                 2       LE Random
1192
1193         This command can only be used when the controller is powered.
1194
1195         This command generates a Command Complete event on success
1196         or failure.
1197
1198         Possible errors:        Not Connected
1199                                 Invalid Parameters
1200                                 Not Powered
1201                                 Invalid Index
1202
1203
1204 User Passkey Reply Command
1205 ==========================
1206
1207         Command Code:           0x001E
1208         Controller Index:       <controller id>
1209         Command Parameters:     Address (6 Octets)
1210                                 Address_Type (1 Octet)
1211                                 Passkey (4 Octets)
1212         Return Parameters:      Address (6 Octets)
1213                                 Address_Type (1 Octet)
1214
1215         This command is used to respond to a User Confirmation Passkey
1216         Request event.
1217
1218         Possible values for the Address_Type parameter:
1219                 0       BR/EDR
1220                 1       LE Public
1221                 2       LE Random
1222
1223         This command can only be used when the controller is powered.
1224
1225         This command generates a Command Complete event on success
1226         or failure.
1227
1228         Possible errors:        Not Connected
1229                                 Invalid Parameters
1230                                 Not Powered
1231                                 Invalid Index
1232
1233
1234 User Passkey Negative Reply Command
1235 ===================================
1236
1237         Command Code:           0x001F
1238         Controller Index:       <controller id>
1239         Command Parameters:     Address (6 Octets)
1240                                 Address_Type (1 Octet)
1241         Return Parameters:      Address (6 Octets)
1242                                 Address_Type (1 Octet)
1243
1244         This command is used to return a negative response to a User
1245         Passkey Request event.
1246
1247         Possible values for the Address_Type parameter:
1248                 0       BR/EDR
1249                 1       LE Public
1250                 2       LE Random
1251
1252         This command can only be used when the controller is powered.
1253
1254         This command generates a Command Complete event on success
1255         or failure.
1256
1257         Possible errors:        Not Connected
1258                                 Invalid Parameters
1259                                 Not Powered
1260                                 Invalid Index
1261
1262
1263 Read Local Out Of Band Data Command
1264 ===================================
1265
1266         Command Code:           0x0020
1267         Controller Index:       <controller id>
1268         Command Parameters:
1269         Return Parameters:      Hash_192 (16 Octets)
1270                                 Randomizer_192 (16 Octets)
1271                                 Hash_256 (16 Octets, Optional)
1272                                 Randomizer_256 (16 Octets, Optional)
1273
1274         This command is used to read the local Out of Band data.
1275
1276         This command can only be used when the controller is powered.
1277
1278         If Secure Connections support is enabled, then this command
1279         will return P-192 versions of hash and randomizer as well as
1280         P-256 versions of both.
1281
1282         Values returned by this command become invalid when the controller
1283         is powered down. After each power-cycle it is required to call
1284         this command again to get updated values.
1285
1286         This command generates a Command Complete event on success or
1287         a Command Status event on failure.
1288
1289         Possible errors:        Not Supported
1290                                 Busy
1291                                 Invalid Parameters
1292                                 Not Powered
1293                                 Invalid Index
1294
1295
1296 Add Remote Out Of Band Data Command
1297 ===================================
1298
1299         Command Code:           0x0021
1300         Controller Index:       <controller id>
1301         Command Parameters:     Address (6 Octets)
1302                                 Address_Type (1 Octet)
1303                                 Hash_192 (16 Octets)
1304                                 Randomizer_192 (16 Octets)
1305                                 Hash_256 (16 Octets, Optional)
1306                                 Randomizer_256 (16 Octets, Optional)
1307         Return Parameters:      Address (6 Octets)
1308                                 Address_Type (1 Octet)
1309
1310         This command is used to provide Out of Band data for a remote
1311         device.
1312
1313         Possible values for the Address_Type parameter:
1314                 0       BR/EDR
1315                 1       LE Public
1316                 2       LE Random
1317
1318         Provided Out Of Band data is persistent over power down/up toggles.
1319
1320         This command also accept optional P-256 versions of hash and
1321         randomizer. If they are not provided, then they are set to
1322         zero value.
1323
1324         The P-256 versions of both can also be provided when the
1325         support for Secure Connections is not enabled. However in
1326         that case they will never be used.
1327
1328         To only provide the P-256 versions of hash and randomizer,
1329         it is valid to leave both P-192 fields as zero values. If
1330         Secure Connections is disabled, then of course this is the
1331         same as not providing any data at all.
1332
1333         When providing data for remote LE devices, then the Hash_192 and
1334         and Randomizer_192 fields are not used and shell be set to zero.
1335
1336         The Hash_256 and Randomizer_256 fields can be used for LE secure
1337         connections Out Of Band data. If only LE secure connections data
1338         is provided the Hash_P192 and Randomizer_P192 fields can be set
1339         to zero. Currently there is no support for providing the Security
1340         Manager TK Value for LE legacy pairing.
1341
1342         If Secure Connections Only mode has been enabled, then providing
1343         Hash_P192 and Randomizer_P192 is not allowed. They are required
1344         to be set to zero values.
1345
1346         This command can be used when the controller is not powered and
1347         all settings will be programmed once powered.
1348
1349         This command generates a Command Complete event on success
1350         or failure.
1351
1352         Possible errors:        Failed
1353                                 Invalid Parameters
1354                                 Not Powered
1355                                 Invalid Index
1356
1357
1358 Remove Remote Out Of Band Data Command
1359 ======================================
1360
1361         Command Code:           0x0022
1362         Controller Index:       <controller id>
1363         Command Parameters:     Address (6 Octets)
1364                                 Address_Type (1 Octet)
1365         Return Parameters:      Address (6 Octets)
1366                                 Address_Type (1 Octet)
1367
1368         This command is used to remove data added using the Add Remote
1369         Out Of Band Data command.
1370
1371         Possible values for the Address_Type parameter:
1372                 0       BR/EDR
1373                 1       LE Public
1374                 2       LE Random
1375
1376         When the Address parameter is 00:00:00:00:00:00, then all
1377         previously added data will be removed.
1378
1379         This command can be used when the controller is not powered and
1380         all settings will be programmed once powered.
1381
1382         This command generates a Command Complete event on success
1383         or failure.
1384
1385         Possible errors:        Invalid Parameters
1386                                 Not Powered
1387                                 Invalid Index
1388
1389
1390 Start Discovery Command
1391 =======================
1392
1393         Command Code:           0x0023
1394         Controller Index:       <controller id>
1395         Command Parameters:     Address_Type (1 Octet)
1396         Return Parameters:      Address_Type (1 Octet)
1397
1398         This command is used to start the process of discovering remote
1399         devices. A Device Found event will be sent for each discovered
1400         device.
1401
1402         Possible values for the Address_Type parameter are a bit-wise or
1403         of the following bits:
1404
1405                 0       BR/EDR
1406                 1       LE Public
1407                 2       LE Random
1408
1409         By combining these e.g. the following values are possible:
1410
1411                 1       BR/EDR
1412                 6       LE (public & random)
1413                 7       BR/EDR/LE (interleaved discovery)
1414
1415         This command can only be used when the controller is powered.
1416
1417         This command generates a Command Complete event on success
1418         or failure.
1419
1420         Possible errors:        Busy
1421                                 Not Supported
1422                                 Invalid Parameters
1423                                 Not Powered
1424                                 Invalid Index
1425
1426
1427 Stop Discovery Command
1428 ======================
1429
1430         Command Code:           0x0024
1431         Controller Index:       <controller id>
1432         Command Parameters:     Address_Type (1 Octet)
1433         Return Parameters:      Address_Type (1 Octet)
1434
1435         This command is used to stop the discovery process started using
1436         the Start Discovery command.
1437
1438         This command can only be used when the controller is powered.
1439
1440         This command generates a Command Complete event on success
1441         or failure.
1442
1443         Possible errors:        Rejected
1444                                 Invalid Parameters
1445                                 Invalid Index
1446
1447
1448 Confirm Name Command
1449 ====================
1450
1451         Command Code:           0x0025
1452         Controller Index:       <controller id>
1453         Command Parameters:     Address (6 Octets)
1454                                 Address_Type (1 Octet)
1455                                 Name_Known (1 Octet)
1456         Return Parameters:      Address (6 Octets)
1457                                 Address_Type (1 Octet)
1458
1459         This command is only valid during device discovery and is
1460         expected for each Device Found event with the Confirm Name
1461         flag set.
1462
1463         Possible values for the Address_Type parameter:
1464                 0       BR/EDR
1465                 1       LE Public
1466                 2       LE Random
1467
1468         The Name_Known parameter should be set to 0x01 if user space
1469         knows the name for the device and 0x00 if it doesn't. If set to
1470         0x00 the kernel will perform a name resolving procedure for the
1471         device in question.
1472
1473         This command can only be used when the controller is powered.
1474
1475         This command generates a Command Complete event on success
1476         or failure.
1477
1478         Possible errors:        Failed
1479                                 Invalid Parameters
1480                                 Invalid Index
1481
1482
1483 Block Device Command
1484 ====================
1485
1486         Command Code:           0x0026
1487         Controller Index:       <controller id>
1488         Command Parameters:     Address (6 Octets)
1489                                 Address_Type (1 Octet)
1490         Return Parameters:      Address (6 Octets)
1491                                 Address_Type (1 Octet)
1492
1493         This command is used to add a device to the list of devices
1494         which should be blocked from being connected to the local
1495         controller.
1496
1497         Possible values for the Address_Type parameter:
1498                 0       BR/EDR
1499                 1       LE Public
1500                 2       LE Random
1501
1502         For Low Energy devices, the blocking of a device takes precedence
1503         over auto-connection actions provided by Add Device. Blocked
1504         devices will not be auto-connected or even reported when found
1505         during background scanning. If the controller is connectable
1506         direct advertising from blocked devices will also be ignored.
1507
1508         Connections created from advertising of the controller will
1509         be dropped if the device is blocked.
1510
1511         This command can be used when the controller is not powered.
1512
1513         This command generates a Command Complete event on success
1514         or failure.
1515
1516         Possible errors:        Failed
1517                                 Invalid Parameters
1518                                 Invalid Index
1519
1520
1521 Unblock Device Command
1522 ======================
1523
1524         Command Code:           0x0027
1525         Controller Index:       <controller id>
1526         Command Parameters:     Address (6 Octets)
1527                                 Address_Type (1 Octet)
1528         Return Parameters:      Address (6 Octets)
1529                                 Address_Type (1 Octet)
1530
1531         This command is used to remove a device from the list of blocked
1532         devices (where it was added to using the Block Device command).
1533
1534         Possible values for the Address_Type parameter:
1535                 0       BR/EDR
1536                 1       LE Public
1537                 2       LE Random
1538
1539         When the Address parameter is 00:00:00:00:00:00, then all
1540         previously blocked devices will be unblocked.
1541
1542         This command can be used when the controller is not powered.
1543
1544         This command generates a Command Complete event on success
1545         or failure.
1546
1547         Possible errors:        Invalid Parameters
1548                                 Invalid Index
1549
1550
1551 Set Device ID Command
1552 =====================
1553
1554         Command Code:           0x0028
1555         Controller Index:       <controller id>
1556         Command Parameters:     Source (2 Octets)
1557                                 Vendor (2 Octets)
1558                                 Product (2 Octets)
1559                                 Version (2 Octets)
1560         Return Parameters:
1561
1562         This command can be used when the controller is not powered and
1563         all settings will be programmed once powered.
1564
1565         The Source parameter selects the organization that assigned the
1566         Vendor parameter:
1567
1568                 0x0000  Disable Device ID
1569                 0x0001  Bluetooth SIG
1570                 0x0002  USB Implementer's Forum
1571
1572         The information is put into the EIR data. If the controller does
1573         not support EIR or if SSP is disabled, this command will still
1574         succeed. The information is stored for later use and will survive
1575         toggling SSP on and off.
1576
1577         This command generates a Command Complete event on success or
1578         a Command Status event on failure.
1579
1580         Possible errors:        Invalid Parameters
1581                                 Invalid Index
1582
1583
1584 Set Advertising Command
1585 =======================
1586
1587         Command Code:           0x0029
1588         Controller Index:       <controller id>
1589         Command Parameters:     Advertising (1 Octet)
1590         Return Parameters:      Current_Settings (4 Octets)
1591
1592         This command is used to enable LE advertising on a controller
1593         that supports it. The allowed values for the Advertising command
1594         parameter are 0x00, 0x01 and 0x02. All other values will return
1595         Invalid Parameters.
1596
1597         The value 0x00 disables advertising, the value 0x01 enables
1598         advertising with considering of connectable setting and the
1599         value 0x02 enables advertising in connectable mode.
1600
1601         Using value 0x01 means that when connectable setting is disabled,
1602         the advertising happens with undirected non-connectable advertising
1603         packets and a non-resolvable random address is used. If connectable
1604         setting is enabled, then undirected connectable advertising packets
1605         and the identity address or resolvable private address are used.
1606
1607         LE Devices configured via Add Device command with Action 0x01
1608         have no effect when using Advertising value 0x01 since only the
1609         connectable setting is taken into account.
1610
1611         To utilize undirected connectable advertising without changing the
1612         connectable setting, the value 0x02 can be utilized. It makes the
1613         device connectable via LE without the requirement for being
1614         connectable on BR/EDR (and/or LE).
1615
1616         The value 0x02 should be the preferred mode of operation when
1617         implementing peripheral mode.
1618
1619         Using this command will temporarily deactivate any configuration
1620         made by the Add Advertising command. This command takes precedence.
1621         Once a Set Advertising command with value 0x00 is issued any
1622         previously made configurations via Add/Remove Advertising, including
1623         such changes made while Set Advertising was active, will be re-
1624         enabled.
1625
1626         A pre-requisite is that LE is already enabled, otherwise this
1627         command will return a "rejected" response.
1628
1629         This command generates a Command Complete event on success or a
1630         Command Status event on failure.
1631
1632         Possible errors:        Busy
1633                                 Rejected
1634                                 Not Supported
1635                                 Invalid Parameters
1636                                 Invalid Index
1637
1638
1639 Set BR/EDR Command
1640 ==================
1641
1642         Command Code:           0x002A
1643         Controller Index:       <controller id>
1644         Command Parameters:     BR/EDR (1 Octet)
1645         Return Parameters:      Current_Settings (4 Octets)
1646
1647         This command is used to enable or disable BR/EDR support
1648         on a dual-mode controller. The allowed values for the Advertising
1649         command parameter are 0x00 and 0x01. All other values will
1650         return Invalid Parameters.
1651
1652         A pre-requisite is that LE is already enabled, otherwise
1653         this command will return a "rejected" response. Enabling BR/EDR
1654         can be done both when powered on and powered off, however
1655         disabling it can only be done when powered off (otherwise the
1656         command will again return "rejected"). Disabling BR/EDR will
1657         automatically disable all other BR/EDR related settings.
1658
1659         This command generates a Command Complete event on success or a
1660         Command Status event on failure.
1661
1662         Possible errors:        Busy
1663                                 Rejected
1664                                 Not Supported
1665                                 Invalid Parameters
1666                                 Invalid Index
1667
1668
1669 Set Static Address Command
1670 ==========================
1671
1672         Command Code:           0x002B
1673         Controller Index:       <controller id>
1674         Command Parameters:     Address (6 Octets)
1675         Return Parameters:      Current_Settings (4 Octets)
1676
1677         This command allows for setting the static random address. It is
1678         only supported on controllers with LE support. The static random
1679         address is suppose to be valid for the lifetime of the
1680         controller or at least until the next power cycle. To ensure
1681         such behavior, setting of the address is limited to when the
1682         controller is powered off.
1683
1684         The special BDADDR_ANY address (00:00:00:00:00:00) can be used
1685         to disable the static address.
1686
1687         When a controller has a public address (which is required for
1688         all dual-mode controllers), this address is not used. If a dual-mode
1689         controller is configured as Low Energy only devices (BR/EDR has
1690         been switched off), then the static address is used. Only when
1691         the controller information reports BDADDR_ANY (00:00:00:00:00:00),
1692         it is required to configure a static address first.
1693
1694         If privacy mode is enabled and the controller is single mode
1695         LE only without a public address, the static random address is
1696         used as identity address.
1697
1698         The Static Address flag from the current settings can also be used
1699         to determine if the configured static address is in use or not.
1700
1701         This command generates a Command Complete event on success or a
1702         Command Status event on failure.
1703
1704         Possible errors:        Rejected
1705                                 Not Supported
1706                                 Invalid Parameters
1707                                 Invalid Index
1708
1709
1710 Set Scan Parameters Command
1711 ===========================
1712
1713         Command Code:           0x002C
1714         Controller Index:       <controller id>
1715         Command Parameters:     Interval (2 Octets)
1716                                 Window (2 Octets)
1717         Return Parameters:
1718
1719         This command allows for setting the Low Energy scan parameters
1720         used for connection establishment and passive scanning. It is
1721         only supported on controllers with LE support.
1722
1723         This command generates a Command Complete event on success or a
1724         Command Status event on failure.
1725
1726         Possible errors:        Rejected
1727                                 Not Supported
1728                                 Invalid Parameters
1729                                 Invalid Index
1730
1731
1732 Set Secure Connections Command
1733 ==============================
1734
1735         Command Code:           0x002D
1736         Controller Index:       <controller id>
1737         Command Parameters:     Secure_Connections (1 Octet)
1738         Return Parameters:      Current_Settings (4 Octets)
1739
1740         This command is used to enable/disable Secure Connections
1741         support for a controller. The allowed values for the
1742         Secure_Connections command parameter are 0x00, 0x01 and 0x02.
1743         All other values will return Invalid Parameters.
1744
1745         The value 0x00 disables Secure Connections, the value 0x01
1746         enables Secure Connections and the value 0x02 enables Secure
1747         Connections Only mode.
1748
1749         This command is only available for LE capable controllers as
1750         well as controllers supporting the core specification version
1751         4.1 or greater.
1752
1753         This command can be used when the controller is not powered and
1754         all settings will be programmed once powered.
1755
1756         In case the controller does not support Secure Connections
1757         the command will fail regardless with Not Supported error.
1758
1759         This command generates a Command Complete event on success or
1760         a Command Status event on failure.
1761
1762         Possible errors:        Busy
1763                                 Not Supported
1764                                 Invalid Parameters
1765                                 Invalid Index
1766
1767
1768 Set Debug Keys Command
1769 ======================
1770
1771         Command Code:           0x002E
1772         Controller Index:       <controller id>
1773         Command Parameters:     Debug_Keys (1 Octet)
1774         Return Parameters:      Current_Settings (4 Octets)
1775
1776         This command is used to tell the kernel whether to accept the
1777         usage of debug keys or not. The allowed values for this parameter
1778         are 0x00, 0x01 and 0x02. All other values will return an Invalid
1779         Parameters response.
1780
1781         With a value of 0x00 any generated debug key will be discarded
1782         as soon as the connection terminates.
1783
1784         With a value of 0x01 generated debug keys will be kept and can
1785         be used for future connections. However debug keys are always
1786         marked as non persistent and should not be stored. This means
1787         a reboot or changing the value back to 0x00 will delete them.
1788
1789         With a value of 0x02 generated debug keys will be kept and can
1790         be used for future connections. This has the same affect as
1791         with value 0x01. However in addition this value will also
1792         enter the controller mode to generate debug keys for each
1793         new pairing. Changing the value back to 0x01 or 0x00 will
1794         disable the controller mode for generating debug keys.
1795
1796         This command generates a Command Complete event on success or
1797         a Command Status event on failure.
1798
1799         Possible errors:        Busy
1800                                 Not Supported
1801                                 Invalid Parameters
1802                                 Invalid Index
1803
1804
1805 Set Privacy Command
1806 ===================
1807
1808         Command Code:           0x002F
1809         Controller Index:       <controller id>
1810         Command Parameters:     Privacy (1 Octet)
1811                                 Identity_Resolving_Key (16 Octets)
1812         Return Parameters:      Current_Settings (4 Octets)
1813
1814         This command is used to enable Low Energy Privacy feature using
1815         resolvable private addresses.
1816
1817         The value 0x00 disables privacy mode, the values 0x01 and 0x02
1818         enable privacy mode.
1819
1820         With value 0x01 the kernel will always use the privacy mode. This
1821         means resolvable private address is used when the controller is
1822         discoverable and also when pairing is initiated.
1823
1824         With value 0x02 the kernel will use privacy mode with resolvable
1825         private address. In case the controller is bondable and
1826         discoverable the identity address is used. Also when pairing is
1827         initiated, the connection will be established with the identity
1828         address.
1829
1830         Exposing the identity address when bondable and discoverable or
1831         during initiated pairing can be a privacy issue. For dual-mode
1832         controllers this can be neglected since its public address will
1833         be exposed over BR/EDR anyway. The benefit of exposing the
1834         identity address for pairing purposes is that it makes matching
1835         up devices with dual-mode topology during device discovery now
1836         possible.
1837
1838         If the privacy value 0x02 is used, then also the GATT database
1839         should expose the Privacy Characteristic so that remote devices
1840         can determine if the privacy feature is in use or not.
1841
1842         When the controller has a public address (mandatory for dual-mode
1843         controllers) it is used as identity address. In case the controller
1844         is single mode LE only without a public address, it is required
1845         to configure a static random address first. The privacy mode can
1846         only be enabled when an identity address is available.
1847
1848         The Identity_Resolving_Key is the local key assigned for the local
1849         resolvable private address.
1850
1851         Possible errors:        Busy
1852                                 Not Supported
1853                                 Invalid Parameters
1854                                 Invalid Index
1855
1856
1857 Load Identity Resolving Keys Command
1858 ====================================
1859
1860         Command Code:           0x0030
1861         Controller Index:       <controller id>
1862         Command Parameters:     Key_Count (2 Octets)
1863                                 Key1 {
1864                                         Address (6 Octets)
1865                                         Address_Type (1 Octet)
1866                                         Value (16 Octets)
1867                                 }
1868                                 Key2 {  }
1869                                 ...
1870         Return Parameters:
1871
1872         This command is used to feed the kernel with currently known
1873         identity resolving keys. The command does not need to be called
1874         again upon the receipt of New Identity Resolving Key events
1875         since the kernel updates its list automatically.
1876
1877         Possible values for the Address_Type parameter:
1878                 0       Reserved (not in use)
1879                 1       LE Public
1880                 2       LE Random
1881
1882         The provided Address and Address_Type are the identity of
1883         a device. So either its public address or static random address.
1884
1885         Unresolvable random addresses and resolvable random addresses are
1886         not valid and will be rejected.
1887
1888         This command can be used when the controller is not powered.
1889
1890         This command generates a Command Complete event on success or
1891         a Command Status event on failure.
1892
1893         Possible errors:        Invalid Parameters
1894                                 Invalid Index
1895
1896 #ifdef __TIZEN_PATCH__
1897 Generate Identity Resolving Key Command
1898 =======================================
1899
1900         Command Code:           0x00F6
1901         Controller Index:       <controller id>
1902         Command Parameters:
1903         Return Parameters:
1904
1905         This command is used to generate identity resolving key for the
1906         local device, which will be used at the time of pairing for key
1907         distribution and to     generate resolvable private address for local device.
1908
1909         This command generates a Command Complete event on success
1910         or a Command Status event on failure.
1911
1912         Possible errors:        Failed
1913                                 Invalid Index
1914
1915 Generate Resolvable Private Address Command
1916 =======================================
1917
1918         Command Code:           0x00F5
1919         Controller Index:       <controller id>
1920         Command Parameters:
1921         Return Parameters:      Resolvable Private Address (6 Octets)
1922
1923         This command is used to generate resolvable private address for the
1924         local device when LE privacy is supported and device is having its IRK.
1925
1926         This command returns generated private address which is resolvable
1927         by remote device on success.
1928
1929         This command generates a Command Complete event on success
1930         or a Command Status event on failure.
1931
1932         Possible errors:        Failed
1933                                 Invalid Index
1934
1935 Set Random Address Command
1936 ==========================
1937
1938         Command Code:           0x00F4
1939         Controller Index:       <controller id>
1940         Command Parameters:     Resolvable Private Address (6 Octets)
1941         Return Parameters:
1942
1943         This command is used to set the random address to local controller.
1944         If local device supports LE Privacy then this command will be called to set
1945         its Random address while active scanning remote devices and in the case of
1946         advertising itself.
1947
1948         This command intern calls the HCI Set Random address command from kernel
1949         space to set the RPA to controller.
1950
1951         This command generates a Command Complete event on success
1952         or a Command Status event on failure.
1953
1954         Possible errors:        Failed
1955                                 Invalid Index
1956
1957 #endif
1958
1959 Get Connection Information Command
1960 ==================================
1961
1962         Command Code:           0x0031
1963         Controller Index:       <controller id>
1964         Command Parameters:     Address (6 Octets)
1965                                 Address_Type (1 Octet)
1966         Return Parameters:      Address (6 Octets)
1967                                 Address_Type (1 Octet)
1968                                 RSSI (1 Octet)
1969                                 TX_Power (1 Octet)
1970                                 Max_TX_Power (1 Octet)
1971
1972         This command is used to get connection information.
1973
1974         Possible values for the Address_Type parameter:
1975                 0       BR/EDR
1976                 1       LE Public
1977                 2       LE Random
1978
1979         TX_Power and Max_TX_Power can be set to 127 if values are invalid or
1980         unknown. A value of 127 for RSSI indicates that it is not available.
1981
1982         This command generates a Command Complete event on success and
1983         on failure. In case of failure only Address and Address_Type fields
1984         are valid and values of remaining parameters are considered invalid
1985         and shall be ignored.
1986
1987         Possible errors:        Not Connected
1988                                 Not Powered
1989                                 Invalid Parameters
1990                                 Invalid Index
1991
1992
1993 Get Clock Information Command
1994 =============================
1995
1996         Command Code:           0x0032
1997         Controller Index:       <controller id>
1998         Command Parameters:     Address (6 Octets)
1999                                 Address_Type (1 Octet)
2000         Return Parameters:      Address (6 Octets)
2001                                 Address_Type (1 Octet)
2002                                 Local_Clock (4 Octets)
2003                                 Piconet_Clock (4 Octets)
2004                                 Accuracy (2 Octets)
2005
2006         This command is used to get local and piconet clock information.
2007
2008         Possible values for the Address_Type parameter:
2009                 0       BR/EDR
2010                 1       Reserved (not in use)
2011                 2       Reserved (not in use)
2012
2013         The Accuracy can be set to 0xffff which means the value is unknown.
2014
2015         If the Address is set to 00:00:00:00:00:00, then only the
2016         Local_Clock field has a valid value. The Piconet_Clock and
2017         Accuracy fields are invalid and shall be ignored.
2018
2019         This command generates a Command Complete event on success and
2020         on failure. In case of failure only Address and Address_Type fields
2021         are valid and values of remaining parameters are considered invalid
2022         and shall be ignored.
2023
2024         Possible errors:        Not Connected
2025                                 Not Powered
2026                                 Invalid Parameters
2027                                 Invalid Index
2028
2029
2030 Add Device Command
2031 ==================
2032
2033         Command Code:           0x0033
2034         Controller Index:       <controller id>
2035         Command Parameters:     Address (6 Octets)
2036                                 Address_Type (1 Octet)
2037                                 Action (1 Octet)
2038         Return Parameters:      Address (6 Octets)
2039                                 Address_Type (1 Octet)
2040
2041         This command is used to add a device to the action list. The
2042         action list allows scanning for devices and enables incoming
2043         connections from known devices.
2044
2045         Possible values for the Address_Type parameter:
2046                 0       BR/EDR
2047                 1       LE Public
2048                 2       LE Random
2049
2050         Possible values for the Action parameter:
2051                 0       Background scan for device
2052                 1       Allow incoming connection
2053                 2       Auto-connect remote device
2054
2055         With the Action 0, when the device is found, a new Device Found
2056         event will be sent indicating this device is available. This
2057         action is only valid for LE Public and LE Random address types.
2058
2059         With the Action 1, the device is allowed to connect. For BR/EDR
2060         address type this means an incoming connection. For LE Public
2061         and LE Random address types, a connection will be established
2062         to devices using directed advertising. If successful a Device
2063         Connected event will be sent.
2064
2065         With the Action 2, when the device is found, it will be connected
2066         and if successful a Device Connected event will be sent. This
2067         action is only valid for LE Public and LE Random address types.
2068
2069         When a device is blocked using Block Device command, then it is
2070         valid to add the device here, but all actions will be ignored
2071         until the device is unblocked.
2072
2073         Devices added with Action 1 are allowed to connect even if the
2074         connectable setting is off. This acts as list of known trusted
2075         devices.
2076
2077         This command can be used when the controller is not powered and
2078         all settings will be programmed once powered.
2079
2080         This command generates a Command Complete event on success
2081         or failure.
2082
2083         Possible errors:        Failed
2084                                 Invalid Parameters
2085                                 Invalid Index
2086
2087
2088 Remove Device Command
2089 =====================
2090
2091         Command Code:           0x0034
2092         Controller Index:       <controller id>
2093         Command Parameters:     Address (6 Octets)
2094                                 Address_Type (1 Octet)
2095         Return Parameters:      Address (6 Octets)
2096                                 Address_Type (1 Octet)
2097
2098         This command is used to remove a device from the action list
2099         previously added by using the Add Device command.
2100
2101         Possible values for the Address_Type parameter:
2102                 0       BR/EDR
2103                 1       LE Public
2104                 2       LE Random
2105
2106         When the Address parameter is 00:00:00:00:00:00, then all
2107         previously added devices will be removed.
2108
2109         This command can be used when the controller is not powered and
2110         all settings will be programmed once powered.
2111
2112         This command generates a Command Complete event on success
2113         or failure.
2114
2115         Possible errors:        Invalid Parameters
2116                                 Invalid Index
2117
2118
2119 Load Connection Parameters Command
2120 ==================================
2121
2122         Command Code:           0x0035
2123         Controller Index:       <controller id>
2124         Command Parameters:     Param_Count (2 Octets)
2125                                 Param1 {
2126                                         Address (6 Octets)
2127                                         Address_Type (1 Octet)
2128                                         Min_Connection_Interval (2 Octets)
2129                                         Max_Connection_Interval (2 Octets)
2130                                         Connection_Latency (2 Octets)
2131                                         Supervision_Timeout (2 Octets)
2132                                 }
2133                                 Param2 {  }
2134                                 ...
2135         Return Parameters:
2136
2137         This command is used to load connection parameters from several
2138         devices into kernel. Currently this is only supported on controllers
2139         with Low Energy support.
2140
2141         Possible values for the Address_Type parameter:
2142                 0       Reserved (not in use)
2143                 1       LE Public
2144                 2       LE Random
2145
2146         The provided Address and Address_Type are the identity of
2147         a device. So either its public address or static random address.
2148
2149         The Min_Connection_Interval, Max_Connection_Interval,
2150         Connection_Latency and Supervision_Timeout parameters should
2151         be configured as described in Core 4.1 spec, Vol 2, 7.8.12.
2152
2153         This command can be used when the controller is not powered.
2154
2155         This command generates a Command Complete event on success or
2156         a Command Status event on failure.
2157
2158         Possible errors:        Invalid Parameters
2159                                 Invalid Index
2160                                 Not Supported
2161
2162
2163 Read Unconfigured Controller Index List Command
2164 ===============================================
2165
2166         Command Code:           0x0036
2167         Controller Index:       <non-controller>
2168         Command Parameters:
2169         Return Parameters:      Num_Controllers (2 Octets)
2170                                 Controller_Index[i] (2 Octets)
2171
2172         This command returns the list of currently unconfigured controllers.
2173         Unconfigured controllers added after calling this command can be
2174         monitored using the Unconfigured Index Added event.
2175
2176         An unconfigured controller can either move to a configured state
2177         by indicating Unconfigured Index Removed event followed by an
2178         Index Added event; or it can be removed from the system which
2179         would be indicated by the Unconfigured Index Removed event.
2180
2181         Only controllers that require configuration will be listed with
2182         this command. A controller that is fully configured will not
2183         be listed even if it supports configuration changes.
2184
2185         This command generates a Command Complete event on success or
2186         a Command Status event on failure.
2187
2188
2189 Read Controller Configuration Information Command
2190 =================================================
2191
2192         Command Code:           0x0037
2193         Controller Index:       <controller id>
2194         Command Parameters:
2195         Return Parameters:      Manufacturer (2 Octets)
2196                                 Supported_Options (4 Octets)
2197                                 Missing_Options (4 Octets)
2198
2199         This command is used to retrieve the supported configuration
2200         options of a controller and the missing configuration options.
2201
2202         The missing options are required to be configured before the
2203         controller is considered fully configured and ready for standard
2204         operation. The command is typically used right after getting the
2205         response to Read Unconfigured Controller Index List command or
2206         Unconfigured Index Added event.
2207
2208         Supported_Options and Missing_Options is a bitmask with currently
2209         the following available bits:
2210
2211                 0       External configuration
2212                 1       Bluetooth public address configuration
2213
2214         It is valid to call this command on controllers that do not
2215         require any configuration. It is possible that a fully configured
2216         controller offers additional support for configuration.
2217
2218         For example a controller may contain a valid Bluetooth public
2219         device address, but also allows to configure it from the host
2220         stack. In this case the general support for configurations will
2221         be indicated by the Controller Configuration settings. For
2222         controllers where no configuration options are available that
2223         setting option will not be present.
2224
2225         When all configurations have been completed and as a result the
2226         Missing_Options mask would become empty, then the now ready
2227         controller will be announced via Index Added event.
2228
2229         This command generates a Command Complete event on success or
2230         a Command Status event on failure.
2231
2232         Possible errors:        Invalid Parameters
2233                                 Invalid Index
2234
2235
2236 Set External Configuration Command
2237 ==================================
2238
2239         Command Code:           0x0038
2240         Controller Index:       <controller id>
2241         Command Parameters:     Configuration (1 Octet)
2242         Return Parameters:      Missing_Options (4 Octets)
2243
2244         This command allows to change external configuration option to
2245         indicate that a controller is now configured or unconfigured.
2246
2247         The value 0x00 sets unconfigured state and the value 0x01 sets
2248         configured state of the controller.
2249
2250         It is not mandatory that this configuration option is provided
2251         by a controller. If it is provided, the configuration has to
2252         happen externally using user channel operation or via vendor
2253         specific methods.
2254
2255         Setting this option and when Missing_Options returns zero, this
2256         means that the controller will switch to configured state and it
2257         can be expected that it will be announced via Index Added event.
2258
2259         Wrongly configured controllers might still cause an error when
2260         trying to power them via Set Powered command.
2261
2262         This command generates a Command Complete event on success or a
2263         Command Status event on failure.
2264
2265         Possible errors:        Rejected
2266                                 Not Supported
2267                                 Invalid Parameters
2268                                 Invalid Index
2269
2270
2271 Set Public Address Command
2272 ==========================
2273
2274         Command Code:           0x0039
2275         Controller Index:       <controller id>
2276         Command Parameters:     Address (6 Octets)
2277         Return Parameters:      Missing_Options (4 Octets)
2278
2279         This command allows configuration of public address. Since a vendor
2280         specific procedure is required, this command might not be supported
2281         by all controllers. Actually most likely only a handful embedded
2282         controllers will offer support for this command.
2283
2284         When the support for Bluetooth public address configuration is
2285         indicated in the supported options mask, then this command
2286         can be used to configure the public address.
2287
2288         It is only possible to configure the public address when the
2289         controller is powered off.
2290
2291         For an unconfigured controller and when Missing_Options returns
2292         an empty mask, this means that a Index Added event for the now
2293         fully configured controller can be expected.
2294
2295         For a fully configured controller, the current controller index
2296         will become invalid and an Unconfigured Index Removed event will
2297         be sent. Once the address has been successfully changed an Index
2298         Added event will be sent. There is no guarantee that the controller
2299         index stays the same.
2300
2301         All previous configured parameters and settings are lost when
2302         this command succeeds. The controller has to be treated as new
2303         one. Use this command for a fully configured controller only when
2304         you really know what you are doing.
2305
2306         This command generates a Command Complete event on success or a
2307         Command Status event on failure.
2308
2309         Possible errors:        Rejected
2310                                 Not Supported
2311                                 Invalid Parameters
2312                                 Invalid Index
2313
2314
2315 Start Service Discovery Command
2316 ===============================
2317
2318         Command Code:           0x003a
2319         Controller Index:       <controller id>
2320         Command Parameters:     Address_Type (1 Octet)
2321                                 RSSI_Threshold (1 Octet)
2322                                 UUID_Count (1 Octet)
2323                                 UUID[i] (16 Octets)
2324         Return Parameters:      Address_Type (1 Octet)
2325
2326         This command is used to start the process of discovering remote
2327         devices with a specific UUID. A Device Found event will be sent
2328         for each discovered device.
2329
2330         Possible values for the Address_Type parameter are a bit-wise or
2331         of the following bits:
2332
2333                 0       BR/EDR
2334                 1       LE Public
2335                 2       LE Random
2336
2337         By combining these e.g. the following values are possible:
2338
2339                 1       BR/EDR
2340                 6       LE (public & random)
2341                 7       BR/EDR/LE (interleaved discovery)
2342
2343         The service discovery uses active scanning for Low Energy scanning
2344         and will search for UUID in both advertising data and scan response
2345         data.
2346
2347         Found devices that have a RSSI value smaller than RSSI_Threshold
2348         are not reported via DeviceFound event. Setting a value of 127
2349         will cause all devices to be reported.
2350
2351         The list of UUIDs identifies a logical OR. Only one of the UUIDs
2352         have to match to cause a DeviceFound event. Providing an empty
2353         list of UUIDs with Num_UUID set to 0 which means that DeviceFound
2354         events are send out for all devices above the RSSI_Threshold.
2355
2356         In case RSSI_Threshold is set to 127 and UUID_Count is 0, then
2357         this command behaves exactly the same as Start Discovery.
2358
2359         When the discovery procedure starts the Discovery event will
2360         notify this similar to Start Discovery.
2361
2362         This command can only be used when the controller is powered.
2363
2364         This command generates a Command Complete event on success
2365         or failure.
2366
2367         Possible errors:        Busy
2368                                 Not Supported
2369                                 Invalid Parameters
2370                                 Not Powered
2371                                 Invalid Index
2372
2373
2374 Read Local Out Of Band Extended Data Command
2375 ============================================
2376
2377         Command Code:           0x003b
2378         Controller Index:       <controller id>
2379         Command Parameters:     Address_Type (1 Octet)
2380         Return Parameters:      Address_Type (1 Octet)
2381                                 EIR_Data_Length (2 Octets)
2382                                 EIR_Data (0-65535 Octets)
2383
2384         This command is used to read the local Out of Band data
2385         information and provide them encoded as extended inquiry
2386         response information or advertising data.
2387
2388         Possible values for the Address_Type parameter are a bit-wise or
2389         of the following bits:
2390
2391                 0       BR/EDR
2392                 1       LE Public
2393                 2       LE Random
2394
2395         By combining these e.g. the following values are possible:
2396
2397                 1       BR/EDR
2398                 6       LE (public & random)
2399                 7       Reserved (not in use)
2400
2401         For BR/EDR controller (Address_Type 1) the returned information
2402         will contain the following information:
2403
2404                 Class of Device
2405                 Simple Pairing Hash C-192 (optional)
2406                 Simple Pairing Randomizer R-192 (optional)
2407                 Simple Pairing Hash C-256 (optional)
2408                 Simple Pairing Randomizer R-256 (optional)
2409                 Service Class UUID (optional)
2410                 Bluetooth Local Name (optional)
2411
2412         The Simple Pairing Hash C-256 and Simple Pairing Randomizer R-256
2413         fields are only included when secure connections has been enabled.
2414
2415         The Device Address (BD_ADDR) is not included in the EIR_Data and
2416         needs to be taken from controller information.
2417
2418         For LE controller (Address_Type 6) the returned information
2419         will contain the following information:
2420
2421                 LE Bluetooth Device Address
2422                 LE Role
2423                 LE Secure Connections Confirmation Value (optional)
2424                 LE Secure Connections Random Value (optional)
2425                 Appearance (optional)
2426                 Local Name (optional)
2427                 Flags
2428
2429         The LE Secure Connections Confirmation Value and LE Secure Connections
2430         Random Value fields are only included when secure connections has been
2431         enabled.
2432
2433         The Security Manager TK Value from the Bluetooth specification can
2434         not be provided by this command. The Out Of Band information here are
2435         for asymmetric exchanges based on Diffie-Hellman key exchange. The
2436         Security Manager TK Value is a symmetric random number that has to
2437         be acquired and agreed upon differently.
2438
2439         The returned information from BR/EDR controller and LE controller
2440         types are not related to each other. Once they have been used
2441         over an Out Of Band link, a new set of information shall be
2442         requested.
2443
2444         When Secure Connections Only mode has been enabled, then the fields
2445         for Simple Pairing Hash C-192 and Simple Pairing Randomizer R-192
2446         are not returned. Only the fields for the strong secure connections
2447         pairing are included.
2448
2449         This command can only be used when the controller is powered.
2450
2451         Values returned by this command become invalid when the controller
2452         is powered down. After each power-cycle it is required to call
2453         this command again to get updated information.
2454
2455         This command generates a Command Complete event on success or
2456         a Command Status event on failure.
2457
2458         Possible errors:        Not Supported
2459                                 Busy
2460                                 Invalid Parameters
2461                                 Not Powered
2462                                 Invalid Index
2463
2464
2465 Read Extended Controller Index List Command
2466 ===========================================
2467
2468         Command Code:           0x003c
2469         Controller Index:       <non-controller>
2470         Command Parameters:
2471         Return Parameters:      Num_Controllers (2 Octets)
2472                                 Controller_Index[i] (2 Octets)
2473                                 Controller_Type[i] (1 Octet)
2474                                 Controller_Bus[i] (1 Octet)
2475
2476         This command returns the list of currently known controllers. It
2477         includes configured, unconfigured and alternate controllers.
2478
2479         Controllers added or removed after calling this command can be
2480         be monitored using the Extended Index Added and Extended Index
2481         Removed events.
2482
2483         The existing Index Added, Index Removed, Unconfigured Index Added
2484         and Unconfigured Index Removed are no longer sent after this command
2485         has been used at least once.
2486
2487         Instead of calling Read Controller Index List and Read Unconfigured
2488         Controller Index List, this command combines all the information
2489         and can be used to retrieve the controller list.
2490
2491         The Controller_Type parameter has these values:
2492
2493                 0x00    Primary Controller (BR/EDR and/or LE)
2494                 0x01    Unconfigured Controller (BR/EDR and/or LE)
2495                 0x02    Alternate MAC/PHY Controller (AMP)
2496
2497         The 0x00 and 0x01 types indicate a primary BR/EDR and/or LE
2498         controller. The difference is just if they need extra configuration
2499         or if they are fully configured.
2500
2501         Controllers in configured state will be listed as 0x00 and controllers
2502         in unconfigured state will be listed as 0x01. A controller that is
2503         fully configured and supports configuration changes will be listed
2504         as 0x00.
2505
2506         Alternate MAC/PHY controllers will be listed as 0x02. They do not
2507         support the difference between configured and unconfigured state.
2508
2509         The Controller_Bus parameter has these values:
2510
2511                 0x00    Virtual
2512                 0x01    USB
2513                 0x02    PCMCIA
2514                 0x03    UART
2515                 0x04    RS232
2516                 0x05    PCI
2517                 0x06    SDIO
2518
2519         Controllers marked as RAW only operation are currently not listed
2520         by this command.
2521
2522         This command generates a Command Complete event on success or
2523         a Command Status event on failure.
2524
2525
2526 Read Advertising Features Command
2527 =================================
2528
2529         Command Code:           0x003d
2530         Controller Index:       <controller id>
2531         Command Parameters:
2532         Return Parameters:      Supported_Flags (4 Octets)
2533                                 Max_Adv_Data_Len (1 Octet)
2534                                 Max_Scan_Rsp_Len (1 Octet)
2535                                 Max_Instances (1 Octet)
2536                                 Num_Instances (1 Octet)
2537                                 Instance[i] (1 Octet)
2538
2539         This command is used to read the advertising features supported
2540         by the controller and stack.
2541
2542         With the Supported_Flags field the possible values for the Flags
2543         field in Add Advertising command provided:
2544
2545                 0       Switch into Connectable mode
2546                 1       Advertise as Discoverable
2547                 2       Advertise as Limited Discoverable
2548                 3       Add Flags field to Adv_Data
2549                 4       Add TX Power field to Adv_Data
2550                 5       Add Appearance field to Scan_Rsp
2551                 6       Add Local Name in Scan_Rsp
2552
2553         The Flags bit 0 indicates support for connectable advertising
2554         and for switching to connectable advertising independent of the
2555         connectable global setting. When this flag is not supported, then
2556         the global connectable setting determines if undirected connectable,
2557         undirected scannable or undirected non-connectable advertising is
2558         used. It also determines the use of non-resolvable random address
2559         versus identity address or resolvable private address.
2560
2561         The Flags bit 1 indicates support for advertising with discoverable
2562         mode enabled. Users of this flag will decrease the Max_Adv_Data_Len
2563         by 3 octets. In this case the advertising data flags are managed
2564         and added in front of the provided advertising data.
2565
2566         The Flags bit 2 indicates support for advertising with limited
2567         discoverable mode enabled. Users of this flag will decrease the
2568         Max_Adv_Data_Len by 3 octets. In this case the advertising data
2569         flags are managed and added in front of the provided advertising
2570         data.
2571
2572         The Flags bit 3 indicates support for automatically keeping the
2573         Flags field of the advertising data updated. Users of this flag
2574         will decrease the Max_Adv_Data_Len by 3 octets and need to keep
2575         that in mind. The Flags field will be added in front of the
2576         advertising data provided by the user. Note that with Flags bit 1
2577         and Flags bit 2, this one will be implicitly used even if it is
2578         not marked as supported.
2579
2580         The Flags bit 4 indicates support for automatically adding the
2581         TX Power value to the advertising data. Users of this flag will
2582         decrease the Max_Adv_Data_Len by 3 octets. The TX Power field will
2583         be added at the end of the user provided advertising data. If the
2584         controller does not support TX Power information, then this bit will
2585         not be set.
2586
2587         The Flags bit 5 indicates support for automatically adding the
2588         Appearance value to the scan response data. Users of this flag
2589         will decrease the Max_Scan_Rsp_len by 4 octets. The Appearance
2590         field will be added in front of the scan response data provided
2591         by the user. If the appearance value is not supported, then this
2592         bit will not be set.
2593
2594         The Flags bit 6 indicates support for automatically adding the
2595         Local Name value to the scan response data. This flag indicates
2596         an opportunistic approach for the Local Name. If enough space
2597         in the scan response data is available, it will be added. If the
2598         space is limited a short version or no name information. The
2599         Local Name will be added at the end of the scan response data.
2600
2601         The valid range for Instance identifiers is 1-254. The value 0
2602         is reserved for internal use and the value 255 is reserved for
2603         future extensions. However the Max_Instances value for indicating
2604         the number of supported Instances can be also 0 if the controller
2605         does not support any advertising.
2606
2607         The Max_Adv_Data_Len and Max_Scan_Rsp_Len provides extra
2608         information about the maximum length of the data fields. For
2609         now this will always return the value 31. Different flags
2610         however might decrease the actual available length in these
2611         data fields.
2612
2613         With Num_Instances and Instance array the currently occupied
2614         Instance identifiers can be retrieved.
2615
2616         This command generates a Command Complete event on success or
2617         a Command Status event on failure.
2618
2619         Possible errors:        Invalid Parameters
2620                                 Invalid Index
2621
2622
2623 Add Advertising Command
2624 =======================
2625
2626         Command Code:           0x003e
2627         Controller Index:       <controller id>
2628         Command Parameters:     Instance (1 Octet)
2629                                 Flags (4 Octets)
2630                                 Duration (2 Octets)
2631                                 Timeout (2 Octets)
2632                                 Adv_Data_Len (1 Octet)
2633                                 Scan_Rsp_len (1 Octet)
2634                                 Adv_Data (0-255 Octets)
2635                                 Scan_Rsp (0-255 Octets)
2636         Return Parameters:      Instance (1 Octet)
2637
2638         This command is used to configure an advertising instance that
2639         can be used to switch a Bluetooth Low Energy controller into
2640         advertising mode.
2641
2642         Added advertising information with this command will not be visible
2643         immediately if advertising is enabled via the Set Advertising
2644         command. The usage of the Set Advertising command takes precedence
2645         over this command. Instance information is stored and will be
2646         advertised once advertising via Set Advertising has been disabled.
2647
2648         The Instance identifier is a value between 1 and the number of
2649         supported instances. The value 0 is reserved.
2650
2651         With the Flags value the type of advertising is controlled and
2652         the following flags are defined:
2653
2654                 0       Switch into Connectable mode
2655                 1       Advertise as Discoverable
2656                 2       Advertise as Limited Discoverable
2657                 3       Add Flags field to Adv_Data
2658                 4       Add TX Power field to Adv_Data
2659                 5       Add Appearance field to Scan_Rsp
2660                 6       Add Local Name in Scan_Rsp
2661
2662         When the connectable flag is set, then the controller will use
2663         undirected connectable advertising. The value of the connectable
2664         setting can be overwritten this way. This is useful to switch a
2665         controller into connectable mode only for LE operation. This is
2666         similar to the mode 0x02 from the Set Advertising command.
2667
2668         When the connectable flag is not set, then the controller will
2669         use advertising based on the connectable setting. When using
2670         non-connectable or scannable advertising, the controller will
2671         be programmed with a non-resolvable random address. When the
2672         system is connectable, then the identity address or resolvable
2673         private address will be used.
2674
2675         Using the connectable flag is useful for peripheral mode support
2676         where BR/EDR (and/or LE) is controlled by Add Device. This allows
2677         making the peripheral connectable without having to interfere
2678         with the global connectable setting.
2679
2680         If Scan_Rsp_Len is zero and connectable flag is not set and
2681         the global connectable setting is off, then non-connectable
2682         advertising is used. If Scan_Rsp_Len is larger than zero and
2683         connectable flag is not set and the global advertising is off,
2684         then scannable advertising is used. This small difference is
2685         supported to provide less air traffic for devices implementing
2686         broadcaster role.
2687
2688         The Duration parameter configures the length of an Instance. The
2689         value is in seconds.
2690
2691         A value of 0 indicates a default value is chosen for the
2692         Duration. The default is 2 seconds.
2693
2694         If only one advertising Instance has been added, then the Duration
2695         value will be ignored. It only applies for the case where multiple
2696         Instances are configured. In that case every Instance will be
2697         available for the Duration time and after that it switches to
2698         the next one. This is a simple round-robin based approach.
2699
2700         The Timeout parameter configures the life-time of an Instance. In
2701         case the value 0 is used it indicates no expiration time. If a
2702         timeout value is provided, then the advertising Instance will be
2703         automatically removed when the timeout passes. The value for the
2704         timeout is in seconds. Powering down a controller will invalidate
2705         all advertising Instances and it is not possible to add a new
2706         Instance with a timeout when the controller is powered down.
2707
2708         When a Timeout is provided, then the Duration subtracts from
2709         the actual Timeout value of that Instance. For example an Instance
2710         with Timeout of 5 and Duration of 2 will be scheduled exactly 3
2711         times, twice with 2 seconds and once with one second. Other
2712         Instances have no influence on the Timeout.
2713
2714         Re-adding an already existing instance (i.e. issuing the Add
2715         Advertising command with an Instance identifier of an existing
2716         instance) will update that instance's configuration.
2717
2718         An instance being added or changed while another instance is
2719         being advertised will not be visible immediately but only when
2720         the new/changed instance is being scheduled by the round robin
2721         advertising algorithm.
2722
2723         Changes to an instance that is currently being advertised will
2724         cancel that instance and switch to the next instance. The changes
2725         will be visible the next time the instance is scheduled for
2726         advertising. In case a single instance is active, this means
2727         that changes will be visible right away.
2728
2729         A pre-requisite is that LE is already enabled, otherwise this
2730         command will return a "rejected" response.
2731
2732         This command can be used when the controller is not powered and
2733         all settings will be programmed once powered.
2734
2735         This command generates a Command Complete event on success or a
2736         Command Status event on failure.
2737
2738         Possible errors:        Failed
2739                                 Rejected
2740                                 Not Supported
2741                                 Invalid Parameters
2742                                 Invalid Index
2743
2744
2745 Remove Advertising Command
2746 ==========================
2747
2748         Command Code:           0x003f
2749         Controller Index:       <controller id>
2750         Command Parameters:     Instance (1 Octet)
2751         Return Parameters:      Instance (1 Octet)
2752
2753         This command is used to remove an advertising instance that
2754         can be used to switch a Bluetooth Low Energy controller into
2755         advertising mode.
2756
2757         When the Instance parameter is zero, then all previously added
2758         advertising Instances will be removed.
2759
2760         Removing advertising information with this command will not be
2761         visible as long as advertising is enabled via the Set Advertising
2762         command. The usage of the Set Advertising command takes precedence
2763         over this command. Changes to Instance information are stored and
2764         will be advertised once advertising via Set Advertising has been
2765         disabled.
2766
2767         Removing an instance while it is being advertised will immediately
2768         cancel the instance, even when it has been advertised less then its
2769         configured Timeout or Duration.
2770
2771         This command can be used when the controller is not powered and
2772         all settings will be programmed once powered.
2773
2774         This command generates a Command Complete event on success or
2775         a Command Status event on failure.
2776
2777         Possible errors:        Invalid Parameters
2778                                 Invalid Index
2779
2780
2781 Get Advertising Size Information Command
2782 ========================================
2783
2784         Command Code:           0x0040
2785         Controller Index:       <controller id>
2786         Command Parameters:     Instance (1 Octet)
2787                                 Flags (4 Octets)
2788         Return Parameters:      Instance (1 Octet)
2789                                 Flags (4 Octets)
2790                                 Max_Adv_Data_Len (1 Octet)
2791                                 Max_Scan_Rsp_Len (1 Octet)
2792
2793         The Read Advertising Features command returns the overall maximum
2794         size of advertising data and scan response data fields. That size is
2795         valid when no Flags are used. However when certain Flags are used,
2796         then the size might decrease. This command can be used to request
2797         detailed information about the maximum available size.
2798
2799         The following Flags values are defined:
2800
2801                 0       Switch into Connectable mode
2802                 1       Advertise as Discoverable
2803                 2       Advertise as Limited Discoverable
2804                 3       Add Flags field to Adv_Data
2805                 4       Add TX Power field to Adv_Data
2806                 5       Add Appearance field to Scan_Rsp
2807                 6       Add Local Name in Scan_Rsp
2808
2809         To get accurate information about the available size, the same Flags
2810         values should be used with the Add Advertising command.
2811
2812         The Max_Adv_Data_Len and Max_Scan_Rsp_Len fields provide information
2813         about the maximum length of the data fields for the given Flags
2814         values. When the Flags field is zero, then these fields would contain
2815         the same values as Read Advertising Features.
2816
2817         Possible errors:        Invalid Parameters
2818                                 Invalid Index
2819
2820
2821 Start Limited Discovery Command
2822 ===============================
2823
2824         Command Code:           0x0041
2825         Controller Index:       <controller id>
2826         Command Parameters:     Address_Type (1 Octet)
2827         Return Parameters:      Address_Type (1 Octet)
2828
2829         This command is used to start the process of discovering remote
2830         devices using the limited discovery procedure. A Device Found event
2831         will be sent for each discovered device.
2832
2833         Possible values for the Address_Type parameter are a bit-wise or
2834         of the following bits:
2835
2836                 0       BR/EDR
2837                 1       LE Public
2838                 2       LE Random
2839
2840         By combining these e.g. the following values are possible:
2841
2842                 1       BR/EDR
2843                 6       LE (public & random)
2844                 7       BR/EDR/LE (interleaved discovery)
2845
2846         The limited discovery uses active scanning for Low Energy scanning
2847         and will search for devices with the limited discoverability flag
2848         configured. On BR/EDR it uses LIAC and filters on the limited
2849         discoverability flag of the class of device.
2850
2851         When the discovery procedure starts the Discovery event will
2852         notify this similar to Start Discovery.
2853
2854         This command can only be used when the controller is powered.
2855
2856         This command generates a Command Complete event on success
2857         or failure.
2858
2859         Possible errors:        Busy
2860                                 Not Supported
2861                                 Invalid Parameters
2862                                 Not Powered
2863                                 Invalid Index
2864
2865
2866 Command Complete Event
2867 ======================
2868
2869         Event Code:             0x0001
2870         Controller Index:       <controller id> or <non-controller>
2871         Event Parameters:       Command_Opcode (2 Octets)
2872                                 Status (1 Octet)
2873                                 Return_Parameters
2874
2875         This event is an indication that a command has completed. The
2876         fixed set of parameters includes the opcode to identify the
2877         command that completed as well as a status value to indicate
2878         success or failure. The rest of the parameters are command
2879         specific and documented in the section for each command
2880         separately.
2881
2882
2883 Command Status Event
2884 ====================
2885
2886         Event Code:             0x0002
2887         Controller Index:       <controller id> or <non-controller>
2888         Event Parameters:       Command_Opcode (2 Octets)
2889                                 Status (1 Octet)
2890
2891         The command status event is used to indicate an early status for
2892         a pending command. In the case that the status indicates failure
2893         (anything else except success status) this also means that the
2894         command has finished executing.
2895
2896
2897 Controller Error Event
2898 ======================
2899
2900         Event Code:             0x0003
2901         Controller Index:       <controller id>
2902         Event Parameters:       Error_Code (1 Octet)
2903
2904         This event maps straight to the HCI Hardware Error event and is
2905         used to indicate something wrong with the controller hardware.
2906
2907
2908 Index Added Event
2909 =================
2910
2911         Event Code:             0x0004
2912         Controller Index:       <controller id>
2913         Event Parameters:
2914
2915         This event indicates that a new controller has been added to the
2916         system. It is usually followed by a Read Controller Information
2917         command.
2918
2919         Once the Read Extended Controller Index List command has been
2920         used at least once, the Extended Index Added event will be
2921         send instead of this one.
2922
2923
2924 Index Removed Event
2925 ===================
2926
2927         Event Code:             0x0005
2928         Controller Index:       <controller id>
2929         Event Parameters:
2930
2931         This event indicates that a controller has been removed from the
2932         system.
2933
2934         Once the Read Extended Controller Index List command has been
2935         used at least once, the Extended Index Removed event will be
2936         send instead of this one.
2937
2938
2939 New Settings Event
2940 ==================
2941
2942         Event Code:             0x0006
2943         Controller Index:       <controller id>
2944         Event Parameters:       Current_Settings (4 Octets)
2945
2946         This event indicates that one or more of the settings for a
2947         controller has changed.
2948
2949
2950 Class Of Device Changed Event
2951 =============================
2952
2953         Event Code:             0x0007
2954         Controller Index:       <controller id>
2955         Event Parameters:       Class_Of_Device (3 Octets)
2956
2957         This event indicates that the Class of Device value for the
2958         controller has changed. When the controller is powered off the
2959         Class of Device value will always be reported as zero.
2960
2961
2962 Local Name Changed Event
2963 ========================
2964
2965         Event Code:             0x0008
2966         Controller Index:       <controller id>
2967         Event Parameters:       Name (249 Octets)
2968                                 Short_Name (11 Octets)
2969
2970         This event indicates that the local name of the controller has
2971         changed.
2972
2973
2974 New Link Key Event
2975 ==================
2976
2977         Event Code:             0x0009
2978         Controller Index:       <controller id>
2979         Event Parameters:       Store_Hint (1 Octet)
2980                                 Key {
2981                                         Address (6 Octets)
2982                                         Address_Type (1 Octet)
2983                                         Key_Type (1 Octet)
2984                                         Value (16 Octets)
2985                                         PIN_Length (1 Octet)
2986                                 }
2987
2988         This event indicates that a new link key has been generated for a
2989         remote device.
2990
2991         The Store_Hint parameter indicates whether the host is expected
2992         to store the key persistently or not (e.g. this would not be set
2993         if the authentication requirement was "No Bonding").
2994
2995         Possible values for the Address_Type parameter:
2996                 0       BR/EDR
2997                 1       Reserved (not in use)
2998                 2       Reserved (not in use)
2999
3000         Public and random LE addresses are not valid and will be rejected.
3001
3002         Currently defined Key_Type values are:
3003
3004                 0x00    Combination key
3005                 0x01    Local Unit key
3006                 0x02    Remote Unit key
3007                 0x03    Debug Combination key
3008                 0x04    Unauthenticated Combination key from P-192
3009                 0x05    Authenticated Combination key from P-192
3010                 0x06    Changed Combination key
3011                 0x07    Unauthenticated Combination key from P-256
3012                 0x08    Authenticated Combination key from P-256
3013
3014         Receiving this event indicates that a pairing procedure has
3015         been completed.
3016
3017
3018 New Long Term Key Event
3019 =======================
3020
3021         Event Code:             0x000A
3022         Controller Index:       <controller id>
3023         Event Parameters:       Store_Hint (1 Octet)
3024                                 Key {
3025                                         Address (6 Octets)
3026                                         Address_Type (1 Octet)
3027                                         Key_Type (1 Octet)
3028                                         Master (1 Octet)
3029                                         Encryption Size (1 Octet)
3030                                         Enc. Diversifier (2 Octets)
3031                                         Random Number (8 Octets)
3032                                         Value (16 Octets)
3033                                 }
3034
3035         This event indicates that a new long term key has been generated
3036         for a remote device.
3037
3038         The Store_Hint parameter indicates whether the host is expected
3039         to store the key persistently or not (e.g. this would not be set
3040         if the authentication requirement was "No Bonding").
3041
3042         Possible values for the Address_Type parameter:
3043                 0       Reserved (not in use)
3044                 1       LE Public
3045                 2       LE Random
3046
3047         The provided Address and Address_Type are the identity of
3048         a device. So either its public address or static random address.
3049
3050         For unresolvable random addresses and resolvable random addresses
3051         without identity information and identity resolving key, the
3052         Store_Hint will be set to not store the long term key.
3053
3054         Currently defined Key_Type values are:
3055
3056                 0x00    Unauthenticated legacy key
3057                 0x01    Authenticated legacy key
3058                 0x02    Unauthenticated key from P-256
3059                 0x03    Authenticated key from P-256
3060                 0x04    Debug key from P-256
3061
3062         Receiving this event indicates that a pairing procedure has
3063         been completed.
3064
3065
3066 Device Connected Event
3067 ======================
3068
3069         Event Code:             0x000B
3070         Controller Index:       <controller id>
3071         Event Parameters:       Address (6 Octets)
3072                                 Address_Type (1 Octet)
3073                                 Flags (4 Octets)
3074                                 EIR_Data_Length (2 Octets)
3075                                 EIR_Data (0-65535 Octets)
3076
3077         This event indicates that a successful baseband connection has
3078         been created to the remote device.
3079
3080         Possible values for the Address_Type parameter:
3081                 0       BR/EDR
3082                 1       LE Public
3083                 2       LE Random
3084
3085         For devices using resolvable random addresses with a known
3086         identity resolving key, the Address and Address_Type will
3087         contain the identity information.
3088
3089         It is possible that devices get connected via its resolvable
3090         random address and after New Identity Resolving Key event
3091         start using its identity.
3092
3093         The following bits are defined for the Flags parameter:
3094                 0       Reserved (not in use)
3095                 1       Legacy Pairing
3096                 2       Reserved (not in use)
3097
3098
3099 Device Disconnected Event
3100 =========================
3101
3102         Event Code:             0x000C
3103         Controller Index:       <controller id>
3104         Event Parameters:       Address (6 Octets)
3105                                 Address_Type (1 Octet)
3106                                 Reason (1 Octet)
3107
3108         This event indicates that the baseband connection was lost to a
3109         remote device.
3110
3111         Possible values for the Address_Type parameter:
3112                 0       BR/EDR
3113                 1       LE Public
3114                 2       LE Random
3115
3116         For devices using resolvable random addresses with a known
3117         identity resolving key, the Address and Address_Type will
3118         contain the identity information.
3119
3120         Possible values for the Reason parameter:
3121                 0       Unspecified
3122                 1       Connection timeout
3123                 2       Connection terminated by local host
3124                 3       Connection terminated by remote host
3125
3126         Note that the local/remote distinction just determines which side
3127         terminated the low-level connection, regardless of the
3128         disconnection of the higher-level profiles.
3129
3130         This can sometimes be misleading and thus must be used with care.
3131         For example, some hardware combinations would report a locally
3132         initiated disconnection even if the user turned Bluetooth off in
3133         the remote side.
3134
3135
3136 Connect Failed Event
3137 ====================
3138
3139         Event Code:             0x000D
3140         Controller Index:       <controller id>
3141         Event Parameters:       Address (6 Octets)
3142                                 Address_Type (1 Octet)
3143                                 Status (1 Octet)
3144
3145         This event indicates that a connection attempt failed to a
3146         remote device.
3147
3148         Possible values for the Address_Type parameter:
3149                 0       BR/EDR
3150                 1       LE Public
3151                 2       LE Random
3152
3153         For devices using resolvable random addresses with a known
3154         identity resolving key, the Address and Address_Type will
3155         contain the identity information.
3156
3157
3158 PIN Code Request Event
3159 ======================
3160
3161         Event Code:             0x000E
3162         Controller Index:       <controller id>
3163         Event Parameters:       Address (6 Octets)
3164                                 Address_Type (1 Octet)
3165                                 Secure (1 Octet)
3166
3167         This event is used to request a PIN Code reply from user space.
3168         The reply should either be returned using the PIN Code Reply or
3169         the PIN Code Negative Reply command.
3170
3171         Possible values for the Address_Type parameter:
3172                 0       BR/EDR
3173                 1       LE Public
3174                 2       LE Random
3175
3176         Secure: 0x01  secure PIN code required
3177                 0x00  secure PIN code not required
3178
3179
3180 User Confirmation Request Event
3181 ===============================
3182
3183         Event Code:             0x000F
3184         Controller Index:       <controller id>
3185         Event Parameters:       Address (6 Octets)
3186                                 Address_Type (1 Octet)
3187                                 Confirm_Hint (1 Octet)
3188                                 Value (4 Octets)
3189
3190         This event is used to request a user confirmation request from
3191         user space.
3192
3193         Possible values for the Address_Type parameter:
3194                 0       BR/EDR
3195                 1       LE Public
3196                 2       LE Random
3197
3198         If the Confirm_Hint parameter value is 0x01 this means that
3199         a simple "Yes/No" confirmation should be presented to the user
3200         instead of a full numerical confirmation (in which case the
3201         parameter value will be 0x00).
3202
3203         User space should respond to this command either using the User
3204         Confirmation Reply or the User Confirmation Negative Reply
3205         command.
3206
3207
3208 User Passkey Request Event
3209 ==========================
3210
3211         Event Code:             0x0010
3212         Controller Index:       <controller id>
3213         Event Parameters:       Address (6 Octets)
3214                                 Address_Type (1 Octet)
3215
3216         This event is used to request a passkey from user space. The
3217         response to this event should either be the User Passkey Reply
3218         command or the User Passkey Negative Reply command.
3219
3220         Possible values for the Address_Type parameter:
3221                 0       BR/EDR
3222                 1       LE Public
3223                 2       LE Random
3224
3225
3226 Authentication Failed Event
3227 ===========================
3228
3229         Event Code:             0x0011
3230         Controller Index:       <controller id>
3231         Event Parameters:       Address (6 Octets)
3232                                 Address_Type (1 Octet)
3233                                 Status (1 Octet)
3234
3235         This event indicates that there was an authentication failure
3236         with a remote device.
3237
3238         Possible values for the Address_Type parameter:
3239                 0       BR/EDR
3240                 1       LE Public
3241                 2       LE Random
3242
3243
3244 Device Found Event
3245 ==================
3246
3247         Event Code:             0x0012
3248         Controller Index:       <controller id>
3249         Event Parameters:       Address (6 Octets)
3250                                 Address_Type (1 Octet)
3251                                 RSSI (1 Octet)
3252                                 Flags (4 Octets)
3253                                 EIR_Data_Length (2 Octets)
3254                                 EIR_Data (0-65535 Octets)
3255
3256         This event indicates that a device was found during device
3257         discovery.
3258
3259         Possible values for the Address_Type parameter:
3260                 0       BR/EDR
3261                 1       LE Public
3262                 2       LE Random
3263
3264         The following bits are defined for the Flags parameter:
3265                 0       Confirm name
3266                 1       Legacy Pairing
3267                 2       Not Connectable
3268
3269         For the RSSI field a value of 127 indicates that the RSSI is
3270         not available. That can happen with Bluetooth 1.1 and earlier
3271         controllers or with bad radio conditions.
3272
3273         The Confirm name flag indicates that the kernel wants to know
3274         whether user space knows the name for this device or not. If
3275         this flag is set user space should respond to it using the
3276         Confirm Name command.
3277
3278         The Legacy Pairing flag indicates that Legacy Pairing is likely
3279         to occur when pairing with this device. An application could use
3280         this information to optimize the pairing process by locally
3281         pre-generating a PIN code and thereby eliminate the risk of
3282         local input timeout when pairing. Note that there is a risk of
3283         false-positives for this flag so user space should be able to
3284         handle getting something else as a PIN Request when pairing.
3285
3286         The Not Connectable flag indicates that the device will not
3287         accept any connections. This can be indicated by Low Energy
3288         devices that are in broadcaster role.
3289
3290
3291 Discovering Event
3292 =================
3293
3294         Event Code:             0x0013
3295         Controller Index:       <controller id>
3296         Event Parameters:       Address_Type (1 Octet)
3297                                 Discovering (1 Octet)
3298
3299         This event indicates that the controller has started discovering
3300         devices. This discovering state can come and go multiple times
3301         between a Start Discovery and a Stop Discovery commands.
3302
3303         The Start Service Discovery command will also trigger this event.
3304
3305         The valid values for the Discovering parameter are 0x01
3306         (enabled) and 0x00 (disabled).
3307
3308
3309 Device Blocked Event
3310 ====================
3311
3312         Event Code:             0x0014
3313         Controller Index:       <controller id>
3314         Event Parameters:       Address (6 Octets)
3315                                 Address_Type (1 Octet)
3316
3317         This event indicates that a device has been blocked using the
3318         Block Device command.
3319
3320         Possible values for the Address_Type parameter:
3321                 0       BR/EDR
3322                 1       LE Public
3323                 2       LE Random
3324
3325         The event will only be sent to Management sockets other than the
3326         one through which the command was sent.
3327
3328
3329 Device Unblocked Event
3330 ======================
3331
3332         Event Code:             0x0015
3333         Controller Index:       <controller id>
3334         Event Parameters:       Address (6 Octets)
3335                                 Address_Type (1 Octet)
3336
3337         This event indicates that a device has been unblocked using the
3338         Unblock Device command.
3339
3340         Possible values for the Address_Type parameter:
3341                 0       BR/EDR
3342                 1       LE Public
3343                 2       LE Random
3344
3345         The event will only be sent to Management sockets other than the
3346         one through which the command was sent.
3347
3348
3349 Device Unpaired Event
3350 =====================
3351
3352         Event Code:             0x0016
3353         Controller Index:       <controller id>
3354         Event Parameters:       Address (6 Octets)
3355                                 Address_Type (1 Octet)
3356
3357         This event indicates that a device has been unpaired (i.e. all
3358         its keys have been removed from the kernel) using the Unpair
3359         Device command.
3360
3361         Possible values for the Address_Type parameter:
3362                 0       BR/EDR
3363                 1       LE Public
3364                 2       LE Random
3365
3366         For devices using resolvable random addresses with a known
3367         identity resolving key, the event parameters will contain
3368         the identity. After receiving this event, the device will
3369         become essentially private again.
3370
3371         The event will only be sent to Management sockets other than the
3372         one through which the Unpair Device command was sent.
3373
3374
3375 Passkey Notify Event
3376 ====================
3377
3378         Event Code:             0x0017
3379         Controller Index:       <controller id>
3380         Event Parameters:       Address (6 Octets)
3381                                 Address_Type (1 Octet)
3382                                 Passkey (4 Octets)
3383                                 Entered (1 Octet)
3384
3385         This event is used to request passkey notification to the user.
3386         Unlike the other authentication events it does not need
3387         responding to using any Management command.
3388
3389         Possible values for the Address_Type parameter:
3390                 0       BR/EDR
3391                 1       LE Public
3392                 2       LE Random
3393
3394         The Passkey parameter indicates the passkey to be shown to the
3395         user whereas the Entered parameter indicates how many characters
3396         the user has entered on the remote side.
3397
3398
3399 New Identity Resolving Key Event
3400 ================================
3401
3402         Event Code:             0x0018
3403         Controller Index:       <controller id>
3404         Event Parameters:       Store_Hint (1 Octet)
3405                                 Random_Address (6 Octets)
3406                                 Key {
3407                                         Address (6 Octets)
3408                                         Address_Type (1 Octet)
3409                                         Value (16 Octets)
3410                                 }
3411
3412         This event indicates that a new identity resolving key has been
3413         generated for a remote device.
3414
3415         The Store_Hint parameter indicates whether the host is expected
3416         to store the key persistently or not.
3417
3418         The Random_Address provides the resolvable random address that
3419         was resolved into an identity. A value of 00:00:00:00:00:00
3420         indicates that the identity resolving key was provided for
3421         a public address or static random address.
3422
3423         Once this event has been send for a resolvable random address,
3424         all further events mapping this device will send out using the
3425         identity address information.
3426
3427         This event also indicates that now the identity address should
3428         be used for commands instead of the resolvable random address.
3429
3430         It is possible that some devices allow discovering via its
3431         identity address, but after pairing using resolvable private
3432         address only. In such a case Store_Hint will be 0x00 and the
3433         Random_Address will indicate 00:00:00:00:00:00. For these devices,
3434         the Privacy Characteristic of the remote GATT database should
3435         be consulted to decide if the identity resolving key must be
3436         stored persistently or not.
3437
3438         Devices using Set Privacy command with the option 0x02 would
3439         be such type of device.
3440
3441         Possible values for the Address_Type parameter:
3442                 0       Reserved (not in use)
3443                 1       LE Public
3444                 2       LE Random
3445
3446         The provided Address and Address_Type are the identity of
3447         a device. So either its public address or static random address.
3448
3449
3450 New Signature Resolving Key Event
3451 =================================
3452
3453         Event Code:             0x0019
3454         Controller Index:       <controller id>
3455         Event Parameters:       Store_Hint (1 Octet)
3456                                 Key {
3457                                         Address (6 Octets)
3458                                         Address_Type (1 Octet)
3459                                         Type (1 Octet)
3460                                         Value (16 Octets)
3461                                 }
3462
3463         This event indicates that a new signature resolving key has been
3464         generated for either the master or slave device.
3465
3466         The Store_Hint parameter indicates whether the host is expected
3467         to store the key persistently or not.
3468
3469         The Type parameter has the following possible values:
3470
3471                 0x00    Unauthenticated local CSRK
3472                 0x01    Unauthenticated remote CSRK
3473                 0x02    Authenticated local CSRK
3474                 0x03    Authenticated remote CSRK
3475
3476         The local keys are used for signing data to be sent to the
3477         remote device, whereas the remote keys are used to verify
3478         signatures received from the remote device.
3479
3480         The local signature resolving key will be generated with each
3481         pairing request. Only after receiving this event with the Type
3482         indicating a local key is it possible to use ATT Signed Write
3483         procedures.
3484
3485         Possible values for the Address_Type parameter:
3486                 0       Reserved (not in use)
3487                 1       LE Public
3488                 2       LE Random
3489
3490         The provided Address and Address_Type are the identity of
3491         a device. So either its public address or static random address.
3492
3493
3494 Device Added Event
3495 ==================
3496
3497         Event Code:             0x001a
3498         Controller Index:       <controller id>
3499         Event Parameters:       Address (6 Octets)
3500                                 Address_Type (1 Octet)
3501                                 Action (1 Octet)
3502
3503         This event indicates that a device has been added using the
3504         Add Device command.
3505
3506         Possible values for the Address_Type parameter:
3507                 0       BR/EDR
3508                 1       LE Public
3509                 2       LE Random
3510
3511         The event will only be sent to management sockets other than the
3512         one through which the command was sent.
3513
3514
3515 Device Removed Event
3516 ====================
3517
3518         Event Code:             0x001b
3519         Controller Index:       <controller id>
3520         Event Parameters:       Address (6 Octets)
3521                                 Address_Type (1 Octet)
3522
3523         This event indicates that a device has been removed using the
3524         Remove Device command.
3525
3526         Possible values for the Address_Type parameter:
3527                 0       BR/EDR
3528                 1       LE Public
3529                 2       LE Random
3530
3531         The event will only be sent to management sockets other than the
3532         one through which the command was sent.
3533
3534
3535 New Connection Parameter Event
3536 ==============================
3537
3538         Event Code:             0x001c
3539         Controller Index:       <controller id>
3540         Event Parameters:       Store_Hint (1 Octet)
3541                                 Param {
3542                                         Address (6 Octets)
3543                                         Address_Type (1 Octet)
3544                                         Min_Connection_Interval (2 Octets)
3545                                         Max_Connection_Interval (2 Octets)
3546                                         Connection_Latency (2 Octets)
3547                                         Supervision_Timeout (2 Octets)
3548                                 }
3549
3550         This event indicates a new set of connection parameters from
3551         a peripheral device.
3552
3553         The Store_Hint parameter indicates whether the host is expected
3554         to store this information persistently or not.
3555
3556         Possible values for the Address_Type parameter:
3557                 0       Reserved (not in use)
3558                 1       LE Public
3559                 2       LE Random
3560
3561         The Min_Connection_Interval, Max_Connection_Interval,
3562         Connection_Latency and Supervision_Timeout parameters are
3563         encoded as described in Core 4.1 spec, Vol 2, 7.7.65.3.
3564
3565
3566 Unconfigured Index Added Event
3567 ==============================
3568
3569         Event Code:             0x001d
3570         Controller Index:       <controller id>
3571         Event Parameters:
3572
3573         This event indicates that a new unconfigured controller has been
3574         added to the system. It is usually followed by a Read Controller
3575         Configuration Information command.
3576
3577         Only when a controller requires further configuration, it will
3578         be announced with this event. If it supports configuration, but
3579         does not require it, then an Index Added event will be used.
3580
3581         Once the Read Extended Controller Index List command has been
3582         used at least once, the Extended Index Added event will be
3583         send instead of this one.
3584
3585
3586 Unconfigured Index Removed Event
3587 ================================
3588
3589         Event Code:             0x001e
3590         Controller Index:       <controller id>
3591         Event Parameters:
3592
3593         This event indicates that an unconfigured controller has been
3594         removed from the system.
3595
3596         Once the Read Extended Controller Index List command has been
3597         used at least once, the Extended Index Removed event will be
3598         send instead of this one.
3599
3600
3601 New Configuration Options Event
3602 ===============================
3603
3604         Event Code:             0x001f
3605         Controller Index:       <controller id>
3606         Event Parameters:       Missing_Options (4 Octets)
3607
3608         This event indicates that one or more of the options for the
3609         controller configuration has changed.
3610
3611
3612 Extended Index Added Event
3613 ==========================
3614
3615         Event Code:             0x0020
3616         Controller Index:       <controller id>
3617         Event Parameters:       Controller_Type (1 Octet)
3618                                 Controller_Bus (1 Octet)
3619
3620         This event indicates that a new controller index has been
3621         added to the system.
3622
3623         This event will only be used after Read Extended Controller Index
3624         List has been used at least once. If it has not been used, then
3625         Index Added and Unconfigured Index Added are sent instead.
3626
3627
3628 Extended Index Removed Event
3629 ============================
3630
3631         Event Code:             0x0021
3632         Controller Index:       <controller id>
3633         Event Parameters:       Controller_Type (1 Octet)
3634                                 Controller_Bus (1 Octet)
3635
3636         This event indicates that an existing controller index has been
3637         removed from the system.
3638
3639         This event will only be used after Read Extended Controller Index
3640         List has been used at least once. If it has not been used, then
3641         Index Removed and Unconfigured Index Removed are sent instead.
3642
3643
3644 Local Out Of Band Extended Data Updated Event
3645 =============================================
3646
3647         Event Code:             0x0022
3648         Controller Index:       <controller id>
3649         Event Parameters:       Address_Type (1 Octet)
3650                                 EIR_Data_Length (2 Octets)
3651                                 EIR_Data (0-65535 Octets)
3652
3653         This event is used when the Read Local Out Of Band Extended Data
3654         command has been used and some other user requested a new set
3655         of local out-of-band data. This allows for the original caller
3656         to adjust the data.
3657
3658         Possible values for the Address_Type parameter are a bit-wise or
3659         of the following bits:
3660
3661                 0       BR/EDR
3662                 1       LE Public
3663                 2       LE Random
3664
3665         By combining these e.g. the following values are possible:
3666
3667                 1       BR/EDR
3668                 6       LE (public & random)
3669                 7       Reserved (not in use)
3670
3671         The value for EIR_Data_Length and content for EIR_Data is the
3672         same as described in Read Local Out Of Band Extended Data command.
3673
3674         When LE Privacy is used and LE Secure Connections out-of-band
3675         data has been requested, then this event will be emitted every
3676         time the Resolvable Private Address (RPA) gets changed. The new
3677         RPA will be included in the EIR_Data.
3678
3679         The event will only be sent to management sockets other than the
3680         one through which the command was sent. It will additionally also
3681         only be sent to sockets that have used the command at least once.
3682
3683
3684 Advertising Added Event
3685 =======================
3686
3687         Event Code:             0x0023
3688         Controller Index:       <controller id>
3689         Event Parameters:       Instance (1 Octet)
3690
3691         This event indicates that an advertising instance has been added
3692         using the Add Advertising command.
3693
3694         The event will only be sent to management sockets other than the
3695         one through which the command was sent.
3696
3697
3698 Advertising Removed Event
3699 =========================
3700
3701         Event Code:             0x0024
3702         Controller Index:       <controller id>
3703         Event Parameters:       Instance (1 Octet)
3704
3705         This event indicates that an advertising instance has been removed
3706         using the Remove Advertising command.
3707
3708         The event will only be sent to management sockets other than the
3709         one through which the command was sent.