X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fmgmt-api.txt;h=725e8ccb4c62ff217660f8f9c998077ef4d6e456;hb=363525157b8fe40ce1869811eb0754681fec3238;hp=51c9b469a0db886ef318fa793203fa7d28c015d2;hpb=869cd78529c9624e084af60a88c0a32ce585f0a1;p=framework%2Fconnectivity%2Fbluez.git diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt index 51c9b46..725e8cc 100644 --- a/doc/mgmt-api.txt +++ b/doc/mgmt-api.txt @@ -4,6 +4,92 @@ Bluetooth Management API Copyright (C) 2008-2009 Marcel Holtmann +Overview +======== + +This document describes the format of data used for communicating with +the kernel using a so-called Bluetooth Management sockets. These sockets +are available starting with Linux kernel version 3.4 + +The following kernel versions introduced new commands, new events or +important fixes to the Bluetooth Management API: + +Linux kernel v3.4 Version 1.0 +Linux kernel v3.5 Version 1.1 +Linux kernel v3.7 Version 1.2 +Linux kernel v3.9 Version 1.3 +Linux kernel v3.13 Version 1.4 +Linux kernel v3.15 Version 1.5 +Linux kernel v3.16 Version 1.6 +Linux kernel v3.17 Version 1.7 +Linux kernel v3.19 Version 1.8 + +Version 1.1 introduces Set Device ID command. + +Version 1.2 introduces Passkey Notify event. + +Version 1.3 does not introduce any new command or event. + +Version 1.4 introduces Set Advertising, Set BR/EDR, Set Static Address +and Set Scan Parameters commands. The existing Set Discoverable command +gained an extra setting for limited discoverable mode. The device name +is now provided in the scan response data for Low Energy. + +Version 1.5 introduces Set Secure Connections, Set Debug Keys, Set Privacy +and Load Identity Resolving Keys commands. It also introduces New Identity +Resolving Key and New Signature Resolving Key events. + +Version 1.6 introduces Get Connection Information command. It also updates +the Device Found event to combine advertising data and scan response data +into a single event. + +Version 1.7 introduces Get Clock Information, Add Device, Remove Device, +Load Connection Parameters, Read Unconfigured Index List, Read Controller +Configuration Information, Set External Configuration and Set Public Address +commands. It also introduces Device Added, Device Removed, New Connection +Parameter, Unconfigured Index Added, Unconfigured Index Removed and New +Configuration Options events. The existing Set Debug Keys command gained +an extra setting for enabling SSP debug mode. + +Version 1.8 introduces Start Service Discovery command. It also adds new +Long Term Key types for LE Secure Connection feature. + + +Example +======= + +The Bluetooth management sockets can be created by setting the hci_channel +member of struct sockaddr_hci to HCI_CHANNEL_CONTROL (3) when creating a +raw HCI socket. In C the needed code would look something like the following: + +int mgmt_create(void) +{ + struct sockaddr_hci addr; + int fd; + + fd = socket(PF_BLUETOOTH, SOCK_RAW | SOCK_CLOEXEC | SOCK_NONBLOCK, + BTPROTO_HCI); + if (fd < 0) + return -errno; + + memset(&addr, 0, sizeof(addr)); + addr.hci_family = AF_BLUETOOTH; + addr.hci_dev = HCI_DEV_NONE; + addr.hci_channel = HCI_CHANNEL_CONTROL; + + if (bind(fd, (struct sockaddr *) &addr, sizeof(addr)) < 0) { + int err = -errno; + close(fd); + return err; + } + + return fd; +} + +The process creating the mgmt socket is required to have the +CAP_NET_ADMIN capability (e.g. root would have this). + + Packet Structures ================= @@ -54,6 +140,15 @@ and Command Complete events: 0x0D Invalid Parameters 0x0E Disconnected 0x0F Not Powered +0x10 Cancelled +0x11 Invalid Index + +As a general rule all commands generate the events as specified below, +however invalid lengths or unknown commands will always generate a +Command Status response (with Unknown Command or Invalid Parameters +status). Sending a command with an invalid Controller Index value will +also always generate a Command Status event with the Invalid Index +status code. Read Management Version Information Command @@ -65,6 +160,11 @@ Read Management Version Information Command Return Parameters: Version (1 Octets) Revision (2 Octets) + This command returns the Management version and revision. + Besides, being informational the information can be used to + determine whether certain behavior has changed or bugs fixed + when interacting with the kernel. + This command generates a Command Complete event on success or a Command Status event on failure. @@ -84,6 +184,9 @@ Read Management Supported Commands Command Event2 (2 Octets) ... + This command returns the list of supported Management commands + and events. + The commands Read Management Version Information and Read management Supported Commands are not included in this list. Both commands are always supported and mandatory. @@ -104,6 +207,10 @@ Read Controller Index List Command Return Parameters: Num_Controllers (2 Octets) Controller_Index[i] (2 Octets) + This command returns the list of currently known controllers. + Controllers added or removed after calling this command can be + monitored using the Index Added and Index Removed events. + This command generates a Command Complete event on success or a Command Status event on failure. @@ -123,26 +230,55 @@ Read Controller Information Command Name (249 Octets) Short_Name (11 Octets) - If not short name is set the Short_Name parameter will be empty + This command is used to retreive the current state and basic + information of a controller. It is typically used right after + getting the response to the Read Controller Index List command + or an Index Added event. + + The Address parameter describes the controllers public address + and it can be expected that it is set. However in case of single + mode Low Energy only controllers it can be 00:00:00:00:00:00. To + power on the controller in this case, it is required to configure + a static address using Set Static Address command first. + + If the public address is set, then it will be used as identity + address for the controller. If no public address is available, + then the configured static address will be used as identity + address. + + In the case of a dual-mode controller with public address that + is configured as Low Energy only device (BR/EDR switched off), + the static address is used when set and public address otherwise. + + If no short name is set the Short_Name parameter will be empty (begin with a nul byte). - Current_Settings & Supported_Settings is a bitmask with + Current_Settings and Supported_Settings is a bitmask with currently the following available bits: - 1 Powered - 2 Connectable - 3 Fast Connectable - 4 Discoverable - 5 Pairable - 6 Link Level Security (Sec. mode 3) - 7 Secure Simple Pairing - 8 Basic Rate/Enhanced Data Rate - 9 High Speed - 10 Low Energy + 0 Powered + 1 Connectable + 2 Fast Connectable + 3 Discoverable + 4 Bondable + 5 Link Level Security (Sec. mode 3) + 6 Secure Simple Pairing + 7 Basic Rate/Enhanced Data Rate + 8 High Speed + 9 Low Energy + 10 Advertising + 11 Secure Connections + 12 Debug Keys + 13 Privacy + 14 Controller Configuration + 15 Static Address This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Set Powered Command =================== @@ -152,6 +288,10 @@ Set Powered Command Command Parameters: Powered (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to power on or off a controller. The + allowed Powered command parameter values are 0x00 and 0x01. All + other values will return Invalid Parameters. + If discoverable setting is activated with a timeout, then switching the controller off will expire this timeout and disable discoverable. @@ -159,6 +299,10 @@ Set Powered Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Invalid Parameters + Invalid Index + Set Discoverable Command ======================== @@ -169,21 +313,43 @@ Set Discoverable Command Timeout (2 Octets) Return Parameters: Current_Settings (4 Octets) + This command is used to set the discoverable property of a + controller. The allowed Discoverable command parameter values + are 0x00, 0x01 and 0x02. All other values will return Invalid + Parameters. + Timeout is the time in seconds and is only meaningful when - Discoverable is set to 1. + Discoverable is set to 0x01 or 0x02. Providing a timeout + with 0x00 return Invalid Parameters. For 0x02, the timeout + value is required. + + The value 0x00 disables discoverable, the value 0x01 enables + general discoverable and the value 0x02 enables limited + discoverable. + + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). It will return Not Supported + otherwise. This command can be used when the controller is not powered and all settings will be programmed once powered. However using a timeout when the controller is not powered will - return an error. + return Not Powered error. When switching discoverable on and the connectable setting is - off it will return an error. + off it will return Rejected error. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Rejected + Not Supported + Invalid Parameters + Not Powered + Invalid Index + Set Connectable Command ======================= @@ -193,6 +359,19 @@ Set Connectable Command Command Parameters: Connectable (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to set the connectable property of a + controller. The allowed Connectable command parameter values are + 0x00 and 0x01. All other values will return Invalid Parameters. + + This command is available for BR/EDR, LE-only and also dual + mode controllers. For BR/EDR is changes the page scan setting + and for LE controllers it changes the advertising type. For + dual mode controllers it affects both settings. + + For LE capable controllers the connectable setting takes affect + when advertising is enabled (peripheral) or when directed + advertising events are received (central). + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -204,9 +383,17 @@ Set Connectable Command When switching connectable off, it will expire a discoverable setting with a timeout. + This setting does not affect known devices from Add Device + command. These devices are always allowed to connect. + This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + Set Fast Connectable Command ============================ @@ -216,27 +403,53 @@ Set Fast Connectable Command Command Parameters: Enable (1 Octet) Return Parameters: Current_Settings (4 Octets) - This command can be used when the controller is not powered and - all settings will be programmed once powered. + This command is used to set the controller into a connectable + state where the page scan parameters have been set in a way to + favor faster connect times with the expense of higher power + consumption. - If connectable is not set, then this command will fail. + The allowed values of the Enable command parameter are 0x00 and + 0x01. All other values will return Invalid Parameters. + + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). It will return Not Supported + otherwise. + + This command can only be used when the controller is powered on + and will return Not Powerd otherwise. + + If connectable is not set, then this command will fail with + Rejected error. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Failed + Busy + Rejected + Not Supported + Invalid Parameters + Not Powered + Invalid Index + -Set Pairable Command +Set Bondable Command ==================== Command Code: 0x0009 Controller Index: - Command Parameters: Pairable (1 Octet) + Command Parameters: Bondable (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to set the bondable property of an + controller. The allowed values for the Bondable command + parameter are 0x00 and 0x01. All other values will return + Invalid Parameters. + This command can be used when the controller is not powered and all settings will be programmed once powered. - Turning pairable on will not automatically switch the controller + Turning bondable on will not automatically switch the controller into connectable mode. That needs to be done separately. The setting will be remembered during power down/up toggles. @@ -244,6 +457,9 @@ Set Pairable Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Set Link Security Command ========================= @@ -253,12 +469,26 @@ Set Link Security Command Command Parameters: Link_Security (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to either enable or disable link level + security for an controller (also known as Security Mode 3). The + allowed values for the Link_Security command parameter are 0x00 + and 0x01. All other values will return Invalid Parameters. + + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). It will return Not Supported + otherwise. + This command can be used when the controller is not powered and all settings will be programmed once powered. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + Set Secure Simple Pairing Command ================================= @@ -268,15 +498,28 @@ Set Secure Simple Pairing Command Command Parameters: Secure_Simple_Pairing (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to enable/disable Secure Simple Pairing + support for a controller. The allowed values for the + Secure_Simple_Pairing command parameter are 0x00 and 0x01. All + other values will return Invalid Parameters. + + This command is only available for BR/EDR capable controllers + supporting the core specification version 2.1 or greater + (e.g. not for single-mode LE controllers or pre-2.1 ones). + This command can be used when the controller is not powered and all settings will be programmed once powered. In case the controller does not support Secure Simple Pairing, - the command will fail regardless. + the command will fail regardless with Not Supported error. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index Set High Speed Command ====================== @@ -286,15 +529,33 @@ Set High Speed Command Command Parameters: High_Speed (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to enable/disable Bluetooth High Speed + support for a controller. The allowed values for the High_Speed + command parameter are 0x00 and 0x01. All other values will + return Invalid Parameters. + + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). + This command can be used when the controller is not powered and all settings will be programmed once powered. - In case the kernel subsystem does not support High Speed, the - command will fail regardless. + To enable High Speed support, it is required that Secure Simple + Pairing support is enabled first. High Speed support is not + possible for connections without Secure Simple Pairing. + + When switching Secure Simple Pairing off, the support for High + Speed will be switched off as well. Switching Secure Simple + Pairing back on, will not re-enable High Speed support. That + needs to be done manually. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Not Supported + Invalid Parameters + Invalid Index + Set Low Energy Command ====================== @@ -304,6 +565,14 @@ Set Low Energy Command Command Parameters: Low_Energy (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to enable/disable Low Energy support for a + controller. The allowed values of the Low_Energy command + parameter are 0x00 and 0x01. All other values will return + Invalid Parameters. + + This command is only available for LE capable controllers and + will yield in a Not Supported error otherwise. + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -313,6 +582,11 @@ Set Low Energy Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + Set Device Class ================ @@ -323,9 +597,15 @@ Set Device Class Minor_Class (1 Octet) Return Parameters: Class_Of_Device (3 Octets) + This command is used to set the major and minor device class for + BR/EDR capable controllers. + This command will also implicitly disable caching of pending CoD and EIR updates. + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -336,6 +616,11 @@ Set Device Class This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + Set Local Name Command ====================== @@ -347,6 +632,10 @@ Set Local Name Command Return Parameters: Name (249 Octets) Short_Name (11 Octets) + This command is used to set the local name of a controller. The + command parameters also include a short name which will be used + in case the full name doesn't fit within EIR/AD data. + The name parameters need to always end with a null byte (failure to do so will cause the command to fail). @@ -361,6 +650,9 @@ Set Local Name Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Add UUID Command ================ @@ -371,6 +663,11 @@ Add UUID Command SVC_Hint (1 Octet) Return Parameters: Class_Of_Device (3 Octets) + This command is used to add a UUID to be published in EIR data. + The accompanied SVC_Hint parameter is used to tell the kernel + whether the service class bits of the Class of Device value need + modifying due to this UUID. + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -381,6 +678,10 @@ Add UUID Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Invalid Parameters + Invalid Index + Remove UUID Command =================== @@ -390,6 +691,9 @@ Remove UUID Command Command Parameters: UUID (16 Octets) Return Parameters: Class_Of_Device (3 Octets) + This command is used to remove a UUID previously added using the + Add UUID command. + When the UUID parameter is an empty UUID (16 x 0x00), then all previously loaded UUIDs will be removed. @@ -403,6 +707,10 @@ Remove UUID Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Busy + Invalid Parameters + Invalid Index + Load Link Keys Command ====================== @@ -422,36 +730,99 @@ Load Link Keys Command ... Return Parameters: + This command is used to feed the kernel with currently known + link keys. The command does not need to be called again upon the + receiption of New Link Key events since the kernel updates its + list automatically. + + The Debug_Keys parameter is used to tell the kernel whether to + accept the usage of debug keys or not. The allowed values for + this parameter are 0x00 and 0x01. All other values will return + an Invalid Parameters response. + + Usage of the Debug_Keys parameter is deprecated and has been + replaced with the Set Debug Keys command. When setting the + Debug_Keys option via Load Link Keys command it has the same + affect as setting it via Set Debug Keys and applies to all + keys in the system. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 Reserved (not in use) + 2 Reserved (not in use) + + Public and random LE addresses are not valid and will be rejected. + + Currently defined Key_Type values are: + + 0x00 Combination key + 0x01 Local Unit key + 0x02 Remote Unit key + 0x03 Debug Combination key + 0x04 Unauthenticated Combination key from P-192 + 0x05 Authenticated Combination key from P-192 + 0x06 Changed Combination key + 0x07 Unauthenticated Combination key from P-256 + 0x08 Authenticated Combination key from P-256 + This command can be used when the controller is not powered. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Load Long Term Keys Command =========================== Command Code: 0x0013 Controller Index: - Command Parameters: Key Count (2 Octets) + Command Parameters: Key_Count (2 Octets) Key1 { Address (6 Octets) Address_Type (1 Octet) - Authenticated (1 Octet) + Key_Type (1 Octet) Master (1 Octet) - Encryption Size (1 Octet) - Enc. Diversifier (2 Octets) - Random Number (8 Octets) + Encryption_Size (1 Octet) + Encryption_Diversifier (2 Octets) + Random_Number (8 Octets) Value (16 Octets) } Key2 { } ... + Return Parameters: + + This command is used to feed the kernel with currently known + (SMP) Long Term Keys. The command does not need to be called + again upon the receiption of New Long Term Key events since the + kernel updates its list automatically. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. + + Unresolvable random addresses and resolvable random addresses are + not valid and will be rejected. + + Currently defined Key_Type values are: + + 0x00 Unauthenticated key + 0x01 Authenticated key This command can be used when the controller is not powered. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Disconnect Command ================== @@ -463,11 +834,25 @@ Disconnect Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to force the disconnection of a currently + connected device. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Busy + Invalid Parameters + Not Powered + Invalid Index + Get Connections Command ======================= @@ -483,16 +868,27 @@ Get Connections Command Address2 { } ... + This command is used to retreive a list of currently connected + devices. + Possible values for the Address_Type parameter: 0 BR/EDR 1 LE Public 2 LE Random + For devices using resolvable random addresses with a known + identity resolving key, the Address and Address_Type will + contain the identity information. + This command can only be used when the controller is powered. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Not Powered + Invalid Index + PIN Code Reply Command ======================= @@ -506,11 +902,23 @@ PIN Code Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to respond to a PIN Code request event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + PIN Code Negative Reply Command =============================== @@ -522,11 +930,24 @@ PIN Code Negative Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to return a negative response to a PIN Code + Request event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + Set IO Capability Command ========================= @@ -536,11 +957,28 @@ Set IO Capability Command Command Parameters: IO_Capability (1 Octet) Return Parameters: + This command is used to set the IO Capability used for pairing. + The command accepts both SSP and SMP values. + + Possible values for the IO_Capability parameter: + 0 DisplayOnly + 1 DisplayYesNo + 2 KeyboardOnly + 3 NoInputNoOutput + 4 KeyboardDisplay + + Passing a value 4 (KeyboardDisplay) will cause the kernel to + convert it to 1 (DisplayYesNo) in the case of a BR/EDR + connection (as KeyboardDisplay is specific to SMP). + This command can be used when the controller is not powered. This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index + Pair Device Command =================== @@ -553,19 +991,59 @@ Pair Device Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to trigger pairing with a remote device. + The IO_Capability command parameter is used to temporarily (for + this pairing event only) override the global IO Capaility (set + using the Set IO Capability command). + Possible values for the Address_Type parameter: 0 BR/EDR 1 LE Public 2 LE Random + Possible values for the IO_Capability parameter: + 0 DisplayOnly + 1 DisplayYesNo + 2 KeyboardOnly + 3 NoInputNoOutput + 4 KeyboardDisplay + + Passing a value 4 (KeyboardDisplay) will cause the kernel to + convert it to 1 (DisplayYesNo) in the case of a BR/EDR + connection (as KeyboardDisplay is specific to SMP). + + The Address and Address_Type of the return parameters will + return the identity address if known. In case of resolvable + random address given as command parameters and the remote + provides an identity resolving key, the return parameters + will provide the resolved address. + + To allow tracking of which resolvable random address changed + into which identity address, the New Identity Resolving Key + event will be send before receiving Command Complete event + for this command. + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Reject status is used when requested transport is not enabled. -Cancel Pair Device -================== + Not Supported status is used if controller is not capable with + requested transport. + + Possible errors: Rejected + Not Supported + Connect Failed + Busy + Invalid Parameters + Not Powered + Invalid Index + + +Cancel Pair Device Command +========================== Command Code: 0x001A Controller Index: @@ -577,11 +1055,20 @@ Cancel Pair Device The Address and Address_Type parameters should match what was given to a preceding Pair Device command. + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Invalid Parameters + Not Powered + Invalid Index + Unpair Device Command ===================== @@ -596,16 +1083,34 @@ Unpair Device Command Removes all keys associated with the remote device. + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + The Disconnect parameter tells the kernel whether to forcefully disconnect any existing connections to the device. It should in practice always be 1 except for some special GAP qualification test-cases where a key removal without disconnecting is needed. + When unpairing a device its link key, long term key and if + provided identity resolving key will be purged. + + For devices using resolvable random addresses where the identity + resolving key was available, after this command they will now no + longer be resolved. The device will essentially become private + again. + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Paired + Invalid Parameters + Not Powered + Invalid Index + User Confirmation Reply Command =============================== @@ -617,11 +1122,24 @@ User Confirmation Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to respond to a User Confirmation Request + event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + User Confirmation Negative Reply Command ======================================== @@ -633,11 +1151,24 @@ User Confirmation Negative Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to return a negative response to a User + Confirmation Request event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + User Passkey Reply Command ========================== @@ -650,11 +1181,24 @@ User Passkey Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to respond to a User Confirmation Passkey + Request event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + User Passkey Negative Reply Command =================================== @@ -666,11 +1210,24 @@ User Passkey Negative Reply Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to return a negative response to a User + Passkey Request event. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Not Connected + Invalid Parameters + Not Powered + Invalid Index + Read Local Out Of Band Data Command =================================== @@ -678,14 +1235,32 @@ Read Local Out Of Band Data Command Command Code: 0x0020 Controller Index: Command Parameters: - Return Parameters: Hash (16 Octets) - Randomizer (16 Octets) + Return Parameters: Hash_192 (16 Octets) + Randomizer_192 (16 Octets) + Hash_256 (16 Octets, Optional) + Randomizer_256 (16 Octets, Optional) + + This command is used to read the local Out of Band data. This command can only be used when the controller is powered. + If Secure Connections support is enabled, then this command + will return P-192 versions of hash and randomizer as well as + P-256 versions of both. + + Values returned by this command become invalid when the controller + is powered down. After each power-cycle it is required to call + this command again to get updated values. + This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Not Supported + Busy + Invalid Parameters + Not Powered + Invalid Index + Add Remote Out Of Band Data Command =================================== @@ -694,16 +1269,62 @@ Add Remote Out Of Band Data Command Controller Index: Command Parameters: Address (6 Octets) Address_Type (1 Octet) - Hash (16 Octets) - Randomizer (16 Octets) + Hash_192 (16 Octets) + Randomizer_192 (16 Octets) + Hash_256 (16 Octets, Optional) + Randomizer_256 (16 Octets, Optional) Return Parameters: Address (6 Octets) Address_Type (1 Octet) - This command can only be used when the controller is powered. + This command is used to provide Out of Band data for a remote + device. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + Provided Out Of Band data is persistent over power down/up toggles. + + This command also accept optional P-256 versions of hash and + randomizer. If they are not provided, then they are set to + zero value. + + The P-256 versions of both can also be provided when the + support for Secure Connections is not enabled. However in + that case they will never be used. + + To only provide the P-256 versions of hash and randomizer, + it is valid to leave both P-192 fields as zero values. If + Secure Connections is disabled, then of course this is the + same as not providing any data at all. + + When providing data for remote LE devices, then the Hash_192 field + is used to provide the Security Manager TK Value. The Randomizer_192 + field is not used and shall be set to zero. The Hash_192 value can + also be set to zero and that means that no Out Of Band data for + LE legacy pairing is provided. + + The Hash_256 and Randomizer_256 fields can be used for LE secure + connections Out Of Band data. If only LE secure connections data + is provided the Hash_P192 and Randomizer_P192 fields can be set + to zero. + + If Secure Connections Only mode has been enabled, then providing + Hash_P192 and Randomizer_P192 is not allowed. They are required + to be set to zero values. + + This command can be used when the controller is not powered and + all settings will be programmed once powered. This command generates a Command Complete event on success or failure. + Possible errors: Failed + Invalid Parameters + Not Powered + Invalid Index + Remove Remote Out Of Band Data Command ====================================== @@ -715,11 +1336,27 @@ Remove Remote Out Of Band Data Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) - This command can only be used when the controller is powered. + This command is used to remove data added using the Add Remote + Out Of Band Data command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + When the Address parameter is 00:00:00:00:00:00, then all + previously added data will be removed. + + This command can be used when the controller is not powered and + all settings will be programmed once powered. This command generates a Command Complete event on success or failure. + Possible errors: Invalid Parameters + Not Powered + Invalid Index + Start Discovery Command ======================= @@ -729,12 +1366,16 @@ Start Discovery Command Command Parameters: Address_Type (1 Octet) Return Parameters: Address_Type (1 Octet) + This command is used to start the process of discovering remote + devices. A Device Found event will be sent for each discovered + device. + Possible values for the Address_Type parameter are a bit-wise or of the following bits: - 1 BR/EDR - 2 LE Public - 3 LE Random + 0 BR/EDR + 1 LE Public + 2 LE Random By combining these e.g. the following values are possible: @@ -747,6 +1388,12 @@ Start Discovery Command This command generates a Command Complete event on success or failure. + Possible errors: Busy + Not Supported + Invalid Parameters + Not Powered + Invalid Index + Stop Discovery Command ====================== @@ -756,11 +1403,18 @@ Stop Discovery Command Command Parameters: Address_Type (1 Octet) Return Parameters: Address_Type (1 Octet) + This command is used to stop the discovery process started using + the Start Discovery command. + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Rejected + Invalid Parameters + Invalid Index + Confirm Name Command ==================== @@ -777,11 +1431,25 @@ Confirm Name Command expected for each Device Found event with the Confirm Name flag set. + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The Name_Known parameter should be set to 0x01 if user space + knows the name for the device and 0x00 if it doesn't. If set to + 0x00 the kernel will perform a name resolving procedure for the + device in question. + This command can only be used when the controller is powered. This command generates a Command Complete event on success or failure. + Possible errors: Failed + Invalid Parameters + Invalid Index + Block Device Command ==================== @@ -793,11 +1461,33 @@ Block Device Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to add a device to the list of devices + which should be blocked from being connect to the local + controller. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + For Low Energy devices, the blocking of a device take presedence + over auto-connection actions provided by Add Device. Blocked + devices will not be auto-connected or even reported when found + during background scanning. If the controller is connectable + direct advertising from blocked devices will also be ignored. + + Connections created from advertising of the controller will + be dropped if the device is blocked. + This command can be used when the controller is not powered. This command generates a Command Complete event on success or failure. + Possible errors: Failed + Invalid Parameters + Invalid Index + Unblock Device Command ====================== @@ -809,11 +1499,25 @@ Unblock Device Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to remove a device from the list of blocked + devices (where it was added to using the Block Device command). + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + When the Address parameter is 00:00:00:00:00:00, then all + previously blocked devices will be unblocked. + This command can be used when the controller is not powered. This command generates a Command Complete event on success or failure. + Possible errors: Invalid Parameters + Invalid Index + Set Device ID Command ===================== @@ -844,165 +1548,1215 @@ Set Device ID Command This command generates a Command Complete event on success or a Command Status event on failure. + Possible errors: Invalid Parameters + Invalid Index -Command Complete Event -====================== -Event Code 0x0001 -Controller Index: or -Event Parameters Command_Opcode (2 Octets) - Status (1 Octet) - Return_Parameters +Set Advertising Command +======================= + Command Code: 0x0029 + Controller Index: + Command Parameters: Advertising (1 Octet) + Return Parameters: Current_Settings (4 Octets) -Command Status Event -==================== + This command is used to enable LE advertising on a controller + that supports it. The allowed values for the Advertising + command parameter are 0x00 and 0x01. All other values will + return Invalid Parameters. -Event Code 0x0002 -Controller Index: or -Event Parameters Command_Opcode (2 Octets) - Status (1 Octet) + A pre-requisite is that LE is already enabled, otherwise + this command will return a "rejected" response. + This command generates a Command Complete event on success or a + Command Status event on failure. -Controller Error Event -====================== + Possible errors: Busy + Rejected + Not Supported + Invalid Parameters + Invalid Index -Event Code 0x0003 -Controller Index: -Event Parameters Error_Code (1 Octet) +Set BR/EDR Command +================== -Index Added Event -================= + Command Code: 0x002A + Controller Index: + Command Parameters: BR/EDR (1 Octet) + Return Parameters: Current_Settings (4 Octets) -Event Code 0x0004 -Controller Index: -Event Parameters + This command is used to enable or disable BR/EDR support + on a dual-mode controller. The allowed values for the Advertising + command parameter are 0x00 and 0x01. All other values will + return Invalid Parameters. + A pre-requisite is that LE is already enabled, otherwise + this command will return a "rejected" response. Enabling BR/EDR + can be done both when powered on and powered off, however + disabling it can only be done when powered off (otherwise the + command will again return "rejected"). Disabling BR/EDR will + automatically disable all other BR/EDR related settings. -Index Removed Event + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Busy + Rejected + Not Supported + Invalid Parameters + Invalid Index + + +Set Static Address Command +========================== + + Command Code: 0x002B + Controller Index: + Command Parameters: Address (6 Octets) + Return Parameters: Current_Settings (4 Octets) + + This command allows for setting the static random address. It is + only supported on controllers with LE support. The static random + address is suppose to be valid for the lifetime of the + controller or at least until the next power cycle. To ensure + such behavior, setting of the address is limited to when the + controller is powered off. + + The special BDADDR_ANY address (00:00:00:00:00:00) can be used + to disable the static address. + + When a controller has a public address (which is required for + all dual-mode controllers), this address is not used. If a dual-mode + controller is configured as Low Energy only devices (BR/EDR has + been switched off), then the static address is used. Only when + the controller information reports BDADDR_ANY (00:00:00:00:00:00), + it is required to configure a static address first. + + If privacy mode is enabled and the controller is single mode + LE only without a public address, the static random address is + used as identity address. + + The Static Address flag from the current settings can also be used + to determine if the configured static address is in use or not. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Rejected + Not Supported + Invalid Parameters + Invalid Index + + +Set Scan Parameters Command +=========================== + + Command Code: 0x002C + Controller Index: + Command Parameters: Interval (2 Octets) + Window (2 Octets) + Return Parameters: + + This command allows for setting the Low Energy scan parameters + used for connection establishment and passive scanning. It is + only supported on controllers with LE support. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Rejected + Not Supported + Invalid Parameters + Invalid Index + + +Set Secure Connections Command +============================== + + Command Code: 0x002D + Controller Index: + Command Parameters: Secure_Connections (1 Octet) + Return Parameters: Current_Settings (4 Octets) + + This command is used to enable/disable Secure Connections + support for a controller. The allowed values for the + Secure_Connections command parameter are 0x00, 0x01 and 0x02. + All other values will return Invalid Parameters. + + The value 0x00 disables Secure Connections, the value 0x01 + enables Secure Connections and the value 0x02 enables Secure + Connections Only mode. + + This command is only available for LE capable controllers as + well as controllers supporting the core specification version + 4.1 or greater. + + This command can be used when the controller is not powered and + all settings will be programmed once powered. + + In case the controller does not support Secure Connections + the command will fail regardless with Not Supported error. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + + +Set Debug Keys Command +====================== + + Command Code: 0x002E + Controller Index: + Command Parameters: Debug_Keys (1 Octet) + Return Parameters: Current_Settings (4 Octets) + + This command is used to tell the kernel whether to accept the + usage of debug keys or not. The allowed values for this parameter + are 0x00, 0x01 and 0x02. All other values will return an Invalid + Parameters response. + + With a value of 0x00 any generated debug key will be discarded + as soon as the connection terminates. + + With a value of 0x01 generated debug keys will be kept and can + be used for future connections. However debug keys are always + marked as non persistent and should not be stored. This means + a reboot or changing the value back to 0x00 will delete them. + + With a value of 0x02 generated debug keys will be kept and can + be used for future connections. This has the same affect as + with value 0x01. However in addition this value will also + enter the controller mode to generate debug keys for each + new pairing. Changing the value back to 0x01 or 0x00 will + disable the controller mode for generating debug keys. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + + +Set Privacy Command +=================== + + Command Code: 0x002F + Controller Index: + Command Parameters: Privacy (1 Octet) + Identity_Resolving_Key (16 Octets) + Return Parameters: Current_Settings (4 Octets) + + This command is used to enable Low Energy Privacy feature using + resolvable private addresses. + + The value 0x00 disables privacy mode, the values 0x01 and 0x02 + enable privacy mode. + + With value 0x01 the kernel will always use the privacy mode. This + means resolvable private address is used when the controller is + discoverable and also when pairing is initiated. + + With value 0x02 the kernel will use privacy mode with resolvable + private address. In case the conroller is bondable and discoverable + the identity address is used. Also when pairing is initiated, the + connection will be established with the identity address. + + Exposing the identity address when bondable and discoverable or + during initated pairing can be a privacy issue. For dual-mode + controllers this can be neglected since its public address will + be exposed over BR/EDR anyway. The benefit of exposing the + identity address for pairing purposes is that it makes matching + up devices with dual-mode topology during device discovery now + possible. + + If the privacy value 0x02 is used, then also the GATT database + should expose the Privacy Characteristic so that remote devices + can determine if the privacy feature is in use or not. + + When the controller has a public address (mandatory for dual-mode + controllers) it is used as identity address. In case the controller + is single mode LE only without a public address, it is required + to configure a static random andress first. The privacy mode can + only be enabled when an identity address is available. + + The Identity_Resolving_Key is the local key assigned for the local + resolvable private address. + + Possible errors: Busy + Not Supported + Invalid Parameters + Invalid Index + + +Load Identity Resolving Keys Command +==================================== + + Command Code: 0x0030 + Controller Index: + Command Parameters: Key_Count (2 Octets) + Key1 { + Address (6 Octets) + Address_Type (1 Octet) + Value (16 Octets) + } + Key2 { } + ... + Return Parameters: + + This command is used to feed the kernel with currently known + identity resolving keys. The command does not need to be called + again upon the receiption of New Identity Resolving Key events + since the kernel updates its list automatically. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. + + Unresolvable random addresses and resolvable random addresses are + not valid and will be rejected. + + This command can be used when the controller is not powered. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Invalid Parameters + Invalid Index + +#ifdef __TIZEN_PATCH__ +Generate Identity Resolving Key Command +======================================= + + Command Code: 0x00F6 + Controller Index: + Command Parameters: + Return Parameters: + + This command is used to generate identity resolving key for the + local device, which will be used at the time of pairing for key + distribution and to generate resolvable private address for local device. + + This command generates a Command Complete event on success + or a Command Status event on failure. + + Possible errors: Failed + Invalid Index + +Generate Resolvable Private Address Command +======================================= + + Command Code: 0x00F5 + Controller Index: + Command Parameters: + Return Parameters: Resolvable Private Address (6 Octets) + + This command is used to generate resolvable private address for the + local device when LE privacy is supported and device is having its IRK. + + This command returns generated private address which is resolvable + by remote device on success. + + This command generates a Command Complete event on success + or a Command Status event on failure. + + Possible errors: Failed + Invalid Index + +Set Random Address Command +========================== + + Command Code: 0x00F4 + Controller Index: + Command Parameters: Resolvable Private Address (6 Octets) + Return Parameters: + + This command is used to set the random address to local controller. + If local device supports LE Privacy then this command will be called to set + its Random address while active scanning remote devices and in the case of + advertising itself. + + This command intern calls the HCI Set Random address command from kernel + space to set the RPA to controller. + + This command generates a Command Complete event on success + or a Command Status event on failure. + + Possible errors: Failed + Invalid Index + +#endif + +Get Connection Information Command +================================== + + Command Code: 0x0031 + Controller Index: + Command Parameters: Address (6 Octets) + Address_Type (1 Octet) + Return Parameters: Address (6 Octets) + Address_Type (1 Octet) + RSSI (1 Octet) + TX_Power (1 Octet) + Max_TX_Power (1 Octet) + + This command is used to get connection information. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + TX_Power and Max_TX_Power can be set to 127 if values are invalid or + unknown. A value of 127 for RSSI indicates that it is not available. + + This command generates a Command Complete event on success and + on failure. In case of failure only Address and Address_Type fields + are valid and values of remaining parameters are considered invalid + and shall be ignored. + + Possible errors: Not Connected + Not Powered + Invalid Parameters + Invalid Index + + +Get Clock Information Command +============================= + + Command Code: 0x0032 + Controller Index: + Command Parameters: Address (6 Octets) + Address_Type (1 Octet) + Return Parameters: Address (6 Octets) + Address_Type (1 Octet) + Local_Clock (4 Octets) + Piconet_Clock (4 Octets) + Accuracy (2 Octets) + + This command is used to get local and piconet clock information. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 Reserved (not in use) + 2 Reserved (not in use) + + The Accuracy can be set to 0xffff which means the value is unknown. + + If the Address is set to 00:00:00:00:00:00, then only the + Local_Clock field has a valid value. The Piconet_Clock and + Accuracy fields are invalid and shall be ignored. + + This command generates a Command Complete event on success and + on failure. In case of failure only Address and Address_Type fields + are valid and values of remaining parameters are considered invalid + and shall be ignored. + + Possible errors: Not Connected + Not Powered + Invalid Parameters + Invalid Index + + +Add Device Command +================== + + Command Code: 0x0033 + Controller Index: + Command Parameters: Address (6 Octets) + Address_Type (1 Octet) + Action (1 Octet) + Return Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This command is used to add a device to the action list. The + action list allows scanning for devices and enables incoming + connections from known devices. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + Possible values for the Action parameter: + 0 Background scan for device + 1 Allow incoming connection + 2 Auto-connect remote device + + With the Action 0, when the device is found, a new Device Found + event will be send indicating this device is available. This + action is only valid for LE Public and LE Random address types. + + With the Action 1, the device is allowed to connect. For BR/EDR + address type this means an incoming connection. For LE Public + and LE Random address types, a connection will be established + to devices using directed advertising. If successful a Device + Connected event will be send. + + With the Action 2, when the device is found, it will be connected + and if successful a Device Connected event will be send. This + action is only valid for LE Public and LE Random address types. + + When a device is blocked using Block Device command, then it is + valid to add the device here, but all actions will be ignored + until the device is unblocked. + + Devices added with Action 1 are allowed to connect even if the + connectable setting is off. This acts as list of known trusted + devices. + + This command can be used when the controller is not powered and + all settings will be programmed once powered. + + This command generates a Command Complete event on success + or failure. + + Possible errors: Failed + Invalid Parameters + Invalid Index + + +Remove Device Command +===================== + + Command Code: 0x0034 + Controller Index: + Command Parameters: Address (6 Octets) + Address_Type (1 Octet) + Return Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This command is used to remove a device from the action list + previously added by using the Add Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + When the Address parameter is 00:00:00:00:00:00, then all + previously added devices will be removed. + + This command can be used when the controller is not powered and + all settings will be programmed once powered. + + This command generates a Command Complete event on success + or failure. + + Possible errors: Invalid Parameters + Invalid Index + + +Load Connection Parameters Command +================================== + + Command Code: 0x0035 + Controller Index: + Command Parameters: Param_Count (2 Octets) + Param1 { + Address (6 Octets) + Address_Type (1 Octet) + Min_Connection_Interval (2 Octets) + Max_Connection_Interval (2 Octes) + Connection_Latency (2 Octets) + Supervision_Timeout (2 Octets) + } + Param2 { } + ... + Return Parameters: + + This command is used to load connection parameters from several + devices into kernel. Currently this is only supported on controllers + with Low Energy support. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. + + The Min_Connection_Interval, Max_Connection_Interval, + Connection_Latency and Supervision_Timeout parameters should + be configured as described in Core 4.1 spec, Vol 2, 7.8.12. + + This command can be used when the controller is not powered. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Invalid Parameters + Invalid Index + Not Supported + + +Read Unconfigured Controller Index List Command +=============================================== + + Command Code: 0x0036 + Controller Index: + Command Parameters: + Return Parameters: Num_Controllers (2 Octets) + Controller_Index[i] (2 Octets) + + This command returns the list of currently unconfigured controllers. + Unconfigured controllers added after calling this command can be + monitored using the Unconfigured Index Added event. + + An unconfigured controller can either move to a configured state + by indicating Unconfigured Index Removed event followed by an + Index Added event; or it can be removed from the system which + would be indicated by the Unconfigured Index Removed event. + + Only controllers that require configuration will be listed with + this command. A controller that is fully configured will not + be listed even if it supports configuration changes. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + +Read Controller Configuration Information Command +================================================= + + Command Code: 0x0037 + Controller Index: + Command Parameters: + Return Parameters: Manufacturer (2 Octets) + Supported_Options (4 Octets) + Missing_Options (4 Octets) + + This command is used to retreive the supported configuration + options of a controller and the missing configuration options. + + The missing options are required to be configured before the + controller is considered fully configured and ready for standard + operation. The command is typically used right after getting the + response to Read Unconfigured Controller Index List command or + Unconfigured Index Added event. + + Supported_Options and Missing_Options is a bitmask with currently + the following available bits: + + 0 External configuration + 1 Bluetooth public address configuration + + It is valid to call this command on controllers that do not + require any configuration. It is possible that a fully configured + controller offers additional support for configuration. + + For example a controller may contain a valid Bluetooth public + device address, but also allows to configure it from the host + stack. In this case the general support for configurations will + be indicated by the Controller Configuration settings. For + controllers where no configuration options are available that + setting option will not be present. + + When all configurations have been completed and as a result the + Missing_Options mask would become empty, then the now ready + controller will be announced via Index Added event. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Invalid Parameters + Invalid Index + + +Set External Configuration Command +================================== + + Command Code: 0x0038 + Controller Index: + Command Parameters: Configuration (1 Octet) + Return Parameters: Missing_Options (4 Octets) + + This command allows to change external configuration option to + indicate that a controller is now configured or unconfigured. + + The value 0x00 sets unconfigured state and the value 0x01 sets + configured state of the controller. + + It is not mandatory that this configuration option is provided + by a controller. If it is provided, the configuration has to + happen externally using user channel operation or via vendor + specific methods. + + Setting this option and when Missing_Options returns zero, this + means that the controller will switch to configured state and it + can be expected that it will be announced via Index Added event. + + Wrongly configured controllers might still cause an error when + trying to power them via Set Powered commmand. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Rejected + Not Supported + Invalid Parameters + Invalid Index + + +Set Public Address Command +========================== + + Command Code: 0x0039 + Controller Index: + Command Parameters: Address (6 Octets) + Return Parameters: Missing_Options (4 Octets) + + This command allows configuration of public address. Since a vendor + specific procedure is required, this command might not be supported + by all controllers. Actually most likely only a handful embedded + controllers will offer support for this command. + + When the support for Bluetooth public address configuration is + indicated in the supported options mask, then this command + can be used to configure the public address. + + It is only possible to configure the public address when the + controller is powered off. + + For an unconfigured controller and when Missing_Options returns + an empty mask, this means that a Index Added event for the now + fully configured controller can be expected. + + For a fully configured controller, the current controller index + will become invalid and an Unconfigured Index Removed event will + be send. Once the address has been successfully changed an Index + Added event will be send. There is no guarantee that the controller + index stays the same. + + All previous configured parameters and settings are lost when + this command succeeds. The controller has to be treated as new + one. Use this command for a fully configured controller only when + you really know what you are doing. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Rejected + Not Supported + Invalid Parameters + Invalid Index + + +Start Service Discovery Command +=============================== + + Command Code: 0x003a + Controller Index: + Command Parameters: Address_Type (1 Octet) + RSSI_Threshold (1 Octet) + UUID_Count (1 Octet) + UUID[i] (16 Octets) + Return Parameters: Address_Type (1 Octet) + + This command is used to start the process of discovering remote + devices with a specific UUID. A Device Found event will be sent + for each discovered device. + + Possible values for the Address_Type parameter are a bit-wise or + of the following bits: + + 0 BR/EDR + 1 LE Public + 2 LE Random + + By combining these e.g. the following values are possible: + + 1 BR/EDR + 6 LE (public & random) + 7 BR/EDR/LE (interleaved discovery) + + The service discovery uses active scanning for Low Energy scanning + and will search for UUID in both advertising data and scan response + data. + + Found devices that have a RSSI value smaller than RSSI_Threshold + are not reported via DeviceFound event. Setting a value of 127 + will cause all devices to be reported. + + The list of UUIDs identifies a logical OR. Only one of the UUIDs + have to match to cause a DeviceFound event. Providing an empty + list of UUIDs with Num_UUID set to 0 which means that DeviceFound + events are send out for all devices above the RSSI_Threshold. + + In case RSSI_Threshold is set to 127 and UUID_Count is 0, then + this command behaves exactly the same as Start Discovery. + + When the discovery procedure starts the Discovery event will + notify this similar to Start Discovery. + + This command can only be used when the controller is powered. + + This command generates a Command Complete event on success + or failure. + + Possible errors: Busy + Not Supported + Invalid Parameters + Not Powered + Invalid Index + + +Read Local Out Of Band Extended Data Command +============================================ + + Command Code: 0x003b + Controller Index: + Command Parameters: Address_Type (1 Octet) + Return Parameters: Address_Type (1 Octet) + EIR_Data_Length (2 Octets) + EIR_Data (0-65535 Octets) + + This command is used to read the local Out of Band data + information and provide them encoded as extended inquiry + response information or advertising data. + + Possible values for the Address_Type parameter are a bit-wise or + of the following bits: + + 0 BR/EDR + 1 LE Public + 2 LE Random + + By combining these e.g. the following values are possible: + + 1 BR/EDR + 6 LE (public & random) + 7 Reserved (not in use) + + For BR/EDR controller (Address_Type 1) the returned information + will contain the following information: + + Class of Device + Simple Pairing Hash C-192 (optional) + Simple Pairing Randomizer R-192 (optional) + Simple Pairing Hash C-256 (optional) + Simple Pairing Randomizer R-256 (optional) + Service Class UUID (optional) + Bluetooth Local Name (optional) + + The Simple Pairing Hash C-256 and Simple Pairing Randomizer R-256 + fields are only included when secure connections has been enabled. + + The Device Address (BD_ADDR) is not included in the EIR_Data and + needs to be taken from controller information. + + For LE controller (Address_Type 6) the returned information + will contain the following information: + + LE Bluetooth Device Address + LE Role + Security Manager TK Value (optional) + LE Secure Connections Confirmation Value (optional) + LE Secure Connections Random Value (optional) + Appearance (optional) + Local Name (optional) + Flags + + The LE Secure Connections Confirmation Value and LE Secure Connections + Random Value fields are only included when secure connections has been + enabled. + + The returned information from BR/EDR controller and LE controller + types are not related to each other. Once they have been used + over an Out Of Band link, a new set of information shall be + requested. + + When Secure Connections Only mode has been enabled, then the fields + for Simple Pairing Hash C-192, Simple Pairing Randomizer R-192 and + Security Manager TK Value are not returned. Only the fields for + the strong secure connections pairing are included. + + This command can only be used when the controller is powered. + + Values returned by this command become invalid when the controller + is powered down. After each power-cycle it is required to call + this command again to get updated information. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + Possible errors: Not Supported + Busy + Invalid Parameters + Not Powered + Invalid Index + + +Read Extended Controller Index List Command +=========================================== + + Command Code: 0x003c + Controller Index: + Command Parameters: + Return Parameters: Num_Controllers (2 Octets) + Controller_Index[i] (2 Octets) + Controller_Type[i] (1 Octet) + + This command returns the list of currently known controllers. It + includes configured, unconfigured and alternate controllers. + + Controllers added or removed after calling this command can be + be monitored using the Extended Index Added and Extended Index + Removed events. + + The existing Index Added, Index Removed, Unconfigured Index Added + and Unconfigured Index Removed are no longer sent after this command + has been used at least once. + + Instead of calling Read Controller Index List and Read Unconfigured + Controller Index List, this command combines all the information + and can be used to retrieve the controller list. + + The Controller_Type parameter has these values: + + 0x00 Primary Controller (BR/EDR and/or LE) + 0x01 Unconfigured Controller (BR/EDR and/or LE) + 0x02 Alternate MAC/PHY Controller (AMP) + + The 0x00 and 0x01 types indiciate a primary BR/EDR and/or LE + controller. The difference is just if they need extra configuration + or if they are fully configured. + + Controllers in configured state will be listed as 0x00 and controllers + in unconfigured state will be listed as 0x01. A controller that is + fully configured and supports configuration changes will be listed + as 0x00. + + Alternate MAC/PHY controllers will be listed as 0x02. They do not + support the difference between configured and unconfigured state. + + Controllers marked as RAW only operation are currently not listed + by this command. + + This command generates a Command Complete event on success or + a Command Status event on failure. + + +Command Complete Event +====================== + + Event Code: 0x0001 + Controller Index: or + Event Parameters: Command_Opcode (2 Octets) + Status (1 Octet) + Return_Parameters + + This event is an indication that a command has completed. The + fixed set of parameters includes the opcode to identify the + command that completed as well as a status value to indicate + success or failure. The rest of the parameters are command + specific and documented in the section for each command + separately. + + +Command Status Event +==================== + + Event Code: 0x0002 + Controller Index: or + Event Parameters: Command_Opcode (2 Octets) + Status (1 Octet) + + The command status event is used to indicate an early status for + a pending command. In the case that the status indicates failure + (anything else except success status) this also means that the + command has finished executing. + + +Controller Error Event +====================== + + Event Code: 0x0003 + Controller Index: + Event Parameters: Error_Code (1 Octet) + + This event maps straight to the HCI Hardware Error event and is + used to indicate something wrong with the controller hardware. + + +Index Added Event +================= + + Event Code: 0x0004 + Controller Index: + Event Parameters: + + This event indicates that a new controller has been added to the + system. It is usually followed by a Read Controller Information + command. + + Once the Read Extended Controller Index List command has been + used at least once, the Extended Index Added event will be + send instead of this one. + + +Index Removed Event =================== -Event Code 0x0005 -Controller Index: -Event Parameters + Event Code: 0x0005 + Controller Index: + Event Parameters: + + This event indicates that a controller has been removed from the + system. + + Once the Read Extended Controller Index List command has been + used at least once, the Extended Index Removed event will be + send instead of this one. + + +New Settings Event +================== + + Event Code: 0x0006 + Controller Index: + Event Parameters: Current_Settings (4 Octets) + + This event indicates that one or more of the settings for a + controller has changed. + + +Class Of Device Changed Event +============================= + + Event Code: 0x0007 + Controller Index: + Event Parameters: Class_Of_Device (3 Octets) + + This event indicates that the Class of Device value for the + controller has changed. When the controller is powered off the + Class of Device value will always be reported as zero. + + +Local Name Changed Event +======================== + + Event Code: 0x0008 + Controller Index: + Event Parameters: Name (249 Octets) + Short_Name (11 Octets) + + This event indicates that the local name of the controller has + changed. + + +New Link Key Event +================== + + Event Code: 0x0009 + Controller Index: + Event Parameters: Store_Hint (1 Octet) + Key { + Address (6 Octets) + Address_Type (1 Octet) + Key_Type (1 Octet) + Value (16 Octets) + PIN_Length (1 Octet) + } + + This event indicates that a new link key has bee generated for a + remote device. + The Store_Hint parameter indicates whether the host is expected + to store the key persistently or not (e.g. this would not be set + if the authentication requirement was "No Bonding"). -New Settings Event -================== + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 Reserved (not in use) + 2 Reserved (not in use) -Event Code 0x0006 -Controller Index: -Event Parameters: Current_Settings (4 Octets) + Public and random LE addresses are not valid and will be rejected. + Currently defined Key_Type values are: -Class Of Device Changed Event -============================= + 0x00 Combination key + 0x01 Local Unit key + 0x02 Remote Unit key + 0x03 Debug Combination key + 0x04 Unauthenticated Combination key from P-192 + 0x05 Authenticated Combination key from P-192 + 0x06 Changed Combination key + 0x07 Unauthenticated Combination key from P-256 + 0x08 Authenticated Combination key from P-256 -Event Code 0x0007 -Controller Index: -Event Parameters: Class_Of_Device (3 Octets) + Receiving this event indicates that a pairing procecure has + been completed. -Local Name Changed Event -======================== +New Long Term Key Event +======================= -Event Code 0x0008 -Controller Index -Event Parameters Name (249 Octets) - Short_Name (11 Octets) + Event Code: 0x000A + Controller Index: + Event Parameters: Store_Hint (1 Octet) + Key { + Address (6 Octets) + Address_Type (1 Octet) + Key_Type (1 Octet) + Master (1 Octet) + Encryption Size (1 Octet) + Enc. Diversifier (2 Octets) + Random Number (8 Octets) + Value (16 Octets) + } + This event indicates that a new long term key has been generated + for a remote device. -New Link Key Event -================== + The Store_Hint parameter indicates whether the host is expected + to store the key persistently or not (e.g. this would not be set + if the authentication requirement was "No Bonding"). -Event Code 0x0009 -Controller Index: -Event Parameters Key { - Address (6 Octets) - Address_Type (1 Octet) - Key_Type (1 Octet) - Value (16 Octets) - PIN_Length (1 Octet) - } + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. -New Long Term Key Event -======================= + For unresolvable random addresses and resolvable random addresses + without identity information and identity resolving key, the + Store_Hint will be set to not store the long term key. -Event Code 0x000A -Controller Index -Event Parameters Store Hint (1 Octet) - Key { - Address (6 Octets) - Address_Type (1 Octet) - Authenticated (1 Octet) - Master (1 Octet) - Encryption Size (1 Octet) - Enc. Diversifier (2 Octets) - Random Number (8 Octets) - Value (16 Octets) - } + Currently defined Key_Type values are: + + 0x00 Unauthenticated legacy key + 0x01 Authenticated legacy key + 0x02 Unauthenticated key from P-256 + 0x03 Authenticated key from P-256 + 0x04 Debug key from P-256 + + Receiving this event indicates that a pairing procecure has + been completed. Device Connected Event ====================== -Event Code 0x000B -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - Flags (4 Octets) - EIR_Data_Length (2 Octets) - EIR_Data (0-65535 Octets) + Event Code: 0x000B + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Flags (4 Octets) + EIR_Data_Length (2 Octets) + EIR_Data (0-65535 Octets) + + This event indicates that a successful baseband connection has + been created to the remote device. Possible values for the Address_Type parameter: 0 BR/EDR 1 LE Public 2 LE Random + For devices using resolvable random addresses with a known + identity resolving key, the Address and Address_Type will + contain the identity information. + + It is possible that devices get connected via its resolvable + random address and after New Identity Resolving Key event + start using its identity. + The following bits are defined for the Flags parameter: 0 Reserved (not in use) 1 Legacy Pairing + 2 Reserved (not in use) Device Disconnected Event ========================= -Event Code 0x000C -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) + Event Code: 0x000C + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Reason (1 Octet) + + This event indicates that the baseband connection was lost to a + remote device. Possible values for the Address_Type parameter: 0 BR/EDR 1 LE Public 2 LE Random + For devices using resolvable random addresses with a known + identity resolving key, the Address and Address_Type will + contain the identity information. + + Possible values for the Reason parameter: + 0 Unspecified + 1 Connection timeout + 2 Connection terminated by local host + 3 Connection terminated by remote host + + Note that the local/remote distinction just determines which side + terminated the low-level connection, regardless of the + disconnection of the higher-level profiles. + + This can sometimes be misleading and thus must be used with care. + For example, some hardware combinations would report a locally + initiated disconnection even if the user turned Bluetooth off in + the remote side. + Connect Failed Event ==================== -Event Code 0x000D -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - Status (1 Octet) + Event Code: 0x000D + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Status (1 Octet) + + This event indicates that a connection attempt failed to a + remote device. Possible values for the Address_Type parameter: 0 BR/EDR 1 LE Public 2 LE Random + For devices using resolvable random addresses with a known + identity resolving key, the Address and Address_Type will + contain the identity information. + PIN Code Request Event ====================== -Event Code 0x000E -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - Secure (1 Octet) + Event Code: 0x000E + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Secure (1 Octet) + + This event is used to request a PIN Code reply from user space. + The reply should either be returned using the PIN Code Reply or + the PIN Code Negative Reply command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random Secure: 0x01 secure PIN code required 0x00 secure PIN code not required @@ -1011,44 +2765,81 @@ Event Parameters Address (6 Octets) User Confirmation Request Event =============================== -Event Code 0x000F -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - Confirm_Hint (1 Octet) - Value (4 Octets) + Event Code: 0x000F + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Confirm_Hint (1 Octet) + Value (4 Octets) + + This event is used to request a user confirmation request from + user space. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + If the Confirm_Hint parameter value is 0x01 this means that + a simple "Yes/No" confirmation should be presented to the user + instead of a full numerical confirmation (in which case the + parameter value will be 0x00). + + User space should respond to this command either using the User + Confirmation Reply or the User Confirmation Negative Reply + command. User Passkey Request Event ========================== -Event Code 0x0010 -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) + Event Code: 0x0010 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This event is used to request a passkey from user space. The + response to this event should either be the User Passkey Reply + command or the User Passkey Negative Reply command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random Authentication Failed Event =========================== -Event Code 0x0011 -Controller Index: -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - Status (1 Octet) + Event Code: 0x0011 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Status (1 Octet) + + This event indicates that there was an authentication failure + with a remote device. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random Device Found Event ================== -Event Code 0x0012 -Controller Index -Event Parameters Address (6 Octets) - Address_Type (1 Octet) - RSSI (1 Octet) - Flags (4 Octets) - EIR_Data_Length (2 Octets) - EIR_Data (0-65535 Octets) + Event Code: 0x0012 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + RSSI (1 Octet) + Flags (4 Octets) + EIR_Data_Length (2 Octets) + EIR_Data (0-65535 Octets) + + This event indicates that a device was found during device + discovery. Possible values for the Address_Type parameter: 0 BR/EDR @@ -1058,39 +2849,376 @@ Event Parameters Address (6 Octets) The following bits are defined for the Flags parameter: 0 Confirm name 1 Legacy Pairing + 2 Not Connectable + + For the RSSI field a value of 127 indicates that the RSSI is + not available. That can happen with Bluetooth 1.1 and earlier + controllers or with bad radio conditions. + + The Confirm name flag indicates that the kernel wants to know + whether user space knows the name for this device or not. If + this flag is set user space should respond to it using the + Confirm Name command. + + The Legacy Pairing flag indicates that Legacy Pairing is likely + to occur when pairing with this device. An application could use + this information to optimize the pairing process by locally + pre-generating a PIN code and thereby eliminate the risk of + local input timeout when pairing. Note that there is a risk of + false-positives for this flag so user space should be able to + handle getting something else as a PIN Request when pairing. + + The Not Connectable flag indicates that the device will not + accept any connections. This can be indicated by Low Energy + devices that are in broadcaster role. Discovering Event ================= -Event Code 0x0013 -Controller Index -Event Parameters Address_Type (1 Octet) - Discovering (1 Octet) + Event Code: 0x0013 + Controller Index: + Event Parameters: Address_Type (1 Octet) + Discovering (1 Octet) + + This event indicates that the controller has started discovering + devices. This discovering state can come and go multiple times + between a Start Discovery and a Stop Discovery commands. + + The Start Service Discovery command will also trigger this event. + + The valid values for the Discovering parameter are 0x01 + (enabled) and 0x00 (disabled). Device Blocked Event ==================== -Event Code 0x0014 -Controller Index -Event Parameters Address (6 Octets) - Address_Type (1 Octet) + Event Code: 0x0014 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This event indicates that a device has been blocked using the + Block Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The event will only be sent to Management sockets other than the + one through which the command was sent. Device Unblocked Event ====================== -Event Code 0x0015 -Controller Index -Event Parameters Address (6 Octets) - Address_Type (1 Octet) + Event Code: 0x0015 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This event indicates that a device has been unblocked using the + Unblock Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The event will only be sent to Management sockets other than the + one through which the command was sent. Device Unpaired Event ===================== -Event Code 0x0016 -Controller Index -Event Parameters Address (6 Octets) - Address_Type (1 Octet) + Event Code: 0x0016 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This event indicates that a device has been unpaired (i.e. all + its keys have been removed from the kernel) using the Unpair + Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + For devices using resolvable random addresses with a known + identity resolving key, the event paramters will contain + the identity. After receiving this event, the device will + become essentially private again. + + The event will only be sent to Management sockets other than the + one through which the Unpair Device command was sent. + + +Passkey Notify Event +==================== + + Event Code: 0x0017 + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Passkey (4 Octets) + Entered (1 Octet) + + This event is used to request passkey notification to the user. + Unlike the other authentication events it does not need + responding to using any Management command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The Passkey parameter indicates the passkey to be shown to the + user whereas the Entered parameter indicates how many characters + the user has entered on the remote side. + + +New Identity Resolving Key Event +================================ + + Event Code: 0x0018 + Controller Index: + Event Parameters: Store_Hint (1 Octet) + Random_Address (6 Octets) + Key { + Address (6 Octets) + Address_Type (1 Octet) + Value (16 Octets) + } + + This event indicates that a new identity resolving key has been + generated for a remote device. + + The Store_Hint parameter indicates whether the host is expected + to store the key persistently or not. + + The Random_Address provides the resolvable random address that + was resolved into an identity. A value of 00:00:00:00:00:00 + indicates that the identity resolving key was provided for + a public address or static random address. + + Once this event has been send for a resolvable random address, + all further events mapping this device will send out using the + identity address information. + + This event also indicates that now the identity address should + be used for commands instead of the resolvable random address. + + It is possible that some devices allow discovering via its + identity address, but after pairing using resolvable private + address only. In such a case Store_Hint will be 0x00 and the + Random_Address will indicate 00:00:00:00:00:00. For these devices, + the Privacy Characteristic of the remote GATT database should + be consulted to decide if the identity resolving key must be + stored persistently or not. + + Devices using Set Privacy command with the option 0x02 would + be such type of device. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. + + +New Signature Resolving Key Event +================================= + + Event Code: 0x0019 + Controller Index: + Event Parameters: Store_Hint (1 Octet) + Key { + Address (6 Octets) + Address_Type (1 Octet) + Type (1 Octet) + Value (16 Octets) + } + + This event indicates that a new signature resolving key has been + generated for either the master or slave device. + + The Store_Hint parameter indicates whether the host is expected + to store the key persistently or not. + + The Type parameter has the following possible values: + + 0x00 Unauthenticated local CSRK + 0x01 Unauthenticated remote CSRK + 0x02 Authenticated local CSRK + 0x03 Authenticated remote CSRK + + The local keys are used for signing data to be sent to the + remote device, whereas the remote keys are used to verify + signatures received from the remote device. + + The local signature resolving key will be generated with each + pairing request. Only after receiving this event with the Type + indicating a local key is it possible to use ATT Signed Write + procedures. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The provided Address and Address_Type are the identity of + a device. So either its public address or static random address. + + +Device Added Event +================== + + Event Code: 0x001a + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + Action (1 Octet) + + This event indicates that a device has been added using the + Add Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The event will only be sent to management sockets other than the + one through which the command was sent. + + +Device Removed Event +==================== + + Event Code: 0x001b + Controller Index: + Event Parameters: Address (6 Octets) + Address_Type (1 Octet) + + This event indicates that a device has been removed using the + Remove Device command. + + Possible values for the Address_Type parameter: + 0 BR/EDR + 1 LE Public + 2 LE Random + + The event will only be sent to management sockets other than the + one through which the command was sent. + + +New Connection Parameter Event +============================== + + Event Code: 0x001c + Controller Index: + Event Parameters: Store_Hint (1 Octet) + Param { + Address (6 Octets) + Address_Type (1 Octet) + Min_Connection_Interval (2 Octets) + Max_Connection_Interval (2 Octes) + Connection_Latency (2 Octets) + Supervision_Timeout (2 Octets) + } + + This event indicates a new set of connection parameters from + a peripheral device. + + The Store_Hint parameter indicates whether the host is expected + to store this information persistently or not. + + Possible values for the Address_Type parameter: + 0 Reserved (not in use) + 1 LE Public + 2 LE Random + + The Min_Connection_Interval, Max_Connection_Interval, + Connection_Latency and Supervision_Timeout parameters are + encoded as described in Core 4.1 spec, Vol 2, 7.7.65.3. + + +Unconfigured Index Added Event +============================== + + Event Code: 0x001d + Controller Index: + Event Parameters: + + This event indicates that a new unconfigured controller has been + added to the system. It is usually followed by a Read Controller + Configuration Information command. + + Only when a controller requires further configuration, it will + be announced with this event. If it supports configuration, but + does not require it, then an Index Added event will be used. + + Once the Read Extended Controller Index List command has been + used at least once, the Extended Index Added event will be + send instead of this one. + + +Unconfigured Index Removed Event +================================ + + Event Code: 0x001e + Controller Index: + Event Parameters: + + This event indicates that an unconfigured controller has been + removed from the system. + + Once the Read Extended Controller Index List command has been + used at least once, the Extended Index Removed event will be + send instead of this one. + + +New Configuration Options Event +=============================== + + Event Code: 0x001f + Controller Index: + Event Parameters: Missing_Options (4 Octets) + + This event indicates that one or more of the options for the + controller configuration has changed. + + +Extended Index Added Event +========================== + + Event Code: 0x0020 + Controller Index: + Event Parameters: Controller_Type (1 Octet) + + This event indicates that a new controller index has been + added to the system. + + This event will only be used after Read Extended Controller Index + List has been used at least once. If it has not been used, then + Index Added and Unconfigured Index Added are send instead. + + +Extended Index Removed Event +============================ + + Event Code: 0x0021 + Controller Index: + Event Parameters: Controller_Type (1 Octet) + + This event indicates that an existing controller index has been + removed from the system. + + This event will only be used after Read Extended Controller Index + List has been used at least once. If it has not been used, then + Index Removed and Unconfigured Index Removed are send instead.