1009 lines
49 KiB
Plaintext
1009 lines
49 KiB
Plaintext
Zephyr HCI Extensions
|
|
*********************
|
|
|
|
|
|
Introduction
|
|
============
|
|
|
|
This document describes a set of vendor specific HCI commands and events for
|
|
Zephyr based Bluetooth Classic and Low Energy controllers.
|
|
|
|
|
|
Zephyr Vendor Configuration Parameters
|
|
======================================
|
|
|
|
|
|
Zephyr Vendor Supported Commands
|
|
================================
|
|
|
|
The Supported Commands configuration parameter lists which vendor commands the
|
|
local Controller supports. It is implied that if a command is listed as
|
|
supported, the feature underlying that command is also supported.
|
|
|
|
The Supported Commands is a 64 octet bit field. If a bit is set to 1, then this
|
|
command is supported.
|
|
|
|
+-------+------+--------------------------------------------+
|
|
| Octet | Bit | Command Supported |
|
|
+-------+------+--------------------------------------------+
|
|
| 0 | 0 | Read Version Information |
|
|
| | 1 | Read Supported Commands |
|
|
| | 2 | Read Supported Features |
|
|
| | 3 | Set Event Mask |
|
|
| | 4 | Reset |
|
|
| | 5 | Write BD_ADDR |
|
|
| | 6 | Set Trace Enable |
|
|
| | 7 | Read Build Information |
|
|
+-------+------+--------------------------------------------+
|
|
| 1 | 0 | Read Static Addresses |
|
|
| | 1 | Read Key Hierarchy Roots |
|
|
| | 2 | Read Chip Temperature |
|
|
| | 3 | Read Host Stack Commands |
|
|
| | 4 | Set Scan Request Reports |
|
|
| | 5 | Reserved |
|
|
| | 6 | Reserved |
|
|
| | 7 | Reserved |
|
|
+-------+------+--------------------------------------------+
|
|
|
|
Only Read_Version_Information and Read_Supported_Commands commands are
|
|
mandatory.
|
|
|
|
|
|
Zephyr Vendor Supported Features
|
|
================================
|
|
|
|
The Supported Features configuration parameter lists vendor specific features
|
|
that either extend commands or don't have a vendor command. Most features are
|
|
indicated by the support its respective vendor command. The Supported Features
|
|
are represented as an 8 octet bit mask. For each feature a single bit is
|
|
specified which shall be set to 1 if the feature is supported and set to 0
|
|
otherwise.
|
|
|
|
+-------+------+--------------------------------------------+
|
|
| Octet | Bit | Feature Supported |
|
|
+-------+------+--------------------------------------------+
|
|
| 0 | 0 | Vendor Diagnostic Channel |
|
|
| | 1 | Reserved |
|
|
| | 2 | Reserved |
|
|
| | 3 | Reserved |
|
|
| | 4 | Reserved |
|
|
| | 5 | Reserved |
|
|
| | 6 | Reserved |
|
|
| | 7 | Reserved |
|
|
+-------+------+--------------------------------------------+
|
|
|
|
|
|
Zephyr Vendor Event Mask
|
|
========================
|
|
|
|
The Event Mask configuration parameter lists the events that are indicated by
|
|
the controller. By default no vendor events are reported.
|
|
|
|
+-------+------+--------------------------------------------+
|
|
| Octet | Bit | Event |
|
|
+-------+------+--------------------------------------------+
|
|
| 0 | 0 | Reserved |
|
|
| | 1 | Fatal Error |
|
|
| | 2 | Trace Information Event |
|
|
| | 3 | Scan Request Received Event |
|
|
| | 4 | Reserved |
|
|
| | 5 | Reserved |
|
|
| | 6 | Reserved |
|
|
| | 7 | Reserved |
|
|
+-------+------+--------------------------------------------+
|
|
|
|
The support for Fatal_Error event is mandatory. The default event mask after
|
|
bootup and vendor specific Reset command includes the Fatal_Error event.
|
|
|
|
|
|
Zephyr Hardware Platforms
|
|
=========================
|
|
|
|
Hardware platforms are assigned numbers to allow identification of the hardware
|
|
manufacturer.
|
|
|
|
Hardware_Platform: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x0001 | Intel Corporation |
|
|
| 0x0002 | Nordic Semiconductor |
|
|
| 0x0003 | NXP Semiconductors |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
The Hardware_Platform name is independent from the Manufacture Name provided
|
|
by HCI version information. This information identifies the actual chip while
|
|
the standard HCI version information identifies the unique implementation of
|
|
a Bluetooth Controller.
|
|
|
|
|
|
Zephyr Hardware Variants
|
|
========================
|
|
|
|
Hardware variants are platform specific. They are specified to allow detailed
|
|
identification of the hardware running Zephyr.
|
|
|
|
Hardware_Variant (Nordic): Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x0001 | nRF51x |
|
|
| 0x0002 | nRF52x |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
The Hardware_Variant value assignment depends on the Hardware_Platform value.
|
|
Each hardware platform has its own variant namespace.
|
|
|
|
|
|
Zephyr Trace Information Format
|
|
===============================
|
|
|
|
The trace information used the Trace Information event and in the Diagnostic
|
|
Channel are following the same packet format.
|
|
|
|
0 8 16 24
|
|
+--------------+--------------+--------------+--------------+
|
|
| Type | Connection_Handle | Parameters
|
|
+--------------+--------------+--------------+--------------+
|
|
|
|
|
|
Zephyr Vendor Commands
|
|
======================
|
|
|
|
Vendor specific HCI commands use the OGF 0x3F. All defined OCF are listed
|
|
below. Undefined OCF are reserved for future use.
|
|
|
|
|
|
Zephyr Read Version Information Command
|
|
=======================================
|
|
|
|
This command reads the values for the vendor version information for the local
|
|
Controller.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Version_Information | 0x001 | | Status, |
|
|
| | | | Hardware_Platform, |
|
|
| | | | Hardware_Variant, |
|
|
| | | | Firmware_Variant, |
|
|
| | | | Firmware_Version, |
|
|
| | | | Firmware_Revision, |
|
|
| | | | Firmware_Build |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
The Hardware_Platform information defines the hardware manufacturer
|
|
information. The Hardware_Variant is manufacturer specific and defines the
|
|
hardware platform from that manufacturer.
|
|
|
|
The Firmware_Variant defines the type of firmware. It is possible to provide
|
|
HCI firmware with limited functionality for example for bootloader operation.
|
|
The Firmware_Version and Firmware_Revision define version information of the
|
|
Firmware_Variant that is currently active. The Firmware_Build defines an
|
|
additional counter for incremental builds.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Hardware_Platform: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXX | Assigned hardware manufacturer |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Hardware_Variant: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXX | Assigned platform specific value |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Firmware_Variant: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Standard Bluetooth controller |
|
|
| 0x01 | Vendor specific controller |
|
|
| 0x02 | Firmware loader |
|
|
| 0x03 | Rescue image |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Firmware_Version: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXX | Implementation specific |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Firmware_Revision: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXX | Implementation specific |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Firmware_Build: Size: 4 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXX | Implementation specific |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Version_Information command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Read Supported Commands Command
|
|
======================================
|
|
|
|
This command reads the list of vendor commands supported for the local
|
|
Controller.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Supported_Commands | 0x002 | | Status, |
|
|
| | | | Supported_Commands |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the Supported_Commands configuration parameter. It is
|
|
implied that if a command is listed as supported, the feature underlying that
|
|
command is also supported.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Supported_Commands: Size: 64 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | Bit mask for each vendor command |
|
|
| | |
|
|
| | If a bit is 1, the Controller |
|
|
| | supports the corresponding command |
|
|
| | and the features required for the |
|
|
| | command, unsupported or undefined |
|
|
| | commands shall be set to 0 |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Supported_Commands command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Read Supported Features Command
|
|
======================================
|
|
|
|
This command reads the list of vendor features supported by the local Controller.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Supported_Features | 0x003 | | Status, |
|
|
| | | | Supported_Features |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the Supported_Features configuration parameter. The
|
|
features list is only used for features not covered by supported commands.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Supported_Features: Size: 8 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXXXXXXXXXX | Bit Mask List of vendor features |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Supported_Features command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Set Event Mask Command
|
|
=============================
|
|
|
|
This command is used to control which vendor events are generated by the HCI
|
|
for the Host.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Set_Event_Mask | 0x004 | Event_Mask | Status |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
If the bit in the Event_Mask is set to a one, then the event associated with
|
|
that bit will be enabled. The Host has to deal with each event that is
|
|
generated by a Controller. The event mask allows the Host to control which
|
|
events will interrupt it.
|
|
|
|
The vendor specific Reset command shall reset this event mask back to its
|
|
default value, but the standard HCI Reset command shall not reset this command
|
|
back to its default value.
|
|
|
|
Event_Mask: Size: 8 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x0000000000000003 | Default enabled vendor events |
|
|
| 0xXXXXXXXXXXXXXXXX | Bit Mask List of vendor events |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Set_Event_Mask command has completed, a Command Complete event shall
|
|
be generated.
|
|
|
|
|
|
Zephyr Reset Command
|
|
====================
|
|
|
|
This command resets the vendor portion of the local Controller.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Reset | 0x005 | Reset_Type | Status |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
The Host shall not send additional HCI commands before the Command Complete
|
|
event related to the Reset command has been received.
|
|
|
|
The Soft reset and Hard reset both include all actions taken by the standard
|
|
HCI Reset command. While the standard HCI Reset command does not reset any
|
|
vendor specific settings, this command will reset everything back to defaults.
|
|
|
|
The Hard reset will cause a full reboot of the hardware.
|
|
|
|
Reset_Type: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Soft reset |
|
|
| 0x01 | Hard reset |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Reset command has completed, a Command Complete event shall be
|
|
generated.
|
|
|
|
|
|
Zephyr Write BD_ADDR Command
|
|
============================
|
|
|
|
This command writes the BD_ADDR (Bluetooth public device address) value
|
|
to the volatile memory. It is kept over Reset and can be read out by
|
|
Read_BD_ADDR command.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Write_BD_ADDR | 0x006 | BD_ADDR | Status |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
To activate this address the standard HCI Reset command is required to be
|
|
executed. Until then the current BD_ADDR is still active and reported by
|
|
Read_BD_ADDR. The vendor specific Reset command will reset the BD_ADDR to its
|
|
non-volatile default if available. Otherwise the BD_ADDR shall be reset to the
|
|
invalid / non-existent 00:00:00:00:00:00 address value.
|
|
|
|
BD_ADDR: Size: 6 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXXXXXX | BD_ADDR of the Device |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Write_BD_ADDR command has completed, a Command Complete event shall
|
|
be generated.
|
|
|
|
|
|
Zephyr Set Trace Enable Command
|
|
===============================
|
|
|
|
This command is used to enable or disable the tracing functionality.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Set_Trace_Enable | 0x007 | Enable, | Status |
|
|
| | | Type | |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
When enabled the Controller will send link layer and link manager tracing
|
|
information to the Host.
|
|
|
|
When Enable is set to 0x00 then Type shall be set to 0x00 as well. The
|
|
diagnostic channel type shall only supported when the feature bit is also set.
|
|
|
|
The support for trace information reporting via HCI events is mandatory to
|
|
support when the Set_Trace_Enable command is supported.
|
|
|
|
Enable: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Tracing disabled |
|
|
| 0x01 | Tracing enabled |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Type: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Use HCI events |
|
|
| 0x01 | Use Vendor Diagnostic Channel |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Set_Trace_Enable command has completed, a Command Complete event shall
|
|
be generated.
|
|
|
|
|
|
Zephyr Read Build Information Command
|
|
=====================================
|
|
|
|
This commands reads the controller firmware build information string.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Build_Information | 0x008 | | Status, |
|
|
| | | | Build_Info |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the build information encoded as an UTF-8 string.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Build_Info: Size: variable
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | UTF-8 encoded build information |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Build_Information command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Read Static Addresses Command
|
|
====================================
|
|
|
|
This commands reads the controller specific static addresses.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Static_Addresses | 0x009 | | Status, |
|
|
| | | | Num_Addresses, |
|
|
| | | | Static_Address[i], |
|
|
| | | | Identity_Root[i] |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the static addresses programmed by the vendor at
|
|
manufacturing time.
|
|
|
|
Each returned static address shall confirm to the Static Device Address
|
|
definition. The two most significant bits of the address shall be equal to 1.
|
|
At least one bit of the random part of the address shall be 0. At least one bit
|
|
of the random part of the address shall be 1.
|
|
|
|
The Identity_Root parameter may be all zeros to indicate no identity root key
|
|
being available for a given static address. The identity root key returned from
|
|
Read_Key_Hierarchy_Roots command shall not be returned from this command.
|
|
|
|
Note: If no public address is provided and a static address is available, then
|
|
it is recommended to return an identity root key (if available) from this
|
|
command. In case a public address is provided, then it is recommended to use
|
|
the Read_Key_Hierarchy_Roots command to return the identity root key (if only
|
|
one is available).
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Num_Addresses: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXX | Number of static device addresses |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Static_Address[i]: Size: 6 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXXXXXX | Static device address |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Identity_Root[i]: Size: 16 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | Identity root key (IR) for static |
|
|
| | device address |
|
|
| | |
|
|
| | All zero parameter value indicates |
|
|
| | missing identity root key. |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Static_Addresses command has completed, a Command Complete event
|
|
shall be generated.
|
|
|
|
|
|
Zephyr Read Key Hierarchy Roots Command
|
|
=======================================
|
|
|
|
This commands reads the controller specific identify and encryption root keys.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Key_Hierarchy_Roots | 0x00A | | Status, |
|
|
| | | | Identity_Root, |
|
|
| | | | Encryption_Root |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the identity root key and encryption root key
|
|
programmed by the vendor at manufacturing time. If a key is set to all zeros,
|
|
then the associated key is not available and it should not be used in the key
|
|
hierarchy.
|
|
|
|
The identity root key and encryption root key may be used for the controllers
|
|
public device address or a static random address generated by the host. It
|
|
shall not be used for static addresses returned by Read_Static_Addresses
|
|
command that have its dedicated identity root key assigned.
|
|
|
|
Note: For addresses returned by Read_Static_Addresses with an all zeros
|
|
identity root key, the returned Identity_Root value may be used. It is however
|
|
important that it only gets assigned to a single address (either public or
|
|
static random).
|
|
|
|
Note: The Encryption_Root parameter is only useful for Legacy Pairing. In case
|
|
of Secure Connections it can not be used. The parameter is provided here for
|
|
completeness, but it is encouraged that Controller implementations set this
|
|
value to all zeros.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Identity_Root: Size: 16 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | Identity root key (IR) |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Encryption_Root: Size: 16 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | Encryption root key (ER) |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Key_Hierarchy_Roots command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Read Chip Temperature Command
|
|
====================================
|
|
|
|
This commands reads the controller chip temperature.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Chip_Temperature | 0x00B | | Status, |
|
|
| | | | Temperature |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the current chip temperature in degrees Celsius.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Temperature: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | The measured temperature converted |
|
|
| | to degrees Celsius (signed integer) |
|
|
| | Range: -128 ≤ N ≤ 127 |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Chip_Temperature command has completed, a Command Complete event
|
|
shall be generated.
|
|
|
|
|
|
Zephyr Read Host Stack Commands Command
|
|
=======================================
|
|
|
|
This command reads the list of host stack operation system defined vendor
|
|
commands supported for the local Controller.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Read_Host_Stack_Commands | 0x00C | | Status, |
|
|
| | | | Num_Commands, |
|
|
| | | | Vendor_ID[i], |
|
|
| | | | Opcode_Base[i] |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
This command shall return the list of host stack operation defined vendor
|
|
commands. They are defined based on a vendor identifier and a base opcode.
|
|
|
|
With this command it is possible to incorporate external defined HCI commands
|
|
designed for host stack operation that extend the standard and vendor specific
|
|
Controller commands. See Android [1][2] and Microsoft [3] defined extensions.
|
|
|
|
The Opcode_Base parameter points to an opcode that will identify the external
|
|
command set. Ideally all external commands are multiplexed through that single
|
|
opcode and also define a flexible interface for external events.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Num_Commands: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXX | Total number of commands |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Vendor_ID[i]: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x0001 | Android specific HCI commands |
|
|
| 0x0002 | Microsoft specific HCI commands |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Opcode_Base[i]: Size: 2 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXX | Base opcode of command |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Read_Host_Stack_Commands command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Set Scan Request Reports Command
|
|
=======================================
|
|
|
|
This commands configures the report of Scan_Request_Received events.
|
|
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Command | OCF | Command | Return |
|
|
| | | Parameters | Parameters |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
| Set_Scan_Request_Reports | 0x00D | Enable | Status |
|
|
+--------------------------+-------+--------------------+--------------------+
|
|
|
|
The Enable parameter indicates with the Controller shall send the
|
|
Scan_Request_Received event upon receipt of a scan request PDU that is in an
|
|
response to an advertisement from the specified advertising set that contains
|
|
its device address and is from a scanner that is allowed by the advertising
|
|
filter policy.
|
|
|
|
Note: In case Extended Advertising configuration is used for setting up
|
|
advertising sets, this shall not generate any vendor events.
|
|
|
|
Status: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Command succeeded |
|
|
| 0x01-0xFF | Command failed |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Enable: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Scan request reporting disabled |
|
|
| 0x01 | Scan request reporting enabled |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
When the Set_Scan_Request_Reports command has completed, a Command Complete
|
|
event shall be generated.
|
|
|
|
|
|
Zephyr Vendor Events
|
|
====================
|
|
|
|
The Vendor Event is used to encapsulate all vendor specific events. The event
|
|
code of all vendor events shall be 0xFF. The subevent code is the first octet
|
|
of the event parameters. The subevent code shall be set to one of the valid
|
|
subevent codes from a vendor specific event. All other subevent parameters are
|
|
defined in the vendor specific events.
|
|
|
|
|
|
Zephyr Fatal Error
|
|
==================
|
|
|
|
This event reports a fatal non-recoverable error from the local Controller.
|
|
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Event | Event Code | Event Parameters |
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Fatal_Error | 0xFF | Subevent_Code, |
|
|
| | | Program_Counter, |
|
|
| | | Error_Info |
|
|
+-------------------------------+------------+-------------------------------+
|
|
|
|
The Error_Info provides a string representation of the occurred error. It may
|
|
include information like file name and line numbers.
|
|
|
|
Subevent_Code: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x02 | Subevent code for Fatal Error event |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Program_Counter: Size: 8 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXXXXXXXXXX | Program counter where the error |
|
|
| | occurred |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Error_Info: Size: variable
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | UTF-8 encoded error information |
|
|
+--------------------+--------------------------------------+
|
|
|
|
The event is reported by default unless masked away by Set_Event_Mask command.
|
|
|
|
|
|
Zephyr Trace Information Event
|
|
==============================
|
|
|
|
This event reports the link manager and link layer trace information.
|
|
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Event | Event Code | Event Parameters |
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Trace_Information | 0xFF | Subevent_Code, |
|
|
| | | Trace_Type, |
|
|
| | | Trace_Data |
|
|
+-------------------------------+------------+-------------------------------+
|
|
|
|
The trace type provides information about the link manager protocol or link
|
|
layer control protocol direction information. The trace data is the specific to
|
|
the trace type and represents the protocol specific data.
|
|
|
|
Subevent_Code: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x03 | Subevent code for Trace Information |
|
|
| | event |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Trace_Type: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x01 | LMP TX |
|
|
| 0x02 | LMP RX |
|
|
| 0x03 | LLCP TX |
|
|
| 0x04 | LLCP RX |
|
|
| 0x05 | LE CONN_IND |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Trace_Data: Size: variable
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| | Trace packet data |
|
|
+--------------------+--------------------------------------+
|
|
|
|
The event is only reported when unmasked by Set_Event_Mask command.
|
|
|
|
|
|
Zephyr Scan Request Received Event
|
|
==================================
|
|
|
|
This event indicates that a SCAN_REQ PDU has been received by an advertiser.
|
|
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Event | Event Code | Event Parameters |
|
|
+-------------------------------+------------+-------------------------------+
|
|
| Scan_Request_Received | 0xFF | Subevent_Code, |
|
|
| | | Address_Type, |
|
|
| | | Address, |
|
|
| | | RSSI |
|
|
+-------------------------------+------------+-------------------------------+
|
|
|
|
The request contains a device address from a scanner that is allowed by the
|
|
advertising filter policy.
|
|
|
|
Note: In case Extended Advertising configuration is used for setting up
|
|
advertising sets, this event shall not be generated.
|
|
|
|
Subevent_Code: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x04 | Subevent code for Scan Request |
|
|
| | Received event |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Address_Type: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Public Device Address |
|
|
| 0x01 | Random Device Address |
|
|
| 0x02 | Public Identity Address |
|
|
| 0x03 | Random (static) Identity Address |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Address: Size: 6 Octets
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXXXXXXXXXXXX | Public Device Address, Random Device |
|
|
| | Address, Public Identity Address or |
|
|
| | Random (static) Identity Address of |
|
|
| | the advertising device. |
|
|
+--------------------+--------------------------------------+
|
|
|
|
RSSI: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| N | Size: 1 Octet (signed integer) |
|
|
| | Range: -127 <= N <= +20 |
|
|
| | Units: dBm |
|
|
+--------------------+--------------------------------------+
|
|
| 127 | RSSI is not available |
|
|
+--------------------+--------------------------------------+
|
|
| 21 to 126 | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
The event is only reported when unmasked by Set_Event_Mask command.
|
|
|
|
|
|
Zephyr Vendor Diagnostic Channel
|
|
================================
|
|
|
|
The vendor diagnostic channel allows for an independent side channel to provide
|
|
extra information from the local Controller to the Host.
|
|
|
|
0 8 16 24
|
|
+--------------+--------------+--------------+--------------+
|
|
| Channel Code | Parameter | Channel Parameters
|
|
| | Total Length |
|
|
+--------------+--------------+--------------+--------------+
|
|
|
|
The diagnostic channel provides multiplexing of diagnostic information based on
|
|
a channel code. The channel parameters content depends on the channel code.
|
|
|
|
Channel_Code: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0x00 | Trace Information |
|
|
| TBD | Debug information |
|
|
| All other values | Reserved for future use |
|
|
+--------------------+--------------------------------------+
|
|
|
|
Parameter_Total_Length: Size: 1 Octet
|
|
+--------------------+--------------------------------------+
|
|
| Value | Parameter Description |
|
|
+--------------------+--------------------------------------+
|
|
| 0xXX | Length of all of the parameters |
|
|
| | contained in this packet, measured |
|
|
| | in octets |
|
|
+--------------------+--------------------------------------+
|
|
|
|
For UART transport (H:4) the type 0xFF shall be used. For USB transport (H:2)
|
|
an extra USB endpoint shall be used.
|
|
|
|
|
|
References
|
|
==========
|
|
|
|
[1] https://source.android.com/devices/Android-5.0-Bluetooth-HCI-Reqs.pdf
|
|
[2] https://source.android.com/devices/Android-6.0-Bluetooth-HCI-Reqs.pdf
|
|
[3] https://msdn.microsoft.com/en-us/library/windows/hardware/dn917903.aspx
|