mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-12-19 17:03:26 +08:00
2870 lines
80 KiB
Plaintext
2870 lines
80 KiB
Plaintext
Bluetooth Management API
|
||
*************************
|
||
|
||
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
|
||
|
||
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.
|
||
|
||
|
||
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
|
||
=================
|
||
|
||
Commands:
|
||
|
||
0 4 8 12 16 22 24 28 31 35 39 43 47
|
||
+-------------------+-------------------+-------------------+
|
||
| Command Code | Controller Index | Parameter Length |
|
||
+-------------------+-------------------+-------------------+
|
||
| |
|
||
|
||
Events:
|
||
|
||
0 4 8 12 16 22 24 28 31 35 39 43 47
|
||
+-------------------+-------------------+-------------------+
|
||
| Event Code | Controller Index | Parameter Length |
|
||
+-------------------+-------------------+-------------------+
|
||
| |
|
||
|
||
All fields are in little-endian byte order (least significant byte first).
|
||
|
||
Controller Index can have a special value <non-controller> to indicate that
|
||
command or event is not related to any controller. Possible values:
|
||
|
||
<controller id> 0x0000 to 0xFFFE
|
||
<non-controller> 0xFFFF
|
||
|
||
|
||
Error Codes
|
||
===========
|
||
|
||
The following values have been defined for use with the Command Status
|
||
and Command Complete events:
|
||
|
||
0x00 Success
|
||
0x01 Unknown Command
|
||
0x02 Not Connected
|
||
0x03 Failed
|
||
0x04 Connect Failed
|
||
0x05 Authentication Failed
|
||
0x06 Not Paired
|
||
0x07 No Resources
|
||
0x08 Timeout
|
||
0x09 Already Connected
|
||
0x0A Busy
|
||
0x0B Rejected
|
||
0x0C Not Supported
|
||
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
|
||
===========================================
|
||
|
||
Command Code: 0x0001
|
||
Controller Index: <non-controller>
|
||
Command Parameters:
|
||
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.
|
||
|
||
|
||
Read Management Supported Commands Command
|
||
==========================================
|
||
|
||
Command Code: 0x0002
|
||
Controller Index: <non-controller>
|
||
Command Parameters:
|
||
Return Parameters: Num_Of_Commands (2 Octets)
|
||
Num_Of_Events (2 Octets)
|
||
Command1 (2 Octets)
|
||
Command2 (2 Octets)
|
||
...
|
||
Event1 (2 Octets)
|
||
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.
|
||
|
||
The events Command Status and Command Complete are not included
|
||
in this list. Both are implicit and mandatory.
|
||
|
||
This command generates a Command Complete event on success or
|
||
a Command Status event on failure.
|
||
|
||
|
||
Read Controller Index List Command
|
||
==================================
|
||
|
||
Command Code: 0x0003
|
||
Controller Index: <non-controller>
|
||
Command Parameters:
|
||
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.
|
||
|
||
|
||
Read Controller Information Command
|
||
===================================
|
||
|
||
Command Code: 0x0004
|
||
Controller Index: <controller id>
|
||
Command Parameters:
|
||
Return Parameters: Address (6 Octets)
|
||
Bluetooth_Version (1 Octet)
|
||
Manufacturer (2 Octets)
|
||
Supported_Settings (4 Octets)
|
||
Current_Settings (4 Octets)
|
||
Class_Of_Device (3 Octets)
|
||
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.
|
||
|
||
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.
|
||
|
||
If no short name is set the Short_Name parameter will be empty
|
||
(begin with a nul byte).
|
||
|
||
Current_Settings and Supported_Settings is a bitmask with
|
||
currently the following available bits:
|
||
|
||
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
|
||
|
||
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 Code: 0x0005
|
||
Controller Index: <controller id>
|
||
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
|
||
========================
|
||
|
||
Command Code: 0x0006
|
||
Controller Index: <controller id>
|
||
Command Parameters: Discoverable (1 Octet)
|
||
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 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 Not Powered error.
|
||
|
||
When switching discoverable on and the connectable setting is
|
||
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 Code: 0x0007
|
||
Controller Index: <controller id>
|
||
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 also switch off the
|
||
discoverable setting. Switching connectable back on will not
|
||
restore a previous discoverable. It will stay off and needs
|
||
to be manually switched back on.
|
||
|
||
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 Code: 0x0008
|
||
Controller Index: <controller id>
|
||
Command Parameters: Enable (1 Octet)
|
||
Return Parameters: Current_Settings (4 Octets)
|
||
|
||
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. 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 Bondable Command
|
||
====================
|
||
|
||
Command Code: 0x0009
|
||
Controller Index: <controller id>
|
||
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 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 Code: 0x000A
|
||
Controller Index: <controller id>
|
||
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 Code: 0x000B
|
||
Controller Index: <controller id>
|
||
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 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 Code: 0x000C
|
||
Controller Index: <controller id>
|
||
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.
|
||
|
||
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 Code: 0x000D
|
||
Controller Index: <controller id>
|
||
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.
|
||
|
||
In case the kernel subsystem does not support Low Energy or the
|
||
controller does not either, the command will fail regardless.
|
||
|
||
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
|
||
================
|
||
|
||
Command Code: 0x000E
|
||
Controller Index: <controller id>
|
||
Command Parameters: Major_Class (1 Octet)
|
||
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.
|
||
|
||
In case the controller is powered off, 0x000000 will be returned
|
||
for the class of device parameter. And after power on the new
|
||
value will be announced via class of device changed event.
|
||
|
||
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
|
||
======================
|
||
|
||
Command Code: 0x000F
|
||
Controller Index: <controller id>
|
||
Command Parameters: Name (249 Octets)
|
||
Short_Name (11 Octets)
|
||
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 can be used when the controller is not powered and
|
||
all settings will be programmed once powered.
|
||
|
||
The values of name and short name will be remembered when
|
||
switching the controller off and back on again. So the name
|
||
and short name only have to be set once when a new controller
|
||
is found and will stay until removed.
|
||
|
||
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
|
||
================
|
||
|
||
Command Code: 0x0010
|
||
Controller Index: <controller id>
|
||
Command Parameters: UUID (16 Octets)
|
||
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.
|
||
|
||
In case the controller is powered off, 0x000000 will be returned
|
||
for the class of device parameter. And after power on the new
|
||
value will be announced via class of device changed event.
|
||
|
||
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 Code: 0x0011
|
||
Controller Index: <controller id>
|
||
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 can be used when the controller is not powered and
|
||
all settings will be programmed once powered.
|
||
|
||
In case the controller is powered off, 0x000000 will be returned
|
||
for the class of device parameter. And after power on the new
|
||
value will be announced via class of device changed event.
|
||
|
||
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
|
||
======================
|
||
|
||
Command Code: 0x0012
|
||
Controller Index: <controller id>
|
||
Command Parameters: Debug_Keys (1 Octet)
|
||
Key_Count (2 Octets)
|
||
Key1 {
|
||
Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Key_Type (1 Octet)
|
||
Value (16 Octets)
|
||
PIN_Length (1 Octet)
|
||
}
|
||
Key2 { }
|
||
...
|
||
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)
|
||
Key1 {
|
||
Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Key_Type (1 Octet)
|
||
Master (1 Octet)
|
||
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
|
||
==================
|
||
|
||
Command Code: 0x0014
|
||
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 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
|
||
=======================
|
||
|
||
Command Code: 0x0015
|
||
Controller Index: <controller id>
|
||
Command Parameters:
|
||
Return Parameters: Connection_Count (2 Octets)
|
||
Address1 {
|
||
Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
}
|
||
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
|
||
=======================
|
||
|
||
Command Code: 0x0016
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
PIN_Length (1 Octet)
|
||
PIN_Code (16 Octets)
|
||
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
|
||
===============================
|
||
|
||
Command Code: 0x0017
|
||
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 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 Code: 0x0018
|
||
Controller Index: <controller id>
|
||
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
|
||
===================
|
||
|
||
Command Code: 0x0019
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
IO_Capability (1 Octet)
|
||
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.
|
||
|
||
Possible errors: Connect Failed
|
||
Busy
|
||
Invalid Parameters
|
||
Not Powered
|
||
Invalid Index
|
||
|
||
|
||
Cancel Pair Device Command
|
||
==========================
|
||
|
||
Command Code: 0x001A
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Return Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
|
||
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
|
||
=====================
|
||
|
||
Command Code: 0x001B
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Disconnect (1 Octet)
|
||
Return Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
|
||
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
|
||
===============================
|
||
|
||
Command Code: 0x001C
|
||
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 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
|
||
========================================
|
||
|
||
Command Code: 0x001D
|
||
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 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
|
||
==========================
|
||
|
||
Command Code: 0x001E
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Passkey (4 Octets)
|
||
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
|
||
===================================
|
||
|
||
Command Code: 0x001F
|
||
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 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_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.
|
||
|
||
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
|
||
===================================
|
||
|
||
Command Code: 0x0021
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
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 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.
|
||
|
||
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
|
||
======================================
|
||
|
||
Command Code: 0x0022
|
||
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 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 Code: 0x0023
|
||
Controller Index: <controller id>
|
||
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:
|
||
|
||
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)
|
||
|
||
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
|
||
|
||
|
||
Stop Discovery Command
|
||
======================
|
||
|
||
Command Code: 0x0024
|
||
Controller Index: <controller id>
|
||
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
|
||
====================
|
||
|
||
Command Code: 0x0025
|
||
Controller Index: <controller id>
|
||
Command Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
Name_Known (1 Octet)
|
||
Return Parameters: Address (6 Octets)
|
||
Address_Type (1 Octet)
|
||
|
||
This command is only valid during device discovery and is
|
||
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
|
||
====================
|
||
|
||
Command Code: 0x0026
|
||
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 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
|
||
======================
|
||
|
||
Command Code: 0x0027
|
||
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 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
|
||
=====================
|
||
|
||
Command Code: 0x0028
|
||
Controller Index: <controller id>
|
||
Command Parameters: Source (2 Octets)
|
||
Vendor (2 Octets)
|
||
Product (2 Octets)
|
||
Version (2 Octets)
|
||
Return Parameters:
|
||
|
||
This command can be used when the controller is not powered and
|
||
all settings will be programmed once powered.
|
||
|
||
The Source parameter selects the organization that assigned the
|
||
Vendor parameter:
|
||
|
||
0x0000 Disable Device ID
|
||
0x0001 Bluetooth SIG
|
||
0x0002 USB Implementer’s Forum
|
||
|
||
The information are put into the EIR data. If the controller does
|
||
not support EIR or if SSP is disabled, this command will still
|
||
succeed. The information are stored for later use and will survive
|
||
toggling SSP on and off.
|
||
|
||
This command generates a Command Complete event on success or
|
||
a Command Status event on failure.
|
||
|
||
Possible errors: Invalid Parameters
|
||
Invalid Index
|
||
|
||
|
||
Set Advertising Command
|
||
=======================
|
||
|
||
Command Code: 0x0029
|
||
Controller Index: <controller id>
|
||
Command Parameters: Advertising (1 Octet)
|
||
Return Parameters: Current_Settings (4 Octets)
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Possible errors: Busy
|
||
Rejected
|
||
Not Supported
|
||
Invalid Parameters
|
||
Invalid Index
|
||
|
||
|
||
Set BR/EDR Command
|
||
==================
|
||
|
||
Command Code: 0x002A
|
||
Controller Index: <controller id>
|
||
Command Parameters: BR/EDR (1 Octet)
|
||
Return Parameters: Current_Settings (4 Octets)
|
||
|
||
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.
|
||
|
||
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:
|
||
|
||
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. 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.
|
||
|
||
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 BR/EDR capable controllers
|
||
supporting the core specification version 4.1 or greater
|
||
(e.g. not for single-mode LE controllers or pre-4.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 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
|
||
|
||
|
||
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.
|
||
|
||
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
|
||
|
||
|
||
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.
|
||
|
||
|
||
Index Removed Event
|
||
===================
|
||
|
||
Event Code: 0x0005
|
||
Controller Index: <controller id>
|
||
Event Parameters:
|
||
|
||
This event indicates that a controller has been removed from the
|
||
system.
|
||
|
||
|
||
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").
|
||
|
||
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
|
||
|
||
Receiving this event indicates that a pairing procecure has
|
||
been completed.
|
||
|
||
|
||
New Long Term Key Event
|
||
=======================
|
||
|
||
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.
|
||
|
||
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").
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
Currently defined Key_Type values are:
|
||
|
||
0x00 Unauthenticated key
|
||
0x01 Authenticated key
|
||
|
||
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)
|
||
|
||
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)
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
This event indicates that a device was found during device
|
||
discovery.
|
||
|
||
Possible values for the Address_Type parameter:
|
||
0 BR/EDR
|
||
1 LE Public
|
||
2 LE Random
|
||
|
||
The following bits are defined for the Flags parameter:
|
||
0 Confirm name
|
||
1 Legacy Pairing
|
||
2 Not Connectable
|
||
|
||
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)
|
||
|
||
This event indicates that the controller has started discovering
|
||
devices. This discovering state can come and go multiple times
|
||
between a StartDiscover and a StopDiscovery command.
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
|
||
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)
|
||
Master (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.
|
||
|
||
When the Master parameter is set to 0x01, then the signature
|
||
resolving key from the remote peer device is provided. It is
|
||
the key that is used for signature verification.
|
||
|
||
When the Master parameter is set to 0x00, then it is the local
|
||
signature resolving key that is used to sign data. The remote
|
||
peer device will be using it for signature verification.
|
||
|
||
The local signature resolving key will be generated with each
|
||
pairing request. Only after receiving this event with Master
|
||
parameter set to 0x00 it is 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.
|
||
|
||
|
||
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.
|
||
|
||
|
||
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.
|