Host Controller Interface Collection Overview
The conceptual layer that connects the Symbian platform Bluetooth stack to Bluetooth hardware (Bluetooth Controller and Bluetooth chipset).
Purpose
This is a guide to the Symbian platform Bluetooth HCI (Host Controller Interface) layer. HCI is the conceptual layer which connects the Symbian platform Bluetooth stack to Bluetooth hardware (Bluetooth Controller and Bluetooth chipset). The HCI layer must be adapted to match the hardware chosen by the device creator. This guide should be read in conjunction with the rest of the Bluetooth documentation, in particular in conjunction with the Bluetooth Overview.
Architecture
The HCI layer is between the Symbian platform Bluetooth Stack and the Bluetooth hardware. The HCI layer consists of the following six components:
Core HCI Plugin including the HCI Server.
What is the HCI layer
The HCI layer is a set of components between the Symbian platform Bluetooth Stack and the Bluetooth hardware. The HCI layer uses the Bluetooth standard Host Controller Transport Layer (HCTL) to send commands to the Bluetooth hardware and to receive events from the Bluetooth hardware.
What are the Bluetooth HCI Plugins
A number of the components of the Symbian platform Bluetooth HCI layer can be customised or replaced by the device creator. Symbian provides reference implementations for each of these components as ECom plugin modules.
Which components need to be customised or replaced
Any of the components, except for the Command Queue, can be customised or replaced by the device creator. The usual reason for customising a component is to adjust it to match the particular Bluetooth hardware selected. For example, the HCTL Plugin can talk to the Bluetooth Controller using one of a number of different methods including UART (H4 transport), BCSP or the H4 reference board HighSpeed method. The device creator must customise the HCTL Plugin to use the communication method that matches the hardware they have chosen.
This document is an overview of each of the HCI layer components. More detail on each component and what can be changed in a plugin can be found in the Bluetooth HCI v2 Design Specification.
Description
The central component of the HCI layer. The Core HCI Plugin is the first plugin to be executed. The Core HCI Plugin uses the Controller Initialisation Plugin to initialise the Bluetooth hardware by sending commands to the Bluetooth Controller through the HCTL Plugin.
The reference implementation provided by Symbian can be used without customisation. A device creator may choose to replace this implementation if, for example, they wish to avoid using the ECom Plugins.
A Symbian provided component that receives commands from the Symbian platform Bluetooth Stack and sends them to the Bluetooth Controller using the HCTL Plugin.
In a previous implementation of the HCI each command and each event was an API in the Symbian platform Bluetooth stack.
The use of the Command Queue allows:
the Bluetooth stack to have a single API for sending commands
the HCI layer to modify commands
the HCI layer to apply timeouts
easier customisation of commands for specific Bluetooth hardware.
The implementation provided is not directly customisable. If you wish to adjust the contents and sequence of commands then use the Queue Decision Plugin to modify and override command contents.
Controller Initialisation Plugin
When Bluetooth is started or restarted (perhaps after an error), the Core HCI Plugin uses the Controller Initialisation Plugin to initialise the Bluetooth hardware. The Bluetooth Stack sends a standard HCI "reset" command. The Controller Initialisation Plugin is called before the reset is sent to the Bluetooth hardware and sends any pre-reset commands. Examples of pre-reset commands are: memory clean-up, statistical information collection and log collection. After the reset command is sent to the Bluetooth hardware the Controller Initialisation Plugin may send additional commands required. These post-reset commands are sent if the commands are necessary for that particular Bluetooth hardware. Examples of post-reset commands are: commands to put the Bluetooth hardware into a state ready for further commands, and commands to handle events that occur during the initialisation.
As the specific sequence of actions, timing and the resulting events are specific to each Bluetooth chipset and to each Bluetooth Controller, the Controller Initialisation Plugin must be modified by the device creator to match the chosen hardware.
The Queue Decision Plugin inspects the commands sent by the Symbian platform Bluetooth Stack. The QDP modifies those commands as necessary for the particular Bluetooth hardware selected.
There are a number of reasons to modify the commands from the Symbian platform Bluetooth stack. These include:
Provide a workaround - A command from the Symbian platform Bluetooth Stack may have to be rewritten or replaced with one or more different commands to address a defect in the Bluetooth hardware.
Timeouts - The QDP can provide a timer and reissue commands if an event is not received within a defined time.
Resend a command - If a command fails, the QDP can resend the command.
Command blocking - The QDP can act as a gate to prevent a command overflow in the hardware, or to wait for a previous command to complete so that the next command will execute correctly.
Handle unexpected events - If an event is recieved that is not expected in normal processing and cannot be matched to an outstanding command, the QDP can process the event. The QDP can, for example, choose to reset the Controller if it believes the unexpected event is an indication of a problem.
Reject commands - There may be commands sent by the Symbian platform Bluetooth Stack that cannot be handled by the Bluetooth controller, either because of a current status or in general. The QDP can send back an error event to the Bluetooth Stack.
Change command parameters - The Bluetooth hardware may require the parameters for a command to be modified in a particular situation. For example, to hand a particular hardware or link state. The QDP can modify the command parameters to match the requirements of the Bluetooth hardware.
If a parameter has to be modified in the same way every time it is used, do not use the QDP to change it each time. Instead change the parameter set function in the Commands and Events class definition for that parameter in that command.
The QDP does not need to be customised by a device creator unless there are commands that need to be changed to support the Bluetooth Controller and chipset selected.
Host Controller Transport Layer (HCTL) Plugin
The HCTL provides the transport mechanism to pass the commands from the HCI layer to the Bluetooth Controller and to receive the events that the Bluetooth Controller sends.
The protocol for sending commands and receiving events is defined by the Bluetooth SIG, but the transport mechanism is implementation dependent. The Symbian-supplied reference implementation includes code for using a UART (H4 transport) or other BCSP or for using the HighSpeed transport for the TI hardware reference board (H4 reference board). The reference implementation can be used unless the device creator needs to support a different transport mechanism for commands and events between the Symbian platform Bluetooth Stack and the Bluetooth Controller.
This component contains detailed knowledge of the commands that can be sent to the Bluetooth Controller and the events that can be received from the Bluetooth Controller.
The reference implementation provided by Symbian covers all the standard commands and events (currently 114 commands and 36 events). The device creator can modify this implementation or create their own, to support the commands and events that the chosen Bluetooth hardware expects and provides.
Note: The implementation of the Commands and Events component is owned by the device creator. The Commands and Events component interface is defined and owned by Symbian and must not be modified as it is used by the Command Queue, the Bluetooth Stack, the Core HCI and optionally by the Controller Initialisation Plugin.