Detailed Description

Introduction

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.

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:

The following type is used for the Bluetooth device address.

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.

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:

• An API function for sending data to HCI
• A callback function for receiving data from HCI, and a callback function for managing flow control.

ACL data is sent using HciSendAclData(). The ACL packet is formatted as defined in the Bluetooth Core Specification document:

• The first two bytes of the buffer contain the handle for the ACL connection.
• The next two bytes of the buffer contain the length.

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:

• The first two bytes of the buffer contain the handle for the ACL connection.
• The next two bytes of the buffer contain the length.

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.

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.

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.

Figure 5. Data Transmit and Receive