Copyright (C) 2008-2009 Marcel Holtmann <marcel@holtmann.org>
+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
=================
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
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.
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.
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.
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
===================
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.
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
========================
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
=======================
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.
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
============================
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: <controller id>
- 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.
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
=========================
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
=================================
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
======================
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
======================
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.
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
================
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.
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
======================
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).
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
================
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.
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
===================
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.
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
======================
...
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: <controller id>
- 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
==================
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
=======================
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
=======================
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
===============================
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
=========================
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
===================
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: <controller id>
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
=====================
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
===============================
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
========================================
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
==========================
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
===================================
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
===================================
Command Code: 0x0020
Controller Index: <controller id>
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
===================================
Controller Index: <controller id>
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
======================================
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
=======================
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:
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
======================
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
====================
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
====================
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
======================
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
=====================
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: <controller id> or <non-controller>
-Event Parameters Command_Opcode (2 Octets)
- Status (1 Octet)
- Return_Parameters
+Set Advertising Command
+=======================
+ Command Code: 0x0029
+ Controller Index: <controller id>
+ 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: <controller id> or <non-controller>
-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: <controller id>
-Event Parameters Error_Code (1 Octet)
+Set BR/EDR Command
+==================
-Index Added Event
-=================
+ Command Code: 0x002A
+ Controller Index: <controller id>
+ Command Parameters: BR/EDR (1 Octet)
+ Return Parameters: Current_Settings (4 Octets)
-Event Code 0x0004
-Controller Index: <controller id>
-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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <non-controller>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <non-controller>
+ 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: <controller id> or <non-controller>
+ 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: <controller id> or <non-controller>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
-Event Parameters
+ Event Code: 0x0005
+ Controller Index: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
-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: <controller id>
-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 <controller id>
-Event Parameters Name (249 Octets)
- Short_Name (11 Octets)
+ Event Code: 0x000A
+ Controller Index: <controller id>
+ 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: <controller id>
-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 <controller id>
-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: <controller id>
-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: <controller id>
+ 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: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
+ Event Code: 0x000C
+ Controller Index: <controller id>
+ 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: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
- Status (1 Octet)
+ Event Code: 0x000D
+ Controller Index: <controller id>
+ 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: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
- Secure (1 Octet)
+ Event Code: 0x000E
+ Controller Index: <controller id>
+ 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
User Confirmation Request Event
===============================
-Event Code 0x000F
-Controller Index: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
- Confirm_Hint (1 Octet)
- Value (4 Octets)
+ Event Code: 0x000F
+ Controller Index: <controller id>
+ 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: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
+ Event Code: 0x0010
+ Controller Index: <controller id>
+ 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: <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
- Status (1 Octet)
+ Event Code: 0x0011
+ Controller Index: <controller id>
+ 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 <controller id>
-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: <controller id>
+ 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
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 <controller id>
-Event Parameters Address_Type (1 Octet)
- Discovering (1 Octet)
+ Event Code: 0x0013
+ Controller Index: <controller id>
+ 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 <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
+ Event Code: 0x0014
+ Controller Index: <controller id>
+ 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 <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
+ Event Code: 0x0015
+ Controller Index: <controller id>
+ 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 <controller id>
-Event Parameters Address (6 Octets)
- Address_Type (1 Octet)
+ Event Code: 0x0016
+ Controller Index: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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: <controller id>
+ 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.
projects / framework / connectivity / bluez.git / blobdiff