Mistake on this page? Email us
Modules
Host Controller Interface (HCI)

Modules

 Generic HCI Definitions
 
 HCI Initialization, Regisration, Reset
 
 HCI Command Interface
 
 HCI Optimization Interface
 
 HCI Event Interface
 
 HCI ACL Data Interface
 

Detailed Description

Introduction

diagram_hci.png
Figure 1. BLE Stack: HCI

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

Overview

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.

HCI Topologies

The different HCI topologies for a single-chip system and a traditional stack with HCI are shown below in Figure 2.

diagram_hci_topo.png
Figure 2. HCI Topologies

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.

Basic Data Types

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]

Initialization, Registration, and Reset

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:

  1. Reset Command
  2. Set Event Mask Command
  3. LE Set Event Mask Command
  4. Set Event Mask Page 2 Command
  5. Read BD_ADDR Command
  6. LE Read Buffer Size Command
  7. Read Buffer Size Command
  8. LE Read Supported States Command
  9. LE Read White List Size Command
  10. LE Read Local Supported Feature Command
  11. LE Read Resolving List Size Command
  12. LE Read Maximum Data Length Command
  13. LE Write Suggested Default Data Length Command
  14. LE Random Command

See HCI Initialization, Regisration, Reset for API.

Optimization Interface

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.

Command Interface

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.

Commands

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

Event Interface

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.

ACL Data Interface

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.

Usage Scenarios

Reset

Figure 3 shows the operation of the reset sequence.

  1. The DM subsystem of the stack calls HciResetSequence() to initiate the reset sequence.
  2. HCI begins sending a sequence of HCI commands to the controller, starting with the HCI Reset command.
  3. After each command a Command Complete event is received.
  4. HCI continues sending commands until it has sent all the commands in its sequence.
  5. When it has received a Command Complete event for the last command it calls the event callback and sends a Reset Sequence Complete event.
operation_hci_reset.png
Figure 3. Reset

HCI Command and Event

Figure 4 shows an HCI command and event.

  1. The DM subsystem of the stack calls an HCI function to create a connection.
  2. HCI sends an LE Create Connection command to the controller.
  3. The controller responds with a Command Status event. Note: This event is not sent to the stack; it is processed internally by HCI.
  4. The controller sends an LE Connection Complete event.
  5. HCI calls the event callback and sends an LE Connection Complete event to the stack.
operation_hci_cmdevt.png
Figure 4. HCI Command and Resulting Event

ACL Data Transmit and Receive

Figure 5 shows ACL data transmit and receive.

  1. The L2CAP layer of the stack calls function HciSendAclData() to send data from the stack to HCI.
  2. HCI builds and sends an ACL data packet to the controller.
  3. The controller then sends a Number of Completed Packets event to HCI and HCI processes this event internally without passing it to the stack.

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.

operation_hci_acl.png
Figure 5. Data Transmit and Receive


Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.