| 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 |
