Modules | |
| Generic HCI Definitions | |
| HCI Initialization, Regisration, Reset | |
| HCI Command Interface | |
| HCI Optimization Interface | |
| HCI Event Interface | |
| HCI ACL Data Interface | |
The HCI subsystem implements the host-controller interface specification. This specification defines commands, events, and data packets sent between a Bluetooth LE protocol stack on a host and a link layer on a controller.
The HCI API is optimized to be a thin interface layer for a single-chip system. It is configurable for either a single-chip system or traditional system with wired HCI.
This configurability is accomplished through a layered implementation. A routing layer can be configured for either a single-chip system or wired HCI. A transport and driver layer below the routing layer can be configured for different wired transports such as UART or USB.
HCI also contains certain configurable initialization features which are executed as part of the stack initialization.
For full API, see Generic HCI Definitions
This page describes the API for the Host Controller Interface (HCI) layer of ARM’s Bluetooth LE protocol stack.
This API is used by the Bluetooth LE stack to communicate with a Bluetooth LE controller or link layer. Traditionally, HCI is a message passing interface consisting of command and event messages defined by the Bluetooth specification.
The Bluetooth specification defines the HCI messages and parameters. Rather than repeat that information here, this document describes how details of the API implementation differ from the Bluetooth Core Specification.
The different HCI topologies for a single-chip system and a traditional stack with HCI are shown below in Figure 2.
In a single-chip system the HCI layer mainly serves two purposes. First, it implements a message passing interface between the stack and the link layer. Second, it translates the HCI API used by the stack (as defined in this document) to the API used by the link layer.
In a traditional stack with HCI, the HCI layer serves several purposes. It implements a message passing interface between the stack and the wired transport. It builds and parses byte-oriented messages for transmission on the wired transport. It also implements a transport-specific driver to send and receive data on the wired transport.
There are also differences in the data flow. In a traditional stack, the HCI layer also implements handling of transmit path data flow and processing of HCI Number of Completed Packets events. In a single-chip system the HCI layer adapts the data path interface required by the stack to the link layer’s data path.
The Bluetooth HCI specification defines parameters in terms of octets. These octets map to integer data types as shown below:
| Octets | Stack Data Types |
|---|---|
| 1 Octet | int8_t or uint8_t |
| 2 Octets | uint16_t |
| 3 or 4 Octets | uint32_t |
| > 4 Octets | uint8_t array or other data structure |
The following type is used for the Bluetooth device address.
| Type | Name |
|---|---|
| uint8_t | bdAddr_t[6] |
A Reset of the HCI reset sequence is initiated by a call to HciResetSequence(). This function initiates an HCI reset sequence, which sends an HCI Reset command followed by several other HCI commands. This HCI command sequence is configurable for each platform. When the reset sequence is complete, a Reset Sequence Complete event is sent via the event callback.
Syntax:
void HciResetSequence(void)
A typical reset sequence is as follows:
See HCI Initialization, Regisration, Reset for API.
This is an optimized interface for certain HCI commands that simply read a value. The stack uses these functions rather than their corresponding functions in the command interface.
These functions can only be called after the reset sequence has been completed.
See HCI Optimization Interface for API.
This interface contains functions that map directly to HCI commands. The operation of the HCI commands and their parameters are not described in this document. See the Bluetooth Core Specification document.
The HCI implementation for a particular platform does not need to implement all functions in the command interface. For example, a single-chip system that implements the functions in the optimization interface, such as HciGetBdAddr(), might not need to implement the corresponding functions in the command interface (for example HciReadBdAddrCmd()).
See HCI Command Interface for API.
The command interface functions are shown in the table below. See the Bluetooth Core Specification document for a description of the parameters and operation of these functions. Functions shown as not implemented are not used by ARM’s Bluetooth LE stack.
| HCI Command | Function |
|---|---|
| Disconnect | HciDisconnectCmd |
| Read Remote Version Information | HciReadRemoteVerInfoCmd |
| Set Event Mask | HciSetEventMaskCmd |
| Reset | HciResetCmd |
| Read Transmit Power Level | HciReadTxPwrLvlCmd |
| Set Controller To Host Flow Control | Not Supported |
| Host Buffer Size | Not Supported |
| Host Number of Completed Packets | Not Supported |
| Set Event Mask Page 2 | HciSetEventMaskPage2Cmd |
| Read Authenticated Payload Timeout | HciReadAuthPayloadTimeout |
| Write Authenticated Payload Timeout | HciWriteAuthPayloadTimeout |
| Read Local Version Information | HciReadLocalVerInfoCmd |
| Read Local Supported Features | HciReadLocalSupFeatCmd |
| Read Buffer Size | HciReadBufSizeCmd |
| Read BD_ADDR | HciReadBdAddrCmd |
| Read RSSI | HciReadRssiCmd |
| LE Set Event Mask | HciLeSetEventMaskCmd |
| LE Read Buffer Size | HciLeReadBufSizeCmd |
| LE Read Local Supported Features | HciLeReadLocalSupFeatCmd |
| LE Set Random Address | HciLeSetRandAddrCmd |
| LE Set Advertising Parameters | HciLeSetAdvParamCmd |
| LE Read Advertising Channel TX Power | HciLeReadAdvTXPowerCmd |
| LE Set Advertising Data | HciLeSetAdvDataCmd |
| LE Set Scan Response Data | HciLeSetScanRespDataCmd |
| LE Set Advertise Enable | HciLeSetAdvEnableCmd |
| LE Set Scan Parameters | HciLeSetScanParamCmd |
| LE Set Scan Enable | HciLeSetScanEnableCmd |
| LE Create Connection | HciLeCreateConnCmd |
| LE Create Connection Cancel | HciLeCreateConnCancelCmd |
| LE Read White List Size | HciLeReadWhiteListSizeCmd |
| LE Clear White List | HciLeClearWhiteListCmd |
| LE Add Device to White List | HciLeAddDevWhiteListCmd |
| LE Remove Device from White List | HciLeRemoveDevWhiteListCmd |
| LE Connection Update | HciLeConnUpdateCmd |
| LE Set Host Channel Classification | HciLeSetHostChanClassCmd |
| LE Read Channel Map | HciLeReadChanMapCmd |
| LE Read Remote Used Features | HciLeReadRemoteFeatCmd |
| LE Encrypt | HciLeEncryptCmd |
| LE Rand | HciLeRandCmd |
| LE Start Encryption | HciLeStartEncryptionCmd |
| LE Long Term Key Request Negative Reply | HciLeLtkReqNegReplCmd |
| LE Long Term Key Requested Reply | HciLeLtkReqReplCmd |
| LE Read Supported States | HciLeReadSupStatesCmd |
| LE Receiver Test | Not Supported |
| LE Transmitter Test | Not Supported |
| LE Test End | Not Supported |
| LE Remote Connection Parameter Request Reply | HciLeRemoteConnParamReqReply |
| LE Remote Connection Parameter Request Negative Reply | HciLeRemoteConnParamReqNegReply |
| LE Set Data Length | HciLeSetDataLen |
| LE Read Suggested Default Data Length | HciLeReadDefDataLen |
| LE Write Suggested Default Data Length | HciLeWriteDefDataLen |
| LE Read Local P-256 Public Key | HciLeReadLocalP256PubKey |
| LE Generate DH Key | HciLeGenerateDHKey |
| LE Add Device to Resolving List | HciLeAddDeviceToResolvingListCmd |
| LE Remove Device from Resolving List | HciLeRemoveDeviceFromResolvingList |
| LE Clear Resolving List | HciLeClearResolvingList |
| LE Read Resolving List Size | HciLeReadResolvingListSize |
| LE Read Peer Resolvable Address | HciLeReadPeerResolvableAddr |
| LE Read Local Resolvable Address | HciLeReadLocalResolvableAddr |
| LE Set Address Resolution Enable | HciLeSetAddrResolutionEnable |
| LE Set Resolvable Private Address Timeout | HciLeSetResolvablePrivateAddrTimeout |
| LE Read Maximum Data Length | HciLeReadMaxDataLen |
| LE Read PHY | HciLeReadPhyCmd |
| LE Set Default PHY | HciLeSetDefaultPhyCmd |
| LE Set PHY | HciLeSetPhyCmd |
| LE Enhanced Receiver Test | Not Supported |
| LE Enhanced Transmitter Test | Not Supported |
| LE Set Advertising Set Random Address | HciLeSetAdvSetRandAddrCmd |
| LE Set Extended Advertising Parameters | HciLeSetExtAdvParamCmd |
| LE Set Extended Advertising Data | HciLeSetExtAdvDataCmd |
| LE Set Extended Scan Response Data | HciLeSetExtScanRespDataCmd |
| LE Set Extended Advertising Enable | HciLeSetExtAdvEnableCmd |
| LE Read Maximum Advertising Data Length | HciLeReadMaxAdvDataLen |
| LE Read Number of Supported Advertising Sets | HciLeReadNumSupAdvSets |
| LE Set Periodic Advertising Parameters | HciLeSetPerAdvParamCmd |
| LE Set Periodic Advertising Data | HciLeSetPerAdvDataCmd |
| LE Set Periodic Advertising Enabled | HciLeSetPerAdvEnableCmd |
| LE Remove Advertising Set | HciLeRemoveAdvSet |
| LE Clear Advertising Sets | HciLeClearAdvSets |
| LE Set Extended Scanning Parameters | HciLeSetExtScanParamCmd |
| LE Set Extended Scan Enable | HciLeExtScanEnableCmd |
| LE Extended Create Connection | HciLeExtCreateConnCmd |
| LE Periodic Advertising Create Sync | HciLePerAdvCreateSyncCmd |
| LE Periodic Advertising Create Sync Cancel | HciLePerAdvCreateSyncCancelCmd |
| LE Periodic Advertising Terminate Sync | HciLeAddDeviceToPerAdvListCmd |
| LE Add Device to Periodic Advertiser List | HciLeAddDeviceToPerAdvListCmd |
| LE Remove Device from Periodic Advertiser List | HciLeRemoveDeviceFromPerAdvListCmd |
| LE Clear Periodic Advertiser List | HciLeClearPerAdvListCmd |
| LE Read Periodic Advertiser List Size | HciLeReadPerAdvListSizeCmd |
| LE Read Transmit Power | HciLeReadTxPower |
| LE Read RF Path Compensation | HciLeReadRfPathComp |
| LE Write RF Path Compensation | HciLeWriteRfPathComp |
| LE Set Privacy Mode | HciLeSetPrivacyModeCmd |
| Vendor Specific | HciVendorSpecificCmd |
The event interface defines event data structures which are passed from HCI to the stack. HCI events and their parameters defined in the Bluetooth Core Specification document are mapped to internal event values and data structures that can be processed efficiently by the stack.
See HCI Event Interface for event interface details.
The ACL data interface contains the following functions:
ACL data is sent using HciSendAclData(). The ACL packet is formatted as defined in the Bluetooth Core Specification document:
The caller of this function is responsible for allocating the WSF buffer pointed to by pAclData. HCI is responsible for deallocating the buffer.
ACL data is received by the stack from HCI through the hciAclCback_t callback. HCI allocates the WSF buffer pointed to by pData. The stack is responsible for deallocating the buffer. The ACL packet is formatted as defined the Bluetooth Core Specification document:
ACL data manages flow control with the hciFlowCback_t callback. If parameter flowDisabled is TRUE then the stack cannot send ACL data to HCI. If flowDisabled is FALSE then data flow can resume on the specified connection handle.
See HCI ACL Data Interface for API.
Figure 3 shows the operation of the reset sequence.
Figure 4 shows an HCI command and event.
Figure 5 shows ACL data transmit and receive.
For receive data, the controller sends an ACL data packet to HCI, processes the packet and calls the ACL data callback to send the packet to L2CAP.
