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    | Write Tx Power Level (per Role/Connection) |
	|       | 6    | Read Tx Power Level (per Role/Connection)  |
	|       | 7    | Read USB Supported Transport Modes         |
	+-------+------+--------------------------------------------+
	| 2     | 0    | Set USB Transport Mode                     |
	+-------+------+--------------------------------------------+

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 Write Tx Power Level (per Role/Connection) Command
=========================================================

This command dynamically modifies BLE Tx power level given a handle and a
handle type (advertiser, scanner, connection).

+--------------------------+-------+--------------------+--------------------+
| Command                  | OCF   | Command            | Return             |
|                          |       | Parameters         | Parameters         |
+--------------------------+-------+--------------------+--------------------+
| Write_Tx_Power_Level     | 0x00E | Handle_Type,       | Status,            |
|                          |       | Handle,            | Handle_Type,       |
|                          |       | Tx_Power_Level     | Handle,            |
|                          |       |                    | Selected_Tx_Power  |
+--------------------------+-------+--------------------+--------------------+

The Tx power of the BLE radio interface is modified for any low-level link by
the controller with a high degree of flexibility. The BLE link whose power is
set is identified based on a handle type (advertiser, scanner, connection) and
handle pair.

The role/state defining input parameter is the Handle_Type, whereas its
corresponding handle is provided by the Handle input parameter. Note that
for Advertisements, the Handle input parameter is ignored in the case that
Advertising Extensions are not configured, whereas Advertising Sets are to be
identified by their corresponding Handle in case Advertising Extensions are
enabled.

The desired transmitter power level for the selected link instance is inputted
as Tx_Power_Level. The power setup and control can be performed dynamically
without the need of restarting the advertiser and scanner role/states. In case
of connections, the Tx power changes take effect only if the connections are
in a connected state.

The inputs Handle_Type and Handle are passed through as outputs to aid the
asynchronous service of the command as well. In addition, the command returns
also with the Selected_Tx_Power by the controller which addresses and corrects
the possible mismatches between the desired Tx_Power_Level and the achievable
Tx powers given each individual controller capabilities.

	Handle_Type:                                    Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| 0x00               | Handle of type Advertiser (Adv)      |
	| 0x01               | Handle of type Scanner (Scan)        |
	| 0x02               | Handle of type Connection (Conn)     |
	| 0x03-0xFF          | Reserved (HCI command error)         |
	+--------------------+--------------------------------------+

	Handle:                                        Size: 2 Octets
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	|                    | Handle of the selected Handle_Type   |
	|                    | that identifies the instance to set  |
	|                    | the power of. See below for a        |
	|                    | description corresponding to each    |
	|                    | Handle_Type                          |
	|                    |                                      |
	|                    | Handle_Type_Adv:                     |
	| 0x0000 - 0xFFFF    |     Legacy Advertisement Handle      |
	|                    |     (Handle value is ignored)        |
	| 0x0000 - 0x00EF    |     Advertisement Extensions (AE)    |
	|                    |     enabled Advertisement set        |
	|                    |     Handle                           |
	|                    |                                      |
	|                    | Handle_Type_Scan:                    |
	| 0x0000 - 0xFFFF    |     Scanner Handle (Handle value is  |
	|                    |     ignored)                         |
	|                    |                                      |
	|                    | Handle_Type_Conn:                    |
	| 0x0000 - 0x0EFF    |     Connection Handle                |
	+--------------------+--------------------------------------+

	Tx_Power_Level:                                 Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| -127 <= N <= 126   | The desired Tx_Power_Level in signed |
	|                    | 1 octet integer format to be set to  |
	|                    | the Handle_Type and Handle pair. The |
	|                    | controller  shall choose a power     |
	|                    | level lower than or equal to the one |
	|                    | specified by the host unless the host|
	|                    | desired power is lower than the      |
	|                    | minimum supported Tx power of the    |
	|                    | controller, in which case the        |
	|                    | controller shall use its minimum Tx  |
	|                    | power.                               |
	|                    | Units: dBm                           |
	|                    |                                      |
	| 127                | No preference for the Tx_Power_Level,|
	|                    | the controller shall revert to using |
	|                    | its default setting for Tx power.    |
	+--------------------+--------------------------------------+

	Status:                                         Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| 0x00               | Command succeeded                    |
	| 0x01-0xFF          | Command failed                       |
	+--------------------+--------------------------------------+

	Selected_Tx_Power:                              Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| -127 <= N <= 126   | The controller selected Tx power to  |
	|                    | set for the given Handle_Type and    |
	|                    | and pair formatted as a 1 octet      |
	|                    | signed integer. The controller shall |
	|                    | not modify this transmit power unless|
	|                    | it is directed to do so by the Host. |
	|                    | Units: dBm                           |
	+--------------------+--------------------------------------+

When the Write_Tx_Power_Level command has completed, a Command Complete
event shall be generated.


Zephyr Read Tx Power Level (per Role/Connection) Command
========================================================

