Linux kernel v3.16 Version 1.6
Linux kernel v3.17 Version 1.7
Linux kernel v3.19 Version 1.8
-Linux kernel v4.1 Version 1.9 (not yet released)
+Linux kernel v4.1 Version 1.9
+Linux kernel v4.2 Version 1.10
+Linux kernel v4.5 Version 1.11 (not yet released)
Version 1.1 introduces Set Device ID command.
Version 1.8 introduces Start Service Discovery command. It also adds new
Long Term Key types for LE Secure Connection feature.
-Version 1.9 introduces a new static address setting and allows the usage
-of Set Fast Connectable when controller is powered off. The existing Set
-Advertising command gained an extra setting for enabling undirected
-connectable advertising.
+Version 1.9 introduces Read Local Out Of Band Extended, Data, Read Extended
+Controller Index List, Read Advertising Features, Add Advertising and Remove
+Advertising commands. It also introduces Extended Index Added, Extended Index
+Removed, Local Out Of Band Extended Data Updated, Advertising Added and
+Advertising Removed events. The existing Set Advertising command gained an
+extra setting for enabling undirected connectable advertising. It provides
+support for a new static address setting and allows the usage of Set Fast
+Connectable when controller is powered off.
+
+Version 1.10 does not introduce any new command or event. It extends the
+advertising feature to support 5 parallel advertising instances.
+
+Version 1.11 introduces Get Advertising Size Information command.
Example
Name (249 Octets)
Short_Name (11 Octets)
- This command is used to retreive the current state and basic
+ This command is used to retrieve 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.
switching the controller off will expire this timeout and
disable discoverable.
+ Settings programmed via Set Advertising and Add/Remove
+ Advertising while the controller was powered off will be activated
+ when powering the controller on.
+
+ Switching the controller off will permanently cancel and remove
+ all advertising instances with a timeout set, i.e. time limited
+ advertising instances are not being remembered across power cycles.
+ Advertising Removed events will be issued accordingly.
+
This command generates a Command Complete event on success or
a Command Status event on failure.
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
+ For LE capable controllers the connectable setting takes effect
when advertising is enabled (peripheral) or when directed
advertising events are received (central).
In case the kernel subsystem does not support Low Energy or the
controller does not either, the command will fail regardless.
+ Disabling LE support will permanently disable and remove all
+ advertising instances configured with the Add Advertising
+ command. Advertising Removed events will be issued accordingly.
+
This command generates a Command Complete event on success or
a Command Status event on failure.
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.
+ receipt 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 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
+ again upon the receipt of New Long Term Key events since the
kernel updates its list automatically.
Possible values for the Address_Type parameter:
Address2 { }
...
- This command is used to retreive a list of currently connected
+ This command is used to retrieve a list of currently connected
devices.
Possible values for the Address_Type parameter:
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
+ this pairing event only) override the global IO Capability (set
using the Set IO Capability command).
Possible values for the Address_Type parameter:
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
+ event will be sent before receiving Command Complete event
for this command.
This command can only be used when the controller is powered.
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
+ which should be blocked from being connected to the local
controller.
Possible values for the Address_Type parameter:
1 LE Public
2 LE Random
- For Low Energy devices, the blocking of a device take presedence
+ For Low Energy devices, the blocking of a device takes precedence
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
0x0000 Disable Device ID
0x0001 Bluetooth SIG
- 0x0002 USB Implementer’s Forum
+ 0x0002 USB Implementer's Forum
- The information are put into the EIR data. If the controller does
+ The information is 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
+ succeed. The information is stored for later use and will survive
toggling SSP on and off.
This command generates a Command Complete event on success or
Using value 0x01 means that when connectable setting is disabled,
the advertising happens with undirected non-connectable advertising
- packets and a non-resovable random address is used. If connectable
+ packets and a non-resolvable random address is used. If connectable
setting is enabled, then undirected connectable advertising packets
and the identity address or resolvable private address are used.
The value 0x02 should be the preferred mode of operation when
implementing peripheral mode.
- Using this command will temporarily deactive any configuration
+ Using this command will temporarily deactivate any configuration
made by the Add Advertising command. This command takes precedence.
+ Once a Set Advertising command with value 0x00 is issued any
+ previously made configurations via Add/Remove Advertising, including
+ such changes made while Set Advertising was active, will be re-
+ enabled.
A pre-requisite is that LE is already enabled, otherwise this
command will return a "rejected" response.
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.
+ private address. In case the controller 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
+ during initiated 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
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
+ to configure a static random address 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
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
+ again upon the receipt of New Identity Resolving Key events
since the kernel updates its list automatically.
Possible values for the Address_Type parameter:
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
+ event will be sent 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.
+ Connected event will be sent.
With the Action 2, when the device is found, it will be connected
- and if successful a Device Connected event will be send. This
+ and if successful a Device Connected event will be sent. 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
Address (6 Octets)
Address_Type (1 Octet)
Min_Connection_Interval (2 Octets)
- Max_Connection_Interval (2 Octes)
+ Max_Connection_Interval (2 Octets)
Connection_Latency (2 Octets)
Supervision_Timeout (2 Octets)
}
Supported_Options (4 Octets)
Missing_Options (4 Octets)
- This command is used to retreive the supported configuration
+ This command is used to retrieve the supported configuration
options of a controller and the missing configuration options.
The missing options are required to be configured before the
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.
+ trying to power them via Set Powered command.
This command generates a Command Complete event on success or a
Command Status event on failure.
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
+ be sent. Once the address has been successfully changed an Index
+ Added event will be sent. There is no guarantee that the controller
index stays the same.
All previous configured parameters and settings are lost when
0x01 Unconfigured Controller (BR/EDR and/or LE)
0x02 Alternate MAC/PHY Controller (AMP)
- The 0x00 and 0x01 types indiciate a primary BR/EDR and/or LE
+ The 0x00 and 0x01 types indicate a primary BR/EDR and/or LE
controller. The difference is just if they need extra configuration
or if they are fully configured.
not be set.
The Flags bit 5 indicates support for automatically adding the
- Apperance value to the scan response data. Users of this flag
+ Appearance value to the scan response data. Users of this flag
will decrease the Max_Scan_Rsp_len by 4 octets. The Appearance
field will be added in front of the scan response data provided
by the user. If the appearance value is not supported, then this
however might decrease the actual available length in these
data fields.
- With Num_Instances and Instance array the current occupied
+ With Num_Instances and Instance array the currently occupied
Instance identifiers can be retrieved.
This command generates a Command Complete event on success or
can be used to switch a Bluetooth Low Energy controller into
advertising mode.
- Added advertising information with this command will be ignored
- when using the Set Advertising command to enable advertising. The
- usage of Set Advertising command take precedence over this command.
+ Added advertising information with this command will not be visible
+ immediately if advertising is enabled via the Set Advertising
+ command. The usage of the Set Advertising command takes precedence
+ over this command. Instance information is stored and will be
+ advertised once advertising via Set Advertising has been disabled.
The Instance identifier is a value between 1 and the number of
supported instances. The value 0 is reserved.
broadcaster role.
The Duration parameter configures the length of an Instance. The
- value is in seconds and a value of 0 indicates an automatic choice
- for the Duration. If only one advertising Instance has been added,
- then the Duration value will be ignored. It only applies for the
- case where multiple Instances are configured. In that case every
- Instance will be available for the Duration time and after that
- it switches to the next one. This is a simple round-robin based
- approach.
+ value is in seconds.
+
+ A value of 0 indicates a default value is chosen for the
+ Duration. The default is 2 seconds.
+
+ If only one advertising Instance has been added, then the Duration
+ value will be ignored. It only applies for the case where multiple
+ Instances are configured. In that case every Instance will be
+ available for the Duration time and after that it switches to
+ the next one. This is a simple round-robin based approach.
The Timeout parameter configures the life-time of an Instance. In
case the value 0 is used it indicates no expiration time. If a
- timeout value is provided, then the advertising Instace will be
+ timeout value is provided, then the advertising Instance will be
automatically removed when the timeout passes. The value for the
timeout is in seconds. Powering down a controller will invalidate
all advertising Instances and it is not possible to add a new
Instance with a timeout when the controller is powered down.
- When a Timeout is provided, then the Duration substracts from
+ When a Timeout is provided, then the Duration subtracts from
the actual Timeout value of that Instance. For example an Instance
- with Timeout of 6 and Duration of 2 will be scheduled exactly 3
- times. Other Instances have no influence on the Timeout.
+ with Timeout of 5 and Duration of 2 will be scheduled exactly 3
+ times, twice with 2 seconds and once with one second. Other
+ Instances have no influence on the Timeout.
+
+ Re-adding an already existing instance (i.e. issuing the Add
+ Advertising command with an Instance identifier of an existing
+ instance) will update that instance's configuration.
+
+ An instance being added or changed while another instance is
+ being advertised will not be visible immediately but only when
+ the new/changed instance is being scheduled by the round robin
+ advertising algorithm.
+
+ Changes to an instance that is currently being advertised will
+ cancel that instance and switch to the next instance. The changes
+ will be visible the next time the instance is scheduled for
+ advertising. In case a single instance is active, this means
+ that changes will be visible right away.
A pre-requisite is that LE is already enabled, otherwise this
command will return a "rejected" response.
When the Instance parameter is zero, then all previously added
advertising Instances will be removed.
+ Removing advertising information with this command will not be
+ visible as long as advertising is enabled via the Set Advertising
+ command. The usage of the Set Advertising command takes precedence
+ over this command. Changes to Instance information are stored and
+ will be advertised once advertising via Set Advertising has been
+ disabled.
+
+ Removing an instance while it is being advertised will immediately
+ cancel the instance, even when it has been advertised less then its
+ configured Timeout or Duration.
+
This command can be used when the controller is not powered and
all settings will be programmed once powered.
Invalid Index
+Get Advertising Size Information Command
+========================================
+
+ Command Code: 0x0040
+ Controller Index: <controller id>
+ Command Parameters: Instance (1 Octet)
+ Flags (4 Octets)
+ Return Parameters: Instance (1 Octet)
+ Flags (4 Octets)
+ Max_Adv_Data_Len (1 Octet)
+ Max_Scan_Rsp_Len (1 Octet)
+
+ The Read Advertising Features command returns the overall maximum
+ size of advertising data and scan response data fields. That size is
+ valid when no Flags are used. However when certain Flags are used,
+ then the size might decrease. This command can be used to request
+ detailed information about the maximum available size.
+
+ The following Flags values are defined:
+
+ 0 Switch into Connectable mode
+ 1 Advertise as Discoverable
+ 2 Advertise as Limited Discoverable
+ 3 Add Flags field to Adv_Data
+ 4 Add TX Power field to Adv_Data
+ 5 Add Appearance field to Scan_Rsp
+ 6 Add Local Name in Scan_Rsp
+
+ To get accurate information about the available size, the same Flags
+ values should be used with the Add Advertising command.
+
+ The Max_Adv_Data_Len and Max_Scan_Rsp_Len fields provide information
+ about the maximum length of the data fields for the given Flags
+ values. When the Flags field is zero, then these fields would contain
+ the same values as Read Advertising Features.
+
+ Possible errors: Invalid Parameters
+ Invalid Index
+
+
+Start Limited Discovery Command
+===============================
+
+ Command Code: 0x0041
+ 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 using the limited discovery procedure. A Device Found event
+ will be sent for each discovered device.
+
+ Possible values for the Address_Type parameter are a bit-wise or
+ of the following bits:
+
+ 0 BR/EDR
+ 1 LE Public
+ 2 LE Random
+
+ By combining these e.g. the following values are possible:
+
+ 1 BR/EDR
+ 6 LE (public & random)
+ 7 BR/EDR/LE (interleaved discovery)
+
+ The limited discovery uses active scanning for Low Energy scanning
+ and will search for devices with the limited discoverability flag
+ configured. On BR/EDR it uses LIAC and filters on the limited
+ discoverability flag of the class of device.
+
+ When the discovery procedure starts the Discovery event will
+ notify this similar to Start Discovery.
+
+ This command can only be used when the controller is powered.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Busy
+ Not Supported
+ Invalid Parameters
+ Not Powered
+ Invalid Index
+
+
Command Complete Event
======================
PIN_Length (1 Octet)
}
- This event indicates that a new link key has bee generated for a
+ This event indicates that a new link key has been generated for a
remote device.
The Store_Hint parameter indicates whether the host is expected
0x07 Unauthenticated Combination key from P-256
0x08 Authenticated Combination key from P-256
- Receiving this event indicates that a pairing procecure has
+ Receiving this event indicates that a pairing procedure has
been completed.
0x03 Authenticated key from P-256
0x04 Debug key from P-256
- Receiving this event indicates that a pairing procecure has
+ Receiving this event indicates that a pairing procedure has
been completed.
2 LE Random
For devices using resolvable random addresses with a known
- identity resolving key, the event paramters will contain
+ identity resolving key, the event parameters will contain
the identity. After receiving this event, the device will
become essentially private again.
Address (6 Octets)
Address_Type (1 Octet)
Min_Connection_Interval (2 Octets)
- Max_Connection_Interval (2 Octes)
+ Max_Connection_Interval (2 Octets)
Connection_Latency (2 Octets)
Supervision_Timeout (2 Octets)
}
projects / platform / upstream / bluez.git / blobdiff