From 7539255a35015bbbda17b0ef92a0c783c578538b Mon Sep 17 00:00:00 2001 From: Johan Hedberg Date: Tue, 8 Jan 2013 15:52:04 +0200 Subject: [PATCH] doc: Update descriptions and possible error returns of mgmt commands --- doc/mgmt-api.txt | 331 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 329 insertions(+), 2 deletions(-) diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt index 60f4da406..731fc24b1 100644 --- a/doc/mgmt-api.txt +++ b/doc/mgmt-api.txt @@ -67,6 +67,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. @@ -86,6 +91,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. @@ -106,6 +114,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. @@ -125,6 +137,11 @@ Read Controller Information Command Name (249 Octets) Short_Name (11 Octets) + 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. + If not short name is set the Short_Name parameter will be empty (begin with a nul byte). @@ -145,6 +162,9 @@ Read Controller Information Command 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 =================== @@ -154,6 +174,9 @@ 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. + If discoverable setting is activated with a timeout, then switching the controller off will expire this timeout and disable discoverable. @@ -161,6 +184,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 ======================== @@ -171,9 +198,16 @@ 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 and 0x01. + Timeout is the time in seconds and is only meaningful when Discoverable is set to 1. + 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. @@ -186,6 +220,13 @@ Set Discoverable Command 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 ======================= @@ -195,6 +236,13 @@ 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. + + 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. @@ -209,6 +257,11 @@ Set Connectable 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 Fast Connectable Command ============================ @@ -218,14 +271,32 @@ 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. + + The allowed values of the Enable command parameter are 0x00 and + 0x01. + + This command is only available for BR/EDR capable controllers + (e.g. not for single-mode LE ones). + + This command can only be used when the controller is powered on. If connectable is not set, then this command will fail. 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 ==================== @@ -235,6 +306,10 @@ Set Pairable Command Command Parameters: Pairable (1 Octet) Return Parameters: Current_Settings (4 Octets) + This command is used to set the pairable property of an + controller. The allowed values for the Pairable command + parameter are 0x00 and 0x01. + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -246,6 +321,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 ========================= @@ -255,12 +333,25 @@ 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. + + 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. 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 ================================= @@ -270,6 +361,14 @@ 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. + + 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. @@ -279,6 +378,10 @@ Set Secure Simple Pairing 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 High Speed Command ====================== @@ -288,6 +391,13 @@ 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. + + 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. @@ -297,6 +407,10 @@ Set High Speed Command 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 ====================== @@ -306,6 +420,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. + + This command is only available for LE capable controllers and + attempting to call it on anything else will yield a "Not + Supported" error. + This command can be used when the controller is not powered and all settings will be programmed once powered. @@ -315,6 +437,10 @@ Set Low Energy Command 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 Device Class ================ @@ -325,9 +451,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. @@ -338,6 +470,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 ====================== @@ -349,6 +486,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). @@ -363,6 +504,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 ================ @@ -373,6 +517,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 + and/or AD 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. @@ -383,6 +532,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 =================== @@ -392,6 +545,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. @@ -405,6 +561,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 ====================== @@ -424,11 +584,19 @@ 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. + 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 =========================== @@ -449,11 +617,19 @@ Load Long Term Keys Command Key2 { } ... + 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. + 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 ================== @@ -465,11 +641,20 @@ Disconnect Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to force the disconnection of a currently + connected device. + 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 ======================= @@ -485,6 +670,9 @@ 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 @@ -495,6 +683,10 @@ Get Connections Command 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 ======================= @@ -508,11 +700,18 @@ 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. + 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 =============================== @@ -524,11 +723,19 @@ 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. + 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 ========================= @@ -538,11 +745,18 @@ 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. The KeyboardDisplay + SMP value (which doesn't exist for SSP will) automatically be + downgraded to DisplayYesNo by the kernel for SSP pairing events. + 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 =================== @@ -555,6 +769,11 @@ 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 @@ -565,6 +784,12 @@ Pair Device Command This command generates a Command Complete event on success or failure. + Possible errors: Connect Failed + Busy + Invalid Parameters + Not Powered + Invalid Index + Cancel Pair Device ================== @@ -584,6 +809,10 @@ Cancel Pair Device This command generates a Command Complete event on success or failure. + Possible errors: Invalid Parameters + Not Powered + Invalid Index + Unpair Device Command ===================== @@ -608,6 +837,11 @@ Unpair Device Command 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 =============================== @@ -619,11 +853,19 @@ 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. + 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 ======================================== @@ -635,11 +877,19 @@ 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. + 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 ========================== @@ -652,11 +902,19 @@ 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. + 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 =================================== @@ -668,11 +926,19 @@ 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. + 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 =================================== @@ -683,11 +949,19 @@ Read Local Out Of Band Data Command Return Parameters: Hash (16 Octets) Randomizer (16 Octets) + This command is used to read the local Out of Band data. + 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: Not Supported + Busy + Invalid Parameters + Not Powered + Invalid Index + Add Remote Out Of Band Data Command =================================== @@ -701,11 +975,19 @@ Add Remote Out Of Band Data Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to provide Out of Band data for a remote + device. + Provided Out Of Band data is persistent over power down/up toggles. 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 ====================================== @@ -717,9 +999,16 @@ Remove Remote Out Of Band Data Command Return Parameters: Address (6 Octets) Address_Type (1 Octet) + This command is used to remove data added using the Add Remote + Out Of Band Data command. + This command generates a Command Complete event on success or failure. + Possible errors: Invalid Parameters + Not Powered + Invalid Index + Start Discovery Command ======================= @@ -729,6 +1018,10 @@ 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: @@ -747,6 +1040,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 +1055,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 ==================== @@ -782,6 +1088,10 @@ Confirm Name Command This command generates a Command Complete event on success or failure. + Possible errors: Failed + Invalid Parameters + Invalid Index + Block Device Command ==================== @@ -793,11 +1103,19 @@ 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. + 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 +1127,17 @@ 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). + 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,6 +1168,9 @@ 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 ====================== -- 2.47.3