This command reads the BLE Tx power level. In contrast to the standardized HCI
command, i.e. Read_Transmit_Power_Level, which returns the transmitted power
level only for a specified connection handle, this command operates for both
connected and unconnected states. It gets the BLE Tx power level for any given
handle type (advertiser, scanner, connection) and handle.

+--------------------------+-------+--------------------+--------------------+
| Command                  | OCF   | Command            | Return             |
|                          |       | Parameters         | Parameters         |
+--------------------------+-------+--------------------+--------------------+
| Read_Tx_Power_Level      | 0x00F | Handle_Type,       | Status,            |
|                          |       | Handle             | Handle_Type,       |
|                          |       |                    | Handle,            |
|                          |       |                    | Tx_Power_Level     |
+--------------------------+-------+--------------------+--------------------+

The Tx power of the BLE radio interface used for a low-level link identified
by a pair of Handle_Type and Handle is retrieved from the controller.

The role/state defining input parameter is the Handle_Type, whereas its
corresponding handle is provided by the Handle input parameter. Note that
for Advertisements, the Handle input parameter is ignored in the case that
Advertising Extensions are not configured, whereas Advertising Sets are to be
identified by their corresponding Handle in case Advertising Extensions are
enabled.

The command returns with an operational Status, and the replicated Handle_Type
and Handle input parameters supplemented by the current Tx_Power_Level in use
by the controller for the requested Handle_Type and Handle.

	Handle_Type:                                    Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| 0x00               | Handle of type Advertiser (Adv)      |
	| 0x01               | Handle of type Scanner (Scan)        |
	| 0x02               | Handle of type Connection (Conn)     |
	| 0x03-0xFF          | Reserved (HCI command error)         |
	+--------------------+--------------------------------------+

	Handle:                                        Size: 2 Octets
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	|                    | Handle of the selected Handle_Type   |
	|                    | that identifies the instance to read |
	|                    | the power of. See below for a        |
	|                    | description corresponding to each    |
	|                    | Handle_Type                          |
	|                    |                                      |
	|                    | Handle_Type_Adv:                     |
	| 0x0000 - 0xFFFF    |     Legacy Advertisement Handle      |
	|                    |     (Handle value is ignored)        |
	| 0x0000 - 0x00EF    |     Advertisement Extensions (AE)    |
	|                    |     enabled Advertisement set        |
	|                    |     Handle                           |
	|                    |                                      |
	|                    | Handle_Type_Scan:                    |
	| 0x0000 - 0xFFFF    |     Scanner Handle (Handle value is  |
	|                    |     ignored)                         |
	|                    |                                      |
	|                    |                                      |
	|                    | Handle_Type_Conn:                    |
	| 0x0000 - 0x0EFF    |     Connection Handle                |
	+--------------------+--------------------------------------+

	Status:                                         Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| 0x00               | Command succeeded                    |
	| 0x01-0xFF          | Command failed                       |
	+--------------------+--------------------------------------+

	Tx_Power_Level:                                 Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| -127 <= N <= 126   | The current Tx_Power_Level formatted |
	|                    | as a 1 octet signed integer at which |
	|                    | the controller is operating the      |
	|                    | low-level link identified by the     |
	|                    | Handle_Type and Handle pair.         |
	|                    | Units: dBm                           |
	+--------------------+--------------------------------------+

When the Read_Tx_Power_Level command has completed, a Command Complete
event shall be generated.

Zephyr Read Supported USB Transport Modes Command
=================================================

This command read the supported USB transport modes.

+--------------------------+-------+--------------------+--------------------+
| Command                  | OCF   | Command            | Return             |
|                          |       | Parameters         | Parameters         |
+--------------------------+-------+--------------------+--------------------+
| Read_USB_Transport_Modes | 0x010 |                    | Status             |
|                          |       |                    | Num_Supported_Modes|
|                          |       |                    | Supported_Mode[i]  |
+--------------------------+-------+--------------------+--------------------+

	Supported_Mode:                                 Size: 1 Octet
	+--------------------+--------------------------------------+
	| Value              | Parameter Description                |
	+--------------------+--------------------------------------+
	| 0x00               | USB standard (H:2) transport mode.   |
	|                    | Standard mode which use dedicated    |
	|                    | endpoints for commands, events and   |
	|                    | data.                                |
	| 0x01               | Serial (H:4) transport mode.         |
	|                    | Serialize all traffic into bulk      |
	|                    | endpoints.                           |
	| All other values   | Reserved for future use              |
	+--------------------+--------------------------------------+

When the Read_USB_Transport_Mode command has completed, a Command Complete
event shall be generated.

Zephyr Set USB Transport Mode Command
=====================================

This command set the host transport mode and reset the controller states like
an HCI Reset command.

+--------------------------+-------+--------------------+--------------------+
| Command                  | OCF   | Command            | Return             |
|                          |       | Parameters         | Parameters         |
+--------------------------+-------+--------------------+--------------------+
| Set_USB_Transport_Mode   | 0x011 | Mode               | Status             |
+--------------------------+-------+--------------------+--------------------+

When the Set_USB_Transport_Mode 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