csr’s implementation of hci on bluecore an107read.pudn.com/downloads287/doc/1296035/141_hci... ·...

bc01-an-107d © Copyright CSR 2001This material is subject to CSR’s non-disclosure agreement.

§

CSR

Unit 400 Cambridge Science ParkMilton Road Cambridge

CB4 0WHUnited Kingdom

Registered in England 3665875

Tel: +44 (0)1223 692000 Fax: +44 (0)1223 692001

www.csr.com

BlueCore™

CSR’s Implementation of HCI on BlueCore

AN107

October 2002

Contents

bc01-an-107d © Copyright CSR 2001This material is subject to CSR’s non-disclosure agreement. of 36

Imp

lemen

tation

of H

CI o

n B

lueC

ore

Contents1 Introduction.......................................................................................................................................................................4

1.1 Purpose..................................................................................................................................................................4

2 Overview............................................................................................................................................................................5

2.1 Firmware Builds for BlueCore01b and BlueCore2-External..........................................................................5

2.2 HCI on BlueCore ..................................................................................................................................................5

2.3 Programmable Interfaces ....................................................................................................................................5

3 ACL Connections ............................................................................................................................................................6

3.1 Number of Connections .......................................................................................................................................6

3.2 Host-to-Host Controller Data Flow.....................................................................................................................6

3.3 Host Controller-to-Host Data Flow.....................................................................................................................6

4 SCO Connections ............................................................................................................................................................8

4.1 Number of Connections .......................................................................................................................................8

4.2 Host Transports ....................................................................................................................................................8

4.3 PSKEY_HOSTIO_MAP_SCO_PCM..................................................................................................................8

4.4 BCCMD MAP_SCO_PCM...................................................................................................................................8

4.5 SCO Data Rate Compensation....................................................................................................................... 10

4.6 Loopback SCO Data Rate Compensation .................................................................................................... 11

4.7 Transparent SCO Data Rate Compensation ................................................................................................ 12

4.8 SCO Data over HCI: Host Transport Bandwidth .......................................................................................... 12

5 HCI Commands ............................................................................................................................................................. 13

5.1 (HCI: 4.5.1) INQUIRY........................................................................................................................................ 13

5.2 (HCI: 4.5.3) PERIODIC_INQUIRY_MODE.................................................................................................... 13

5.3 (HCI: 4.5.5) CREATE_CONNECTION ........................................................................................................... 13

5.4 (HCI: 4.5.6) DISCONNECT.............................................................................................................................. 14

5.5 (HCI: 4.5.8) ACCEPT_CONNECTION_REQUEST ..................................................................................... 14

5.6 (HCI: 4.5.10) LINK_KEY_REQUEST_REPLY.............................................................................................. 14

5.7 (HCI: 4.5.11) LINK_KEY_REQUEST_NEGATIVE_REPLY........................................................................ 14

5.8 (HCI: 4.5.12) PIN_CODE_REQUEST_REPLY............................................................................................. 14

5.9 (HCI: 4.5.13) PIN_CODE_REQUEST_NEGATIVE_REPLY...................................................................... 15

5.10 (HCI: 4.5.14) CHANGE_CONNECTION_PACKET_TYPE......................................................................... 15

5.11 (HCI: 4.5.16) SET_CONNECTION_ENCRYPTION..................................................................................... 15

5.12 (HCI: 4.5.17) CHANGE_CONNECTION_LINK_KEY.................................................................................. 15

5.13 (HCI: 4.5.18) MASTER_LINK_KEY................................................................................................................ 15

5.14 (HCI: 4.5.19) REMOTE_NAME_REQUEST.................................................................................................. 15

5.15 (HCI: 4.5.22) READ_CLOCK_OFFSET......................................................................................................... 16

5.16 (HCI: 4.6.1) HOLD_MODE............................................................................................................................... 16

5.17 (HCI: 4.6.2) SNIFF_MODE............................................................................................................................... 16

5.18 (HCI: 4.6.4) PARK_MODE ............................................................................................................................... 16

5.19 (HCI: 4.6.6) QOS_SETUP................................................................................................................................ 17

5.20 (HCI: 4.6.8) SWITCH_ROLE ........................................................................................................................... 17

5.21 (HCI: 4.7.2) RESET........................................................................................................................................... 18

5.22 (HCI: 4.7.3) SET_EVENT_FILTER................................................................................................................. 18

5.23 (HCI: 4.7.4) FLUSH........................................................................................................................................... 19

5.24 (HCI: 4.7.7) CREATE_NEW_UNIT_KEY....................................................................................................... 19

5.25 (HCI: 4.7.9) WRITE_STORED_LINK_KEY................................................................................................... 19

5.26 (HCI: 4.7.10) DELETE_STORED_LINK_KEY.............................................................................................. 20

Contents


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.27 (HCI: 4.7.11) CHANGE_LOCAL_NAME ........................................................................................................ 20

5.28 (HCI: 4.7.18) WRITE_SCAN_ENABLE.......................................................................................................... 20

5.29 (HCI: 4.7.24) WRITE_AUTHENTICATION_ENABLE.................................................................................. 21

5.30 (HCI: 4.7.26) WRITE_ENCRYPTION_MODE............................................................................................... 21

5.31 (HCI: 4.7.28) WRITE_CLASS_OF_DEVICE................................................................................................. 21

5.32 (HCI: 4.7.30) WRITE_VOICE_SETTING....................................................................................................... 21

5.33 (HCI: 4.7.31) WRITE_AUTOMATIC_FLUSH_TIMEOUT............................................................................ 22

5.34 (HCI: 4.7.34) WRITE_NUM_BROADCAST_RETRANSMISSIONS.......................................................... 22

5.35 (HCI: 4.7.37) READ_TRANSMIT_POWER_LEVEL .................................................................................... 22

5.36 (HCI: 4.7.39) WRITE_SCO_FLOW_CONTROL_ENABLE......................................................................... 22

5.37 (HCI: 4.7.42) HOST_NUMBER_OF_COMPLETED_PACKETS................................................................ 22

5.38 (HCI: 4.7.40) SET_HOST_CONTROLLER_TO_HOST_FLOW_CONTROL .......................................... 22

5.39 (HCI: 4.7.44) WRITE_LINK_SUPERVISION_TIMEOUT............................................................................ 23

5.40 (HCI: 4.7.45) READ_NUMBER_OF_SUPPORTED_IAC............................................................................ 23

5.41 (HCI: 4.7.51) WRITE_PAGE_SCAN_MODE ................................................................................................ 23

5.42 (HCI: 4.8.1) READ_LOCAL_VERSION_INFORMATION ........................................................................... 24

5.43 (HCI: 4.8.2) READ_LOCAL_SUPPORTED_FEATURES........................................................................... 24

5.44 (HCI: 4.8.3) READ_BUFFER_SIZE................................................................................................................ 25

5.45 (HCI: 4.8.4) READ_COUNTRY_CODE ......................................................................................................... 26

5.46 (HCI: 4.8.5) READ_BD_ADDR........................................................................................................................ 26

5.47 (HCI: 4.9.3) GET_LINK_QUALITY.................................................................................................................. 26

5.48 (HCI: 4.9.4) READ_RSSI.................................................................................................................................. 27

5.49 (HCI: 4.10.2) WRITE_LOOPBACK_MODE................................................................................................... 27

6 HCI Events...................................................................................................................................................................... 29

6.1 (HCI: 5.2.13) QOS_SETUP_COMPLETE...................................................................................................... 29

6.2 (HCI: 5.2.14) COMMAND_COMPLETE......................................................................................................... 29

6.3 (HCI: 5.2.15) COMMAND_STATUS............................................................................................................... 29

6.4 (HCI: 5.2.16) HARDWARE_ERROR .............................................................................................................. 29

6.5 (HCI: 5.2.17) FLUSH OCCURRED ................................................................................................................ 30

7 Manufacturer-Specific HCI Extensions .................................................................................................................. 31

8 Emission of HCI Events.............................................................................................................................................. 32

9 Document References................................................................................................................................................ 34

Acronyms and Definitions ................................................................................................................................................. 35

Record of Changes.............................................................................................................................................................. 36

List of FiguresFigure 4.1: Locally Created SCO Link...................................................................................................................................9

Figure 4.2: Remotely Created SCO Link...............................................................................................................................9

Figure 5.1: Remote Loopback.............................................................................................................................................. 28

List of TablesTable 4.1: SCO (from Air to Host) ....................................................................................................................................... 10

Table 4.2: SCO (from Host to Air)........................................................................................................................................ 11

Table 5.1: BuildIDs for HCIStack1.1v12.x, HCIStack1.1v13.x and HCIStack1.1v14.x............................................... 24

Table 5.2: READ_BUFFER_SIZE Command Returned Values .................................................................................... 25

Table 5.3: BER Values to 0.1% ........................................................................................................................................... 26

Table 5.4: BER Values Over 0.1% ...................................................................................................................................... 27

Table 8.1: Emission of HCI Events...................................................................................................................................... 33

Introduction


Imp

lemen

tation

of H

CI o

n B

lueC

ore

1 Introduction

1.1 Purpose

This document describes how CSR has implemented Host Controller Interface (HCI) for its BlueCore™ chips:

§ HCIStack1.1v12.x and HCIStack1.1v13.x builds for BlueCore01b

§ HCIStack1.1v14.x and HCIStack1.1v15.x builds for BlueCore2-External

In particular, it fills gaps left as “manufacturer-specific” in the HCI specification.

There is no guarantee that features described here will be part of future builds.

This document is not a general primer on HCI; the Bluetooth™ Specification v1.1 is the best reference for this.

Overview


Imp

lemen

tation

of H

CI o

n B

lueC

ore

2 Overview

2.1 Firmware Builds for BlueCore01b and BlueCore2-External

There are currently two major versions of firmware for CSR’s Bluetooth chips:

HCI builds implementing a conventional Host Controller Interface (HCI) Bluetooth module.

RFCOMM builds adding L2CAP, RFCOMM and SDP to a conventional HCI build. This pushes thehost/module boundary to the top of RFCOMM, reducing the host’s processor load. However, this build ismainly used to support BlueLab™, which uses the firmware’s virtual machine (VM). An RFCOMM build usingthe VM can remove the need for a separate host.

This document is concerned almost entirely with HCI builds:

§ HCIStack1.1v12.x and HCIStack1.1v13.x builds run on BlueCore01b.

§ HCIStack1.1v14.x and HCIStack1.1v15.x builds run on BlueCore2-External.

A build for BlueCore01b will not run on BlueCore2-External and vice versa.

2.2 HCI on BlueCore

Each of the HCI builds is issued with a release note, listing the build's features, known major deficiencies andmajor changes since the previous HCI build. This “HCI on BlueCore” document extends the release notes'information, acting more as a user guide than (an HCI) specification feature checklist. Where a release notedeals almost entirely with how well the build compares against the Bluetooth specification, this document refersto other CSR documents, PS Key configuration settings, etc. It also gives details on how the firmware implementssome HCI commands, notably those with manufacturer-specific elements.

This (issue of this) document describes the HCIStack1.1v12.x, HCIStack1.1v13.x, HCIStack1.1v14.x andHCIStack1.1v15.x builds. There is no guarantee that features described here will be part of future builds, thoughthe trend has been to add functionality, not to remove it

2.3 Programmable Interfaces

An HCI build of the firmware can be considered to present five programmable interfaces:

HCI: Communications between the host and the Bluetooth module, defined by section H1 of referenceddocument [BT]. This is the primary topic of this document.

LMP: Link Management Protocol. Communication between BT devices, defined by Part C of [BT]. This canonly interact with the Link Managers (LM) of remote Bluetooth devices, so it is difficult to characterise this asa programmable interface. However, the interactions with remote LMs configure the local firmware.

BCCMD: A CSR-proprietary command protocol for the Bluetooth module. This is described in a set ofdocuments, listed in each build’s document list. Some of its commands are mentioned in this document.

PS: The BlueCore device’s Persistent Store. This is primarily a configuration database. The firmware readsfrom the store when it boots.

VM: Virtual machine is provided in both HCI and RFCOMM firmware builds, but it is mainly used withRFCOMM builds. This allows a simple, design-specific application to run in a controlled environment. TheVM’s interface to the rest of the firmware is described in the BlueLab documentation.

The rest of this document largely follows the structure of the HCI specification.

ACL Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

3 ACL Connections

3.1 Number of Connections

The firmware supports a maximum of seven ACL (Asynchronous Connection-less) connections. This limit appliesregardless of whether the ACL connections are in Active, Park, Hold or Sniff mode.

The maximum number of slaves derives primarily from the availability of RAM (random access memory). Asubstantial block of RAM is used to hold each connection’s “state”: its addresses, modes, encryption data, bufferdescriptors, etc.

The firmware uses PS Key PSKEY_MAX_ACLS (0x000d) to limit the number of links that can be opensimultaneously; the PS Key’s default value is 7. If this is set higher than the available random access memory(RAM) can support, then the firmware will reboot the BlueCore device when it runs out of (pool) RAM. Forapplications that use extra RAM (e.g., for a VM application), it may make sense to reduce the value ofPSKEY_MAX_ACLS, thus protect the firmware.

This document is concerned with HCI firmware builds, where the default value of 7 is appropriate. For otherbuilds, notably RFCOMM builds (providing on-chip L2CAP, RFCOMM, etc.), the value should certainly be lower,as the higher stack layers consume substantial amounts of the pool RAM, which means that the BlueCore devicecan support fewer ACL connections.

The firmware builds have been tested with a master supporting seven ACLs and two HV3 SCO (SynchronousConnection-oriented) links, all carrying bi-directional data, but this gets very close to the limit of the availableRAM; there is very little spare RAM to support extra operations.

(It might be thought better to test with seven ACLs and three HV3 SCO links, but this configuration cannot bemaintained. The SCO links take all of the piconet's bandwidth, leaving no time to poll the slaves without SCOlinks. The configuration can be created, but then the idle links are not polled, so these links are disconnectedwhen their supervision timers fire.)

The hardware can address extra external RAM; this should allow it to support more slaves. However, this is notsupported by the current firmware.

BlueCore2 devices have more internal RAM than BlueCore01b. Future firmware builds for BlueCore2-Externalare expected to support extra connections.

3.2 Host-to-Host Controller Data Flow

The consequences of the firmware receiving an ACL packet with an invalid HCI connection handle depend on thehost transport in use:

§ When using the H4 host transport the erroneous packet is discarded and an HCI HARDWARE_ERRORevent with code FAULT_H4_RX_BAD_PDU (0x23) is sent to the host.

§ When using USB or BCSP the firmware reboots. The host transport will be reset. The host hasapparently violated HCI, so this drastic means of recovering seems reasonable.

See section 5.4, DISCONNECT, concerning "frozen" HCI handles.

3.3 Host Controller-to-Host Data Flow

The maximum size of data packets sent over HCI to the host is the lower of:

§ The Host_ACL_Data_Packet_Length value in the last HCI HOST_BUFFER_SIZE command issued bythe host

§ The value of the max_tx_payload_size field of PSKEY_HOSTIO_PROTOCOL_INFO6 (0x019a)

The default value for the latter limit is 512 bytes; it is strongly recommended that this should not be increased.

ACL Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

These two controls apply regardless of the host transport in use. However, ACL data is normally sent over HCI assoon as:

§ ACL data becomes available

§ Host transport has capacity

To try to avoid some common confusions:

§ This sizing is independent of the local READ_BUFFER_SIZE values; the READ_BUFFER_SIZEcommand limits the size of data messages sent to the BlueCore device only.

§ The sizes of ACL data blocks passed into a Bluetooth device have no direct relationship to the sizes ofACL data blocks passed to the peer’s host. The only Bluetooth HCI requirement is to maintain the“start of L2CAP” markers.

SCO Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

4 SCO Connections

4.1 Number of Connections

The maximum number of SCO connections is constrained by PSKEY_MAX_SCOS (0x000e). This defaults to3. It sometimes makes sense for embedded systems to use a lower value for this PS Key.

Note:

If the piconet is full of SCO traffic (one HV1, two HV2s or three HV3s), then there is no spare time to pollextra slaves, so slaves without a SCO link will be disconnected with a supervisor timeout.

4.2 Host Transports

The beta v9.x firmware builds supported a single SCO link and this was always routed over BlueCore01b’s pulsecode modulation (PCM) port. This went against the HCI specification as the SCO link’s creation was commandedover HCI, but the data did not flow over HCI/SCO. Also, the BlueCore01b PCM port hardware can carry only asingle SCO connection, so this limited BlueCore01b to a single SCO link.

In the beta v10.x builds the default behaviour was changed to obey the HCI specification. Up to three SCO linkscould be created and the SCO data flowed over HCI. This remains the case for builds since HCIStack1.1v12.x.

CSR only supports SCO over HCI over BlueCore Serial Protocol (BCSP). Code to support SCO over HCI forUniversal Serial Bus (USB) and H4 is in the firmware, but has not been thoroughly tested.

4.3 PSKEY_HOSTIO_MAP_SCO_PCM

The PS Key PSKEY_HOSTIO_MAP_SCO_PCM (0x01ab) can be configured to cause the firmware to behavelike beta v9.x: when this Boolean PS Key is set to TRUE, all attempts to open SCO connections try to route thedata path over the single PCM port. This implies the build can support only a single SCO link.

HCIStack1.1v15.x can carry multiple SCO streams over its PCM port. The clock settings inPSKEY_PCM_CONFIG32 (0x01b3) determine whether the PCM port is configured to carry more than one PCMchannel. However, the meaning of this PS Key is unchanged: if the PS Key is TRUE, it maps all attempts to openSCO streams to PCM port’s first channel (only the first attempt succeeds).

4.4 BCCMD MAP_SCO_PCM

PSKEY_HOSTIO_MAP_SCO_PCM provides a static mapping, forcing the use of the PCM port for all SCO links.An alternative approach is to use the BCCMD command MAP_SCO_PCM, described in referenced document[BCCMDS]. This command effectively says “route the next SCO connection over the PCM port”.

SCO Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

The command applies both to locally and remotely created SCO links. Figure 4.1 shows the normal sequence forrouting a locally created SCO link over the local chip’s PCM port:

HostHost

Controller

bccmd::Map_SCO_PCM(1)

hcicmd::Add_SCO_Connection(...)

bccmd::Map_SCO_PCM(1, OK)

hcievt::Command_Status(OK)

hcievt::Command_Complete(OK)

Record that next

SCO link will use

PCM Channel 1

SCO connection

attached to PCM

Channel 1

Figure 4.1: Locally Created SCO Link

The sequence for a remotely created SCO link is similar:

HostHost

Controller

bccmd::Map_SCO_PCM(1)

hcicmd::Accept_Connection_Request()

bccmd::Map_SCO_PCM(1, OK)Record that nextSCO link will usePCM Channel 1.

SCO connectionattached to PCM

Channel 1

hcievt::Connection_Request(SCO)

hcievt::Connection_Complete()

Figure 4.2: Remotely Created SCO Link

These sequences refer to “PCM Port 1”. It may seem pointless to have to specify the PCM port number onBlueCore01b, as it has only a single PCM port. However, BlueCore2 hardware supports extra PCM channels,and the bccmd::MAP_SCO_PCM() command has been shaped accordingly.

The extra capability of BlueCore2-External hardware is not usable with HCIStack1.1v14.x builds; only one PCMchannel can be used.

On HCIStack1.1v15.x builds, the MAP_SCO_PCM command selects one of four PCM channels through thePCM port.

The MAP_SCO_PCM BCCMD command allows SCO channels to run over the PCM port and over HCIsimultaneously.

If PSKEY_HOSTIO_MAP_SCO_PCM is set to TRUE, it nullifies this BCCMD command.

SCO Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

4.5 SCO Data Rate Compensation

Two significant issues affect the transfer of SCO traffic between the piconet and the host:

§ SCO data travels over the air at a nominal 8k samples/second. The same data stream flows over thehost interface, so it must also run at 8k samples/second. However, the clocks can be slightlymismatched, so the BlueCore firmware must handle the mismatch.

§ There can be gaps in the SCO traffic caused either by not receiving packets from air or by not receivingdata from the host. The BlueCore device must deal with the gaps.

The firmware combats these issues with three mechanisms:

§ Where data is streaming smoothly, but there is a slight mismatch between the air and host interfaceclocks, the firmware can silently add or drop individual samples. Where a sample is added, the lastknown good sample from the stream is repeated.

Samples are added/dropped at a maximum rate of one sample per SCO air packet.

It is considered acceptable to tamper with the stream's data because SCO streams are designed tocarry voice; the audible effect of using this simple mechanism is negligible.

§ Where there is a gap in the data received from air the firmware can fill it with repeated samples. The lastknown good sample is repeated throughout the block. This is used where an expected air packet is notreceived, or where a received packet is unacceptable, e.g., because it is corrupt.

§ When a SCO link is created, the BlueCore device's buffers can be half filled with samples correspondingto a short silence. This can prevent an irritating click when data starts to flow.

The use of these mechanisms is shown in tables 4.1 and 4.2:

SCO (from Air to Host)

Add/Drop Samples Dropped Air PacketCompensation

Pre-Fill Buffer

Host Interface

HCI v12.x HCI v13.xHCI v15.x



PCM Yes Yes Yes Yes Yes Yes

USB No Yes No Yes No Yes

BCSP No No No Yes No No

H4 No No No Yes No No

Table 4.1: SCO (from Air to Host)

PCM

The PCM interface runs at 8k samples/second. This is the same nominal rate as the piconet, but the clocks candrift relative to each other, so add/drop sample compensation must be used.

If the BlueCore device is providing the PCM port's clock (the default case), and if the local device is the piconetmaster, then there is no need to add/drop samples as both interfaces run from the same clock.

If an air packet is lost, the firmware must continue to feed the synchronous PCM sample stream to the host, so itmust fill the gap; it must generate a block of samples.

The PCM port is configured with PS Key PSKEY_PCM_CONFIG (0x01a9) on BlueCore01b and withPSKEY_PCM_CONFIG32 on BlueCore2-External.

SCO Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

USB

For SCO, the USB interface carries a fixed rate flow of fixed size packets. This gives it the same synchronouscharacteristic as the PCM interface. The interface's rate is fixed at a nominal 8k samples/second. Thus, it alsoneeds to handle lost air packets and add/drop sample compensation.

These mechanisms were not used in the HCIStack1.1v12.x builds, so their SCO/HCI/USB performance was poor.

BCSP and H4

These interfaces have no need for the add/drop sample compensation as the firmware decides the size andtiming of SCO data packets sent to the host. See section 4.8, SCO Data over HCI: Host Transport Bandwidth.

In the HCIStack1.1v12.x builds, if the firmware fails to receive an expected SCO air packet, then there is a gap inthe flow of data sent to the host. It is the host's responsibility to spot the gap and compensate for it.

The HCIStack1.1v13.x and later builds compensate for lost air packets. If there is a gap in the air traffic, acorresponding block of (repeat sample) data is sent to the host. Consequently, the host code no longer needs towatch for gaps in the sample flow; it receives (nominally) 8k samples/second.

SCO (from Host to Air)

Add/Drop Samples Dropped Host PacketCompensation

Pre-fill Buffer

Host Interface

HCI v12.x HCI v13.xHCI v15.x HCI v12.x HCI v13.x

HCI v15.x HCI v12.x HCI v13.xHCI v15.x

PCM Yes Yes No No Yes Yes

USB Yes Yes No No No Yes

BCSP Yes Yes No No No No

H4 Yes Yes No No No No

Table 4.2: SCO (from Host to Air)

All Host Interfaces

For all host interfaces, it is the host's responsibility to send 8k samples/second. If a SCO channel's to-air bufferruns dry, a NULL packet is sent to air. The firmware does not construct data to fill the gap.

PCM and USB

As with the from-air sample flow, the firmware must compensate for any clock mismatch between the piconet andthe PCM or USB.

BCSP and H4

The host is required to provide 8k samples/second, but the host's sample clock may drift relative to the piconet'stiming, thus sample add/drop compensation is provided for the two Universal Asynchronous Receiver Transmitter(UART) transports.

4.6 Loopback SCO Data Rate Compensation

When the firmware is put into local loopback mode, all SCO data sent from the host is returned to the host. Thereis no need for data rate compensation.

If the firmware is put into remote loopback mode, then the firmware presumes that the test connection will bemade from a remote device. This means no (SCO) data flows over the local device's HCI, thus there is no localneed for data rate compensation.

See section 5.49, WRITE_LOOPBACK_MODE.

SCO Connections


Imp

lemen

tation

of H

CI o

n B

lueC

ore

4.7 Transparent SCO Data Rate Compensation

There is no clear definition of transparent SCO. [BT] errata 1274 and 1275 describe transparent SCO as asynchronous data link, to which no voice coding is applied. Erratum 2113 (rejected) notes that transparent SCOdata should not be subjected to interpolation.

When commanded to use transparent SCO, the firmware attempts to provide an unreliable bi-directional bytepipe, which can carry up to 8k bytes/second.

Because the SCO channel is intrinsically unreliable, it seems reasonable for the firmware to drop data to handleany timing mismatch between the piconet and host transport, but it seems less reasonable for it to add data.Consequently, the only data rate compensation performed on a transparent SCO link is to discard a received airpacket if the receive ring buffer threatens to fill.

PCM and USB

Transparent SCO is effectively unusable with PCM or a USB host interface.

In both cases the firmware must transfer 8k bytes/second to the host, but SCO air packets are unreliable, sothere will inevitably be gaps in the data, and there is no general, reasonable technique that can handle the gaps.

The firmware will actually fill the gaps in the to-host stream with rubbish, as the receive ring buffer will wrap whenit empties.

A mismatch between the host transport and piconet clocks has the same consequence.

BCSP and H4

Transparent SCO can be used with UART host transports, as these can handle varying SCO data rates over HCI.

Note:

Although SCO nominally carries 8k bytes/second, the firmware's implementation of transparent SCO can beused at lower rates.

4.8 SCO Data over HCI: Host Transport Bandwidth

SCO voice data must be delivered in a regular and timely manner, so for all HCI transports (USB, H4 and BCSP)SCO data has (almost) the highest priority of data sent to the host. This is set by the “priority” field of the PS KeyPSKEY_HOSTIO_PROTOCOL_INFO7 (0x019b).

For USB, SCO is routed over an isochronous endpoint that always provides sufficient bandwidth, as defined in[BT].

For UART-based transports, H4 and BCSP, the system design must ensure the host transport has sufficientbandwidth to carry the SCO data packets, plus the extra needed for HCI commands/events and any ACL data. Acommon cause of user problems has been that opening a SCO channel apparently leads to losing control of theBluetooth module. The usual user report is that the connection-complete HCI event reaches the host after anexcessive delay. This is almost always because the host transport has suddenly filled with (high priority) SCOtraffic. The tardy HCI event only manages to slip through to the host when there is a momentary gap in the SCOdata.

In HCIStack1.1v11.x, SCO data was sent to the host over HCI as soon as it became available. This sometimestook more of the host transport’s bandwidth than was expected. For example, for an HV1 link the SCO databecame available 10 samples at a time. Where the voice coding used single byte samples this could almostdouble the raw UART bandwidth needed for BCSP.

In HCIStack1.1v12.x, PS Key PSKEY_HOSTIO_MIN_UART_HCI_SCO_SIZE (0x01ae) was added. This setsthe minimum number of SCO samples for each SCO data packet sent to the host, so it constrains consumption ofthe host transport’s bandwidth.

A consequence with this mechanism is that it can prevent the last few samples on a connection being sent to thehost. This is only likely to be of any interest when using transparent SCO.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5 HCI Commands

This section describes how some of the HCI commands have been implemented. The command order matchesthat in [BT].

5.1 (HCI: 4.5.1) INQUIRY

This causes the local device to enter Inquiry mode, in which it seeks other Bluetooth devices in radio range andreports them to the host.

The firmware’s LM includes a filter to reduce the number of repeat (external device) reports sent to the host, butthis is of finite size (currently eight Bluetooth addresses), thus duplicate addresses can reach the host.

Some users have commented that this is a violation of the HCI specification, but CSR can find no evidence ofthis. Indeed duplicate reports are effectively implied when the finite amount of memory in a module is consideredalongside the potentially very large number of external devices.

See section 5.2, PERIODIC_INQUIRY_MODE.

5.2 (HCI: 4.5.3) PERIODIC_INQUIRY_MODE

The implementation of PERIODIC_INQUIRY_MODE has a peculiarity that has caused problems for users. If themodule is commanded to perform an Inquiry at the same time as the module is actually inquirying [sic] becauseof a PERIODIC_INQUIRY_MODE setting, then the Inquiry command is refused with a “command disallowed”reason code.

The HCI specification is not clear on the required behaviour.

5.3 (HCI: 4.5.5) CREATE_CONNECTION

Number of Connections

An attempt to create more connections than are permitted by PSKEY_MAX_ACLS will be gracefully rejected.

For information on the supported number of ACL connections, see section 3.1, Number of Connections.

Packet_Type

It is almost always best to set the Packet_Type parameter to allow the use of all six ACL packet types(0xcc18). Two firmware mechanisms benefit from this:

§ CQDDR allows the peer to request the local device to use DM or DH packets, and to use particularlength packets. The more packet types the local device has to choose from, the better it can honour thepeer's requests.

§ The local device's LC includes a block of code that selects transmit packet types according to the link'srecent peer ACK/NAK history. While link conditions are good, this code block will tend to use capacious,multi-slot packets, but it will revert to shorter, more robust packet types when link conditions becomeworse. The wider the selection of packet types available, the better this can operate.

Some users force use of DH5 packets only, presuming this will give the highest bandwidth. This is almost alwaysa poor choice, as in poor radio conditions it will take many retransmissions to transfer each DH5.

Slave Packet_Type

When an ACL is freshly created, the slave presumes it can use all six ACL packet types. The slave's host maysubsequently refine this with a call to CHANGE_CONNECTION_PACKET_TYPE.

[BT] specification is not very clear on whether this is the correct behaviour. Other manufacturers' implementationsmay be based on different presumptions.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

PAGE_SCAN_MODE

Only the Mandatory PAGE_SCAN_MODE is supported.

5.4 (HCI: 4.5.6) DISCONNECT

Frozen HCI Handles

The [BT] HCI mechanism for destroying connections has a weakness: there is no way for the host controller(BlueCore device) to know that the host knows that a connection has been terminated.

For example, if a link’s supervisor timer triggers indicating that the firmware regards that a link has died, theBlueCore device sends an HCI DISCONNECTION_COMPLETE (connection timeout) event to its host. However,the BlueCore device has no way of knowing that the host has acted upon this message; thus as far as theBlueCore device is concerned, the host remains free to send it data or commands for the connection at any time.

Sending data to the BlueCore device on unknown HCI handles is very destructive. See section 3.2, Host-to-HostController Data Flow. Consequently, the BlueCore device firmware defends itself when a connection is takendown: it places the HCI handle into a “frozen” state for a period. In this state the firmware harmlessly discardsdata received on the handle.

While an HCI handle is in its frozen state, it holds a set of resources, notably the HCI handle, a block of RAM anda set of the BlueCore device’s memory management unit (MMU) buffers. Holding on to the HCI handle prevents itbeing reallocated to a fresh connection.

A frozen HCI handle takes resources, so there is a limit to the number of handles that can be in this statesimultaneously. Ultimately this limits the rate at which HCI connections can be created and destroyed.

The duration of the frozen period is set by PSKEY_HCI_HANDLE_FREEZE_PERIOD (0x0237); the default is15 seconds.

PSKEY_MAX_FROZEN_HCI_HANDLES (0x0238) limits the number of HCI handles that can be maintained inthe frozen state simultaneously (default 20). All attempts to create fresh HCI connections are refused while thereare this many frozen HCI handles. This mechanism applies to ACL and SCO handles.

Disconnection Constraints

It is not possible to disconnect a parked slave; the command is disallowed. The link should be restored to itsactive state and then disconnected.

Disconnecting a link that is in Hold or Sniff mode will cleanly disconnect on the side commanding thedisconnection, but the remote side’s host will probably see the link fail from a Supervisor Timeout. As above,restoring the link to its full active state avoids this problem.

5.5 (HCI: 4.5.8) ACCEPT_CONNECTION_REQUEST

See section 5.20, SWITCH_ROLE.

5.6 (HCI: 4.5.10) LINK_KEY_REQUEST_REPLY

See section 6.2, HCI COMMAND_COMPLETE event.

5.7 (HCI: 4.5.11) LINK_KEY_REQUEST_NEGATIVE_REPLY


5.8 (HCI: 4.5.12) PIN_CODE_REQUEST_REPLY


HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.9 (HCI: 4.5.13) PIN_CODE_REQUEST_NEGATIVE_REPLY


5.10 (HCI: 4.5.14) CHANGE_CONNECTION_PACKET_TYPE

See section 5.3, CREATE_CONNECTION.

Broadcast Handles

The firmware always sends broadcast data in DM1 packets . Broadcast is an intrinsically fragile data transfermechanism, so it was thought best to maximise the chances of delivering the data by using the most robustpacket type.

5.11 (HCI: 4.5.16) SET_CONNECTION_ENCRYPTION

The BlueCore device hardware supports encryption up to 128 bits. The actual strength of encryption used on alink is derived by negotiation with the peer Bluetooth device via LMP. The local device’s lower and upper limits ona link’s acceptable encryption strength are configured by PS Keys PSKEY_ENC_KEY_LMIN (0x00da) andPSKEY_ENC_KEY_LMAX (0x00db).

Once encryption has been enabled for a link, the effective encryption key length can be obtained via the BCCMDcommand CRYPT_KEY_LENGTH, described in [BCCMDS]. This information is not provided by the standard HCIcommand set.

The firmware builds from CSR’s web site are all limited to a maximum effective encryption key length of 56 bits.Setting PSKEY_ENC_KEY_LMAX above seven (bytes) for these builds has no useful effect.

Builds supporting 128-bit encryption can be obtained on request to CSR.

The HCIStack1.1v13.x and later builds provide the MAX_CRYPT_KEY_LENGTH BCCMD command. This allowsthe host to determine the maximum effective encryption key length supported by the build.

5.12 (HCI: 4.5.17) CHANGE_CONNECTION_LINK_KEY

If authentication of the new link key fails, the device needs to re-initialise bonding usingAUTHENTICATION_REQUESTED. An attempt to use CHANGE_CONNECTION_LINK_KEY after such a failurewill provoke a COMMAND_DISALLOWED event, as the device has no valid key.

5.13 (HCI: 4.5.18) MASTER_LINK_KEY

The Bluetooth specification requires encryption to be disabled for part of a MASTER_LINK_KEY operation.However, the specification does not require functionality under HCI to disable/enable encryption; this can bedone by code above HCI.

The firmware performs this disabling/enabling of encryption autonomously. This is a convenience for the host; notall manufacturers’ implementations of HCI behave in this manner.

If encryption is enabled when a MASTER_LINK_KEY command is received the firmware turns off encryption partway through performing the MASTER_LINK_KEY operation and re-enables encryption afterwards. Encryption isre-enabled regardless of whether the MASTER_LINK_KEY operation succeeded.

5.14 (HCI: 4.5.19) REMOTE_NAME_REQUEST

Only the Mandatory PAGE_SCAN_MODE is supported.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.15 (HCI: 4.5.22) READ_CLOCK_OFFSET

The BCCMD command set provides two commands related to this HCI command:

§ Command “BT_Clock” obtains the local device’s Bluetooth clock.

§ Command “Piconet_Instant” obtains the Bluetooth clock for an established piconet (the peer may be thepiconet’s master, so the peer will define the piconet’s Bluetooth clock).

The commands are described in [BCCMDS].

5.16 (HCI: 4.6.1) HOLD_MODE

Users should try to avoid Hold, Sniff and Park timings that are close to the link’s Supervisor Timeout value. As arule of thumb, keeping at least one second lower than of the Supervisor Timeout period avoids problems.

Attempts to use Hold, Sniff and Park intervals larger than the link Supervision Timeout minus six times the link’sTpoll period will be rejected by the firmware. The default Tpoll period is approximately 25ms.

It is recommended that the hold interval should be between 0x01 and 0xc80 (two seconds).

The firmware supports Hold and Sniff modes for an ACL connection where there are also one or more SCO linksadded to that connection.

5.17 (HCI: 4.6.2) SNIFF_MODE

See section 5.16, HOLD_MODE.

Using extreme Sniff mode values has been observed to cause problems. Testing in poor radio conditions showedthat settings of {0x5000, 0x5000, 1, 0}, i.e., one sniff attempt every 12.8 seconds, fails to allow data throughon 60% of sniff attempts. Settings {0x800, 0x800, 4, 1} are far more reliable.

It is recommended that the interval should be between 0x0a and 0xc80 (two seconds) and that theSniff_Attempt parameter should be less than half of the interval.

It is preferable to exit Sniff mode before performing operations involving complex LMP negotiations, such asauthentication and encryption. This is particularly important for HCI_SWITCH_ROLE, which will be rejected ifattempted inside a typical Sniff window.

Sniff mode parameters cannot be altered while in Sniff mode. The host should exit Sniff mode first, then requestSniff mode again with the new parameters.

It is not possible to enter Hold or Park mode directly from Sniff mode; exit Sniff mode first.

Four parameters to the HCI Sniff command specify numbers of baseband slots. These must be even values.

5.18 (HCI: 4.6.4) PARK_MODE

See sections 5.16, HOLD_MODE; 5.39, WRITE_LINK_SUPERVISION_TIMEOUT and 5.4, DISCONNECT.

Since many slaves may be parked on the same beacon, the master will not always honour the beaconparameters suggested in a park request from the slave.

The firmware supports only a single beacon train, so all parked devices must use the same beacon parameters.The beacon is configured from the first (accepted) PARK_MODE command.

It is recommended that the beacon interval should be between 0x0a and 0xc80 (two seconds).

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.19 (HCI: 4.6.6) QOS_SETUP

Builds before HCIStack1.1v15.x

The firmware does not usefully support Quality of Service (QoS) over HCI.

A QOS_SETUP HCI command will normally be accepted, but the corresponding QOS_SETUP_COMPLETEevent always specifies a “best effort” Service_Type, and all other parameters are set to zero or 0xffffffff .Effectively, all attempts to use QoS over HCI are gracefully rejected.

Builds from HCIStack1.1v15.x

A QOS_SETUP HCI command will normally be accepted, but the corresponding QOS_SETUP_COMPLETEevent always specifies a “best effort” Service_Type, and all other parameters are set to zero or 0xffffffff ,except the Latency parameter.

The command’s Latency parameter is translated from microseconds to piconet slots (rounded down) and usedto attempt to set the connection’s Tpoll value. The attempt can be rejected, e.g., if QOS_SETUP is called on aslave, then the change may be rejected by the master. The Tpoll value is also subjected to some limits, but if thecommand is successful, the Latency parameter in the QOS_SETUP_COMPLETE event reports theconnection’s new Tpoll value, converted back into microseconds.

Connections are given a Tpoll value of 40 slots when they are created.

Being able to adjust links’ Tpoll values allows reduction of the maximum latency for starting data transfers fromslave to master, but at the cost of extra polling (and thus power consumption) on the master.

Control of Tpoll values also allows adjustment of connections’ relative priorities, although the nature of the LC’sscheduler makes the control non-linear. The master’s LC is obliged by [BT] to (attempt to) contact each of itsslaves every Tpoll slots, to allow them to pass data back to the master, and to allow the master to confirm eachslave’s continued presence. However, when it has completed its polling duties, the master’s LC may fill any timeleft with normal ACL transfers, and these are scheduled round-robin. Hence, only relatively small Tpoll valuesmay have a significant effect on (un)balancing ACL loads.

The LC’s scheduling is far more involved than this simple illustration suggests; many other factors influence links’(relative) bandwidths.

5.20 (HCI: 4.6.8) SWITCH_ROLE

Encryption

The Bluetooth specification requires encryption to be disabled when performing a Master/Slave switch, howeverthe specification does not require code under HCI to disable/enable encryption; this can be done by code aboveHCI.

The firmware performs this disabling/enabling of encryption autonomously. This is a convenience for the host; notall manufacturers’ implementations of HCI behave in this manner.

If encryption is enabled when a SWITCH_ROLE command is received the firmware turns off encryption, performsthe SWITCH_ROLE operation, then re-enables encryption afterwards. Encryption is re-enabled regardless ofwhether the SWITCH_ROLE operation succeeded.

SCO

SWITCH_ROLE requests are refused if a SCO link is present.

Active

SWITCH_ROLE requests are refused if the ACL link is not in its active state.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

Failure

If a SWITCH_ROLE fails, then the link is left in place. This can also apply to a role switch at connection time,specified by SET_EVENT_FILTER or ACCEPT_CONNECTION_REQUEST.

5.21 (HCI: 4.7.2) RESET

Reset Stub

In builds before HCIStack1.1v12.x, the HCI RESET command rebooted the BlueCore device. This implied thatthe host transport was reset. This was a consequence of the way the firmware team understood an early versionof the Bluetooth specification (probably 0.7).

Rebooting the BlueCore device is incorrect behaviour. [BT] (v1.1) now makes it clear that the RESET commandmust re-initialise radio, LC, LM and HCI state, but leave the host transport in place. Builds sinceHCIStack1.1v12.x obey [BT].

Builds before HCIStack1.1v12.x used PSKEY_HCI_RESET_STUB (0x00f1) to cause the RESET command todo nothing. When this Boolean PS Key was set to TRUE, the HCI engine simply responded to the host that it hadperformed the RESET command, but it actually did nothing. This was surprisingly effective: all known host stacksuse the RESET command only at system initialisation and/or when the system gets into a mess. They do not usethe command as a quick way of clearing all existing connections. In particular, the stubbed RESET left the hosttransport state intact, which was what many users required. However, this workaround is no longer needed, sothe PS Key has been removed.

Boot-time NOP

When the firmware boots, it emits an HCI COMMAND_STATUS event with a No Operation (NOP) opcode as ameans of saying, “I’m awake.”

This event is also emitted by HCIStack1.1v12.x builds when they perform an HCI Reset. The event is not emittedby HCIStack1.1v13.x and later builds on HCI Reset.

Although [BT] makes it clear that this event can be emitted at any time, some host stacks are disturbed by it. Onevendor's early host stack fell over because of the event.

Setting the Boolean PS Key PSKEY_HCI_NOP_DISABLE (0x00f2) prevents the generation of the event at boottime.

HCI Command Flow Control


5.22 (HCI: 4.7.3) SET_EVENT_FILTER

See section 5.20, SWITCH_ROLE.

Number of Filters

The firmware supports a maximum of five event filters. The limit is set with PS KeyPSKEY_LM_MAX_EVENT_FILTERS (0x00f4).

Each active event filter consumes RAM, so if this PS Key’s value is significantly increased a correspondingsaving should be found elsewhere, e.g., by reducing PSKEY_MAX_ACLS.

Class of Device Filters and SCO Connections

In HCIStack1.1v13.x and later builds, if an ACL connection is made, then the slave asks to add a SCO channel tothe link, the master cannot use its event filters to accept or reject the request as it does not know the slave'sClass of Device. (The master's Class of Device is transferred to the slave in an FHS packet when the ACL link is

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

created, but the master does not learn the slave's Class of Device.) In this case, the master passes the SCOconnection request to its host.

If the devices perform a role switch, then both devices know the peer's Class of Device, so the filter can workproperly.

In HCIStack1.1v12.x builds a master always presumes the slave's Class of Device is zero and filters accordingly.

5.23 (HCI: 4.7.4) FLUSH

The firmware generates one FLUSH_OCCURRED event for each Flush command. This is generated onreception of the next HCI data packet with a start Packet_Boundary_Flag (0x02).

The single FLUSH_OCCURRED event is sent regardless of the number of L2CAP messages discarded (even ifthis is zero).

Only one flush transaction can be processed at a time:

§ If two Flush commands are issued, then the second will be rejected if it is received before the first'sFLUSH_OCCURRED event has been sent.

§ Similarly, if an automatic flush is started (WRITE_AUTOMATIC_FLUSH_TIMEOUT), then a Flushcommand may be rejected if it is received before the automatic flush's FLUSH_OCCURRED event hasbeen sent.

See sections 5.33, WRITE_AUTOMATIC_FLUSH_TIMEOUT command and 6.5, FLUSH_OCCURRED event.

5.24 (HCI: 4.7.7) CREATE_NEW_UNIT_KEY

See section 5.25, WRITE_STORED_LINK_KEY, for a description on how the local device’s Unit Key is stored.

The general advice from the Bluetooth security grandees is to avoid using Unit Keys. Where these fall into thewrong hands (e.g., stored in a stolen cell phone), it undermines Bluetooth security built upon them. The defaultbehaviour of this command reflects this advice.

This HCI command is controlled by PS Key PSKEY_LM_USE_UNIT_KEY (0x00f0). By default this PS Key isFALSE, in which case all attempts to use CREATE_NEW_UNIT_KEY are rejected with “command disallowed”.

If the PS Key is TRUE and if the local device has no stored Unit Key, then all attempts to useCREATE_NEW_UNIT_KEY are rejected with “command disallowed”.

If the PS Key is TRUE and if the local device already has a stored Unit Key, then a new Unit Key is generatedand written into the Persistent Store.

The PSKEY_LM_USE_UNIT_KEY also controls how the local device performs pairing. If the PS Key is FALSE,then the local device’s Combination Key is always used, else the local device’s Unit Key is always used.

If this requires that the local device needs to use a Unit Key but no Unit Key is held in the local device’sPersistent Store, then a fresh Unit Key is generated. However, this fresh Unit Key is not automatically written tothe Persistent Store. The value is passed to the host in a LINK_KEY_NOTIFICATION event, and the host candecide whether to store it using WRITE_STORED_LINK_KEY.

See the warning in section 5.27, CHANGE_LOCAL_NAME.

5.25 (HCI: 4.7.9) WRITE_STORED_LINK_KEY


COMMAND_COMPLETE Status

[BT] specifies that the command's COMMAND_COMPLETE event should carry the number of keys actuallywritten and a Status value, where 0x00 indicates success. However, it is not clear what the Status value

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

should be if an attempt is made to write several keys, but only some of these are written (e.g., because of spaceconstraints).

The firmware always returns 0x00 unless the command parameters are invalid. For example, if an attempt ismade to write one key and it is not written, then the event has both the Status and Num_Keys_Writtenfields set to 0x00.

Storage of Link Keys

The firmware supports a maximum of 16 stored linked keys. These are held in PS KeysPSKEY_LINK_KEY_BD_ADDR0 (0x00ca) through to PSKEY_LINK_KEY_BD_ADDR15 (0x00d9). The use ofthese 16 PS Keys is associated with PSKEY_FREE_KEY_PIGEON_HOLE (0x00c9). It rarely makes sense forthese PS Keys to be set using pstool.exe .

Unit Key

If this command stores a key associated with the local device’s Bluetooth address, then it is taken to be the localdevice’s Unit Key. If there is no such key stored, then the local device has no Unit Key.

5.26 (HCI: 4.7.10) DELETE_STORED_LINK_KEY


5.27 (HCI: 4.7.11) CHANGE_LOCAL_NAME

Storage

The local Bluetooth module’s name is held in PS Keys PSKEY_LOCAL_NAME0 (0x00dc) through toPSKEY_LOCAL_NAME17 (0x00ed) . The name is stored as a sequence of text fragments. This allows thefirmware to be more efficient in its use of RAM than if it stored the complete name in one block. The length of thename stored in these PS Keys is held in PS Key PSKEY_LOCAL_NAME_LENGTH (0x00ee).

The HCI CHANGE_LOCAL_NAME command writes to this set of PS Keys; there is normally no sense in writingto the PS Keys with pstool.exe .

Initial Value

The Persistent Store data remains intact through power cycling, so this means the module’s name survivespower cycling. Strictly this is a violation of the HCI specification, which gives a default value of "" (an emptystring) for the device’s name. CSR does not currently intend to alter this behaviour.

If no name has been written to the PS Keys the firmware defaults to CSR-bc01b or CSR-bc2 as appropriate.

HCI 12.1 Warning

Build HCIStack1.1v12.1 and all previous builds have a serious bug whereby BlueCore01b can lock up if bulk(ACL/SCO) data is flowing through the chip while changing PS Key values. This affects theCHANGE_LOCAL_NAME, CREATE_NEW_UNIT_KEY, WRITE_STORED_LINK_KEY andDELETE_STORED_LINK_KEY HCI commands. This problem is fixed in HCIStack1.1v12.3 and later builds.

5.28 (HCI: 4.7.18) WRITE_SCAN_ENABLE

Slave Page and Inquiry

A peculiarity of the firmware is that Bluetooth slaves do not perform Page-Scan, Inquiry-Scan, Page or Inquiry.

The only reason for performing Page-Scan is to become the slave of another device. If a device is a slave of twomasters, then this implies a scatternet, and the firmware does not support scatternets. The same reasonunderlies slaves not supporting Page.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

The reasoning behind slaves not supporting Inquiry-Scan is less solid. An Inquiry-scanning device merely has torespond to an inquiry after a seemly delay, so there is no awkward connection state to handle. However, themost common (user-requested) reason for a slave to support Inquiry-Scan is for a "Bluetooth Neighbourhood"application. This generally performs an Inquiry to list local devices, then makes a connection to each device inturn to quiz its Service Discovery Protocol (SDP) database. Access to SDP implies an ACL, so the quizzeddevice must become part of a scatternet, and the firmware does not support scatternets. The same reasoningunderlies slaves not supporting Inquiry.

Scanning and Bandwidth

The firmware gives higher priority to Page-Scan and Inquiry-Scan than to bulk ACL transfers on the master. Thismeans that if the master has scanning enabled after creating an ACL (e.g., after a connection and role switch),then the scanning will reduce the radio bandwidth available for ACL traffic.

If the master uses continuous scanning, sufficient to consume all of the radio's bandwidth, this suggests no ACLtraffic will flow. However, the firmware gives higher priority to piconet device polling (Tpoll) activity than toscanning, and ACL data can flow when polling is performed. Consequently, a trickle of ACL data can flow oneach link. This is a surprisingly common cause of "very low ACL bandwidth" queries to CSR.

5.29 (HCI: 4.7.24) WRITE_AUTHENTICATION_ENABLEIf authentication fails as a connection is being established, the link is automatically disconnected.

The HCI specification provides no convenient means of telling the host that an attempt to perform authenticationhas succeeded or failed. (The firmware could send an AUTHENTICATION_COMPLETE event, but it would referto an HCI ACL connection handle that the host would not yet know.)

This command is used to force authentication of fresh connections, so disconnecting seems a reasonable actionon authentication failure.

5.30 (HCI: 4.7.26) WRITE_ENCRYPTION_MODE

See section 5.11, SET_CONNECTION_ENCRYPTION.

If an attempt to turn on encryption fails as a connection is established, then the link is left in place. See section5.29, WRITE_AUTHENTICATION_ENABLE.

The hosts are told whether or not the link has encryption enabled in their CONNECTION_COMPLETE events, sothe hosts can decide whether to maintain the link.

5.31 (HCI: 4.7.28) WRITE_CLASS_OF_DEVICE

There is no default value specified by [BT].

When the firmware boots the device’s Class_of_Device value is written to a location in RAM from thePSKEY_CLASSOFDEVICE (0x0003). This PS Key has a default value of zero.

The WRITE_CLASS_OF_DEVICE command overwrites the RAM location, changing the device’sCLASS_OF_DEVICE value. However, the HCI command does not alter the value stored under the PS Key.

5.32 (HCI: 4.7.30) WRITE_VOICE_SETTING

The command supports µ-law, A-law and linear codings, as described in referenced document [HCI].

Transparent SCO

[BT] erratum 1275 proposes two changes: addition of support for unsigned sample values and addition of supportfor transparent SCO. The firmware supports “transparent SCO” as described by the erratum, but it does notsupport unsigned sample values .

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

The erratum allocates a Voice_Setting bit pattern that is “Reserved” in [BT] to enable transparent SCO:

XXXXXXXX11 [Reserved] -----> Air Coding Format: none (transparent).

For transparent SCO the firmware provides an unreliable, bi-directional byte stream that can run at up to8k bytes/second.

Lower data rates can be used, but note that each SCO air packet type carries a fixed number of bytes, so thedata transfer is performed in correspondingly sized chunks.

See the description of SCO connections in section 4, especially section 4.8, SCO Data over HCI: Host TransportBandwidth.

16-bit Samples

The specification of the HCI command appears to allow 16-bit A-law and µ-law coded data. This does not workwith the firmware. A-law and µ-law are almost always used with 8-bit values.

5.33 (HCI: 4.7.31) WRITE_AUTOMATIC_FLUSH_TIMEOUT

When an automatic flush is triggered, the FLUSH_OCCURRED event is sent when the firmware processes thestart of the next L2CAP packet.

See sections 5.23, FLUSH command and 6.5, FLUSH_OCCURRED event.

5.34 (HCI: 4.7.34) WRITE_NUM_BROADCAST_RETRANSMISSIONS

The firmware interprets this HCI command pedantically: the default setting of 0x01 causes one retransmission.This is equivalent to a (baseband specification) number of broadcasts (NBC) of 2.

Real applications using broadcast tend to run with an NBC of about 5.

5.35 (HCI: 4.7.37) READ_TRANSMIT_POWER_LEVEL

When used to obtain a link’s maximum transmit power level, this command returns the module’s maximumtransmit power. As such, this acts as a means of determining which Bluetooth transmit power class is being used.(The command’s wording is rather vague; it could be taken to mean the maximum power level used so far on thelink.)

When used to obtain a current transmit power level, this command returns the dBm value for the current elementof the Bluetooth module’s transmit power table for the link. The module’s transmit power table is held inPSKEY_LC_POWER_TABLE (0x001e) .

Every Bluetooth module design must have a custom power table. (This point continues to cause problems, soCSR repeats it whenever an opportunity arises.) The PS Key’s default value is suitable for a current Casiradesign only.

5.36 (HCI: 4.7.39) WRITE_SCO_FLOW_CONTROL_ENABLE

See section 5.38, for SET_HOST_CONTROLLER_TO_HOST_FLOW_CONTROL.

5.37 (HCI: 4.7.42) HOST_NUMBER_OF_COMPLETED_PACKETS


5.38 (HCI: 4.7.40) SET_HOST_CONTROLLER_TO_HOST_FLOW_CONTROL

The firmware provides no support for flow control on SCO links: no Host-to-Host Controller flow control and noHost Controller-to-Host flow control.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

This feature is normally considered to be nonsense: SCO data must be delivered in a regular and timely fashion,so anything that hinders the steady flow of samples impairs audio quality. SCO normally needs to be transferredas a stream of regular, unreliable samples/packets.

This is reflected in the designs of the BCSP and USB transports: BCSP uses an unreliable datagram channel(unrel/7) and USB uses an isochronous endpoint. Thus, SCO sample packets can be silently lost, and thereforethis HCI command’s token-based flow control mechanism can leak tokens, slowly strangling the transport’sbandwidth.

5.39 (HCI: 4.7.44) WRITE_LINK_SUPERVISION_TIMEOUT

Running without a Supervision Timer

When a link’s Supervision Timeout triggers, the BlueCore device firmware frees its resources (RAM, AM_ADDR,SCO channels, etc.). Some of the resources are liberated only after a delay, but eventually they all becomeavailable for reuse.

If a link is run without a Supervision Timer (timeout value zero), then the firmware has no means of detecting thatthe link has failed, so its resources are not freed when the link becomes unworkable (e.g., out-of-range or a peerdevice is switched off). This leaks resources, slowly reducing the local device’s ability to perform Bluetoothoperations.

It is normally very unwise to turn off links’ Supervision Timers.

Autonomous Unpark/Park

If a device is left in its parked state for a prolonged period, it will normally trigger its Supervision Timer and thelink will be lost. Maintaining the link requires the device to be unparked and reparked regularly. This requirementis implicit in [BT], but the specification does not require it to be performed by code under HCI.

The firmware autonomously unparks/reparks devices regularly to maintain their link Supervision Timers. Neitherhost is aware of this: no HCI events are emitted from the master or slave. This is a convenience for the host; notall manufacturers’ implementations of HCI behave in this manner.

Because of the autonomous Unpark/Park mechanism, it is recommended that the park interval be no more than athird of the link’s Supervision Timeout.

5.40 (HCI: 4.7.45) READ_NUMBER_OF_SUPPORTED_IAC

In HCIStack1.1v12.x, this command always returns 0x01. This is allowed by the HCI specification and itaccurately describes the ability of the BlueCore device hardware.

The value 0x01 sometimes raises questions of whether this is adequate to support the Generic Access Profile(GAP), as GAP requires the ability to scan for two access codes. GAP notes that scanning for two codes may beachieved by sequential scanning, but it does not say this must be done below HCI; it can be done by theapplication.

In HCIStack1.1v13.x and subsequent builds , this command always returns 0x02. Two access codes arescanned for sequentially.

5.41 (HCI: 4.7.51) WRITE_PAGE_SCAN_MODE

Only the (default) Mandatory Page Scan Mode is accepted. The firmware does not support the Optional PageScan Modes.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.42 (HCI: 4.8.1) READ_LOCAL_VERSION_INFORMATION

This returns the following information:

HCI Version: 0x01 (Bluetooth HCI specification 1.1)

HCI Revision: BuildID

LMP Version: 0x01 (Bluetooth LMP specification 1.1)

Manufacturer_Name: 0x0a (Cambridge Silicon Radio)

LMP_Subversion: BuildID

Each distributed firmware build is given a unique identifier (its BuildID). This value is reported in theHCI_Revision and LMP_Subversion fields. (It could be that the LMP_Subversion field is supposed togive the version of the Bluetooth module’s silicon, but [BT] is rather vague on this point.)

The value is also available over USB in the bcdDevice field (release number) of the Standard DeviceDescriptor (table 9.7 in referenced document [USB]).

The value is also accessible via the “BuildID” BCCMD command, described in [BCCMDS].

Table 5.1 shows some BuildIDs for HCIStack1.1v12.x, HCIStack1.1v13.x and HCIStack1.1v14.x builds:

BuildID (hex) BuildID (decimal) Build Name

0x0077 119 HCIStack1.1v12.1

0x0086 134 HCIStack1.1v12.3

0x00bc 188 HCIStack1.1v12.7

0x0135 309 HCIStack1.1v13.10 (56-bit encryption)




Table 5.1: BuildIDs for HCIStack1.1v12.x, HCIStack1.1v13.x and HCIStack1.1v14.x

If a BuildID has the four bits 0x0f00 set to ones, then the build has not been labelled. These builds areintended for use within CSR only.

5.43 (HCI: 4.8.2) READ_LOCAL_SUPPORTED_FEATURES

Local Features Storage

This command returns the value of PS Key PSKEY_LOCAL_SUPPORTED_FEATURES (0x00ef). ThePS Key’s value is also used by the LMP_features_res and LMP_features_req messages.

The PS Key’s default value gives all of the features that the build’s LM supports. In HCIStack1.1v12.x builds thisdoes not include (optional) “Paging Scheme” support. Setting this bit to 1 in the PS Key will not magically createthe missing functionality.

From HCIStack1.1v13.x builds, support for the “Paging Scheme” is declared (though the support is trivial).

The PS Key’s three “flow” bits should always be zero.

Configuring the LM

This PS Key’s value configures the local LM. For example, if an application requires that the local LM should notsupport LMP power control, then the corresponding bit can be cleared in the PS Key’s value, and the LM will notparticipate in LMP power control from the next reboot.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.44 (HCI: 4.8.3) READ_BUFFER_SIZE

Returned Values

The four main values returned by the READ_BUFFER_SIZE command are taken from PS Keys:

PS Key Read_Buffer_Size Parameter Default

PSKEY_H_HC_FC_MAX_ACL_PKT_LEN HC_ACL_Data_Packet_Length 192PSKEY_H_HC_FC_MAX_ACL_PKTS HC_Total_Num_ACL_Data_Packets 8PSKEY_H_HC_FC_MAX_SCO_PKT_LEN HC_SCO_Data_Packet_Length 64PSKEY_H_HC_FC_MAX_SCO_PKTS HC_Total_Num_SCO_Data_Packets 8

Table 5.2: READ_BUFFER_SIZE Command Returned Values

Thus, for ACL, the BlueCore device normally presents (8 x 192) byte buffers.

It is possible to alter these values, so long as the product does not exceed (8 x 192). For example, it may help anapplication if it has (4 x 384) byte buffers. However, increasing the PS Keys’ values such that the productexceeds (8 x 192) will not miraculously create extra RAM. The firmware will reboot when it runs out of memory.

The same type of adjustment can be made for SCO buffers, indeed it often makes more sense to tune SCOsystem parameters to maintain a steady flow of data. The default of (8 x 64) byte buffers can be refactored as(12 x 48) bytes, etc. However, the maximum value for PSKEY_H_HC_FC_MAX_SCO_PKT_LEN (0x0012)is 128.

Setting PSKEY_H_HC_FC_MAX_ACL_PKTS or PSKEY_H_HC_FC_MAX_SCO_PKTS (0x0014)above 14achieves nothing: these PS Keys' values are silently limited to 14 in the firmware.

Finally, it is possible to take buffer storage allocated to SCO and add it to that used for ACL, up to an upper limitof 1919 bytes. For example, if it is known that an application will never use SCO, then its (8 x 64) bytes can beadded to the ACL buffers, e.g., as (14 x 136). (This wastes 144 of the SCO bytes.) In this example, it would makesense to set PSKEY_MAX_SCOS to zero.

The 1919 limit can be achieved where the value of PSKEY_H_HC_FC_MAX_ACL_PKT_LEN is 128. The upperlimit is actually the lower of the following:

1919 bytes

and

(2047 - PSKEY_H_HC_FC_MAX_ACL_PKT_LEN) bytes

so, if PSKEY_H_HC_FC_MAX_ACL_PKT_LEN is 192, the upper limit is 1855 bytes.

Exceeding the Limits

If the firmware detects that the host has exceeded the constraints of HC_Total_Num_ACL_Data_Packets orHC_Total_Num_SCO_Data_Packets, then it forces the BlueCore device to reset.

The manner in which the firmware behaves when it detects the host has exceeded the constraints ofHC_ACL_Data_Packet_Length or HC_SCO_Data_Packet_Length depends on the host transport:

§ When using the H4 host transport, an oversized packet is discarded and an HCI HARDWARE_ERRORevent with code 0xfe is sent to the host, i.e. the error is treated as an H4 synchronisation loss. Thehost will normally be expected to issue an HCI Reset command to re-initialise the BlueCore devicefirmware.

§ When using a USB or BCSP host transport the occasional overlong packet will be tolerated. However, ifthe ACL channel's underlying MMU buffer is filled, then the firmware will reset.

This sub-section should be irrelevant; if the host exceeds the values returned by READ_BUFFER_SIZE, then ithas violated HCI.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

5.45 (HCI: 4.8.4) READ_COUNTRY_CODE

The local device’s Bluetooth Country Code is taken from PS Key PSKEY_COUNTRYCODE (0x0002).

Although the firmware is believed to work with values other than 0x00 (“North America and Europe”), CSR nolonger tests this. In particular, the Protocol Implementation Conformance Statement (PICS) documents (used tosupport qualification) state that CSR supports only 0x00.

5.46 (HCI: 4.8.5) READ_BD_ADDR

The local device’s Bluetooth Address is taken from PS Key PSKEY_BDADDR (0x0001).

Each Bluetooth module needs a unique Bluetooth address; the module manufacturer writes this into this PS Key.

If the Read_BD_ADDR command returns the PS Key's default ("ROM") value then this strongly suggests thePS Key has not been configured.

§ On HCIStack1.1v12.x builds the default address is {0x000000, 0x5b, 0x0002}.

§ On HCIStack1.1v13.x and later builds the default address is {0x00a5a5, 0x5b, 0x0002}.

5.47 (HCI: 4.9.3) GET_LINK_QUALITY

This command obtains a value in the range 0 to 0xff, describing the quality of an ACL connection. The value’smeaning is manufacturer-specific.

The value is derived from an averaged bit error rate (BER) measurement, updated as packets are received. TheBER value is derived from parts of radio packets that support forward error correction (FEC):

§ All packets’ headers

§ Payloads of DM1, DM3, DM5, HV1 and HV2 packets

§ Data parts of DV packets

The technique used to derive BER values is not precise. It is intended only to give an indication of link qualityrather than act as a precise, calibrated instrument.

Links’ BER values are used internally to adapt to changes in link quality, notably to support Channel QualityDriven Data Rate (CQDDR).

The HCI command’s values are as follows.

§ Between 0xff and 0xd7, each bit distance represents 0.0025% BER. Thus:

Value BER

0xff 0.0%

0xfe 0.0025%

0xfd 0.0050%

0xfc 0.0075%

etc., until …

0xd7 0.1%

Table 5.3: BER Values to 0.1%

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

§ Between 0xd6 and 0x5a each bit distance represents 0.08% BER. Thus:

Value BER

0xd7 0.1%

0xd6 0.18%

0xd5 0.26%

etc.

Table 5.4: BER Values Over 0.1%

§ Between 0x59 and 0x00 each bit distance represents 0.64% BER.

As a rule of thumb, a link with a BER between 0.0% and 0.1% is workable. Trying to run a link with a BER above1% will give poor results.

This mechanism has been in firmware builds since beta v9.

5.48 (HCI: 4.9.4) READ_RSSI

A common user hope is to use this command’s return values as the basis of a general-purpose signal strengthmeter. Unfortunately, the command (as specified by [BT]), is almost useless for this role.

While a link’s received signal strength is within the Golden Receive Power Range, the command returns an RSSIvalue of zero. The Golden Receive Power Range is normally around 20dBm wide, crudely equating to a physicalrange factor of ten. (For example, between 1m and 10m, the RSSI value could be zero.)

The RSSI value will only go positive or negative when the received signal slips outside the Golden Range. Wheredynamic power control is available, the firmware’s LM will emit LMP_incr_power_req or LMP_decr_power_reqmessages to the Bluetooth peer to try to bring the received signal strength back into the Golden Range.

[BT] requires only that the function returns a negative value when the RSSI is below the Golden Range, zerowithin it, and a positive value when the RSSI is above the Golden Range.

§ When the RSSI is above the Golden Range, the firmware returns a positive number. The value is anapproximation of the dB between the top of the Golden Range and the RSSI. The value is very crude: itcan be ±5dB from the real value. There is no guarantee that a constant RSSI will give a constant returnvalue, thus there is no guarantee that the mapping from RSSI to the returned value will be monotonic.

§ When the RSSI is within the Golden Range, the firmware returns zero.

§ When the RSSI is below the Golden Range, the firmware returns a negative number. The value is anapproximation of the dB between the RSSI and the bottom of the Golden Range. The value is evenmore crude than for positive values: it can be more than ±5dB from the real value. There is no guaranteethat a constant RSSI will give a constant return value, thus there is no guarantee that the mapping fromRSSI to the returned value will be monotonic, and the value clips at a minimum of approximately –10dB.

The firmware, therefore, supports the bare minimum required by [BT]. This is not useful for a generalpower-meter.

5.49 (HCI: 4.10.2) WRITE_LOOPBACK_MODE

Local Loopback

When the device is put into local loopback mode, the three test SCO links flow over HCI; the PS KeyPSKEY_MAP_SCO_PCM and BCCMD command MAP_SCO_PCM are ignored.

HCI Commands


Imp

lemen

tation

of H

CI o

n B

lueC

ore

Remote Loopback

Figure 5.1 outlines the only way in which remote loopback is supported:

HCI Device A

Disconnect

Create_Connection

HCI Device B

boot or Reset

Write_Loopback_Mode (remote)

Write_Scan_Enable (Page-Scan)

Write_Loopback_Mode (off)

ACL data

Figure 5.1: Remote Loopback

Device B is put into remote loopback mode and then into Page-Scan mode. Device A then connects to Device B,sends ACL data, then disconnects. (Device A may optionally add SCO links to the test ACL link and pass SCOdata.)

The firmware rejects a request to enter remote loopback mode if the local device has any existing ACLconnection. (This does not violate [BT], but it probably is not what the HCI authors intended.)

If the local device is in remote loopback mode, then any local attempt to connect to a remote device fails.

Slow Host Transport

A tiresome characteristic of the firmware's support for this command is that remote loopback mode can lock up alink if the testing host’s connection to the Bluetooth module has a low bandwidth relative to the Bluetooth link.This problem occurs because the two devices assert flow control signals to each other, then fail to de-assertthem. The problem occurs readily when using BCSP at 115k2 baud, but has never been seen with a USB hosttransport.

HCI Events


Imp

lemen

tation

of H

CI o

n B

lueC

ore

6 HCI Events

6.1 (HCI: 5.2.13) QOS_SETUP_COMPLETE

See section 5.19, QOS_SETUP COMMAND.

6.2 (HCI: 5.2.14) COMMAND_COMPLETE

The flow of HCI commands from the host is controlled by the Num_HCI_Command_Packets (NHCP) parameterin the COMMAND_STATUS and COMMAND_COMPLETE events. However, strict adherence to this flow controlmechanism can lead to uncomfortable delays or to HCI deadlock, not helped by the fact that the maximum valueof Num_HCI_Command_Packets is one.

The following commands are allowed to violate NHCP flow control:

§ LINK_KEY_REQUEST_REPLY

§ LINK_KEY_REQUEST_NEGATIVE_REPLY

§ PIN_CODE_REQUEST_REPLY

§ PIN_CODE_REQUEST_NEGATIVE_REPLY

§ RESET

§ HOST_NUMBER_OF_COMPLETED_PACKETS

§ HCI manufacturer-specific extension commands. See [HCIEXTN].

These commands’ natures provide their own flow control. For example, the link key commands should only beused in response to a LINK_KEY_REQUEST event.

6.3 (HCI: 5.2.15) COMMAND_STATUS

See section 5.21 on the RESET command and section 6.2 on the HCI COMMAND_COMPLETE event.

6.4 (HCI: 5.2.16) HARDWARE_ERROR

Each Bluetooth module manufacture defines a set of Hardware_Code values for the HARDWARE_ERRORevent.

CSR’s list of Hardware_Codes is identical to the “fault” values given in referenced document [HQCMDS].

HCIStack1.1v12.x Builds

When a fault condition is detected, it is recorded in a tiny database within the firmware. The database collectsinformation for two seconds, then two messages are emitted to the host:

§ A “fault report”, described in CSR document [HQCMDS]. This can be sent as a manufacturer-specificHCI Extension Event. The report gives the fault code (e.g., “pool memory supply low”), the number ofoccurrences in the two-second period and the (firmware) time of the first occurrence.

§ An HCI HARDWARE_ERROR event, carrying the same fault code as for the “fault report” message.

This database mechanism prevents a flurry of identical error messages being sent to the host, possibly at a timewhen resources are low. However, the delay also means that the error messages are emitted two seconds late,and this sometimes causes confusion.

Some systems are configured so that the host does not receive fault reports (the first report above) by clearingthe Boolean PS Key PSKEY_HQ_ACTIVE (0x01fc).

HCI Events


Imp

lemen

tation

of H

CI o

n B

lueC

ore

HCIStack1.1v13.x and Later Builds

The behaviour of HCIStack1.1v13.x and later builds is identical to that of HCIStack1.1v12.x builds, except thatthe HARDWARE_ERROR event is emitted as soon as the fault condition is first detected.

6.5 (HCI: 5.2.17) FLUSH OCCURRED

The firmware generates FLUSH_OCCURRED events at the start of the next L2CAP packet following the end ofthe flushed data.

If the firmware internally generates a large number of FLUSH_OCCURRED events, and these threaten to floodthe (large) buffer used to pass events to the host, then the excess events are silently discarded to avoiddeadlock.

See section 5.33, WRITE_AUTOMATIC_FLUSH_TIMEOUT command and section 5.23, FLUSH command.

Manufacturer-Specific HCI Extensions


Imp

lemen

tation

of H

CI o

n B

lueC

ore

7 Manufacturer-Specific HCI Extensions

Each Bluetooth module manufacturer is allowed to add extra (debug) commands and events to itsimplementation of HCI using “Manufacturer-Specific HCI Extensions”.

CSR’s use of Manufacturer-Specific HCI Extensions is described in referenced document [HCIEXTN]. The list ofextra commands is given in referenced documents [BCCMDS], [BCCMDPS], [BCCMDTEST] and[BCCMDRADIOTEST]. Extra events are described in referenced documents [HQCMDS] and[HQCMDRADIOTEST].

Emission of HCI Events


Imp

lemen

tation

of H

CI o

n B

lueC

ore

8 Emission of HCI Events

This section outlines the circumstances under which HCI events are emitted.

Key Meaning

LH Can be emitted locally when servicing a local host’s HCI command

RH Can be emitted locally when servicing a remote host’s HCI command

A Can be emitted locally at any time

HCI Event LH RH A Comments

INQUIRY_COMPLETE Yes No No

INQUIRY_RESULT Yes No No

CONNECTION_COMPLETE Yes Yes No

CONNECTION_REQUEST No Yes No Emitted when a peer requests a connectionand local event filters are not set.

DISCONNECTION_COMPLETE Yes Yes Yes

Provoked by a local or remote peer HCIDISCONNECT_REQUEST command, a linksupervision timeout or a master link keyauthentication failure.

AUTHENTICATION_COMPLETE Yes No No

REMOTE_NAME_REQUEST_COMPLETE Yes No No

ENCRYPTION_CHANGE Yes Yes NoCan also be seen when a broadcastencryption key size negotiation is takingplace.

CHANGE_CONNECTION_LINK_KEY_COMPLETE Yes No No

MASTER_LINK_KEY_COMPLETE Yes Yes No

READ_REMOTE_SUPPORTED_FEATURES_COMPLETE Yes No No

READ_REMOTE_VERSION_INFORMATION_COMPLETE Yes No No

QOS SETUP_COMPLETE Yes Yes No

COMMAND_COMPLETE Yes No No

COMMAND_STATUS Yes No No

HARDWARE_ERROR No No Yes Error codes described in [HQCMDS].

FLUSH_OCCURRED Yes No YesProvoked by the HCI Flush andWRITE_AUTOMATIC_FLUSH_TIMEOUTcommands.

ROLE_CHANGE Yes Yes No

Can be emitted before the HCICONNECTION_COMPLETE event if aSWITCH_ROLE is requested by the slavewhen handling an HCIACCEPT_CONNECTION_REQUESTcommand.

NUMBER_OF_COMPLETED_PACKETS No No Yes Emitted when the peer accepts ACL data.

MODE_CHANGE Yes Yes Yes

Emitted on transition between Active, Hold,Sniff and Park modes. Can also be emittedfrom failing to park during an autonomousUnpark/Park sequence.

Emission of HCI Events


Imp

lemen

tation

of H

CI o

n B

lueC

ore

HCI Event LH RH A Comments

RETURN_LINK_KEYS Yes No No

PIN_CODE_REQUEST Yes Yes No

LINK_KEY_REQUEST Yes Yes No

LINK_KEY_NOTIFICATION Yes Yes No

Emitted either because pairing hascompleted or because aCHANGE_CONNECTION_LINK_KEYcommand has completed.

LOOPBACK_COMMAND Yes No No

DATA_BUFFER_OVERFLOW No No No Currently not used.

MAX_SLOTS_CHANGE Yes Yes YesEmitted on connection establishment. Canalso be emitted when a SCO connection isadded or removed.

READ_CLOCK_OFFSET_COMPLETE Yes No No

CONNECTION_PACKET_TYPE_CHANGED Yes No No

QOS_VIOLATION No No No Currently not used.

PAGE_SCAN_MODE_CHANGE No No No Currently not used.

PAGE_SCAN_REPETITION_MODE_CHANGE Yes Yes No

Can be emitted after connection creation ifboth devices say they support “pagingscheme” in their supported features. In thiscase, the slave always emits the event andthe master emits the event if it had paged theslave with the wrong page scan repetitionmode. Can also be emitted after aSWITCH_ROLE.

Table 8.1: Emission of HCI Events

Document References


Imp

lemen

tation

of H

CI o

n B

lueC

ore

9 Document References

Document ID Document Title, Reference

[BCCMD] BlueCore Command Protocol; CSR document AN068

[BCCMDPS] BCCMD Protocol Persistent Store Commands; CSR document AN072

[BCCMDS] Basic BCCMD Command Set; CSR document AN069

[BCCMDTEST] BCCMD Test Command Set; CSR document AN090

[BCCMDRADIOTEST] BCCMD Radio Test Command Set; CSR document bc01-sp-045Pa

[BT] Specification of the Bluetooth System, Volume 1, Core, v1.1, 22 February 2001

[HCIEXTN] HCI Manufacturer-Specific Extensions; described in CSR document AN067

[HQCMDS] HQ Protocol Basic Command Set; CSR document AN091

[HQCMDRADIOTEST] HQ Protocol Radio Test Command Set; CSR document bc01-sp-048Pa

[USB] USB Specification 1.1, 23 September 1998

Acronyms and Definitions


Imp

lemen

tation

of H

CI o

n B

lueC

ore

Acronyms and Definitions

BlueCore™Group term for CSR’s range of Bluetooth chips;Currently BlueCore01b and BlueCore2-External

Bluetooth™ Set of technologies providing audio and data transfer over short-range radio connections

BlueLab™ CSR’s software development kit for applications running in BlueCore’s VM

ACL Asynchronous Connection-Less

ACK ACKnowledge

BCCMD BlueCore Command Protocol, described in [BCCMD]

BCSP BlueCore Serial Protocol; described in [BCSP]

BER Bit Error Rate

CQDDR Channel Quality Driven Data Rate; described in [BT]

CSR Cambridge Silicon Radio

FEC Forward Error Correction

GAP Generic Access Profile; defined in the Bluetooth specifications

H4 UART-based HCI transport; described in section H4 of v1.0b of [BT]

HCI Host Controller Interface; part of [BT]

L2CAP Logical Link Control and Adaptation Protocol; part of [BT]

LC Link Controller; software/hardware component of the BlueCore device

LM Link Manager; software component of BlueCore firmware

LMP Link Management Protocol; part of [BT]

MMU Memory Management Unit; hardware in the BlueCore device that helps carry bulk dataefficiently between host and radio

NAK Negative AcKnowledge

NBC Number of broadcasts

NOP No OPeration

PCMPulse Code Modulation. BlueCore01b has a PCM port that can carry audio samples for aSCO connection. BlueCore2-External has three PCM ports, but the extra ports are notaccessible using the HCIStack1.1v14.3 builds.

PICS Protocol Implementation Conformance Statement

PS Persistent Store; the firmware’s configuration database

PS Key Storage element identifier for the Persistent Store

QoS Quality of Service

RAM Random Access Memory

RFCOMM Radio Frequency COM port; part of [BT]

SCO Synchronous Connection-Oriented

SDP Service Discovery Protocol; part of [BT]

[sic] Thus; as it is written

UART Universal Asynchronous Receiver Transmitter. BlueCore has a UART that carries H4 orBCSP

USB Universal Serial Bus

VM Virtual Machine. An environment in the BlueCore firmware for running application-specificcode

Record of Changes

bc01-an-107d © Copyright CSR 2001This material is subject to CSR’s non-disclosure agreement.

of 36

Imp

lemen

tation

of H

CI o

n B

lueC

ore

Record of Changes

Date: Revision Reason for Change:

11 OCT 01 a Original publication of this document (CSR reference: bc01-an-107a)

15 OCT 01 b Minor text amendments (CSR reference: bc01-an-107b)

25 APR 02 c

Amended and added information to SCO section, WRITE_LOOPBACK_MODE,flush commands, READ_RSSI. Extended to cover HCIStack1.1v13.x builds.Corrected example calculations in READ_BUFFER_SIZE (CSRreference:bc01-an-107c)

18 OCT 02 d

Extended to cover HCIStack1.1v14.x and HCIStack1.1v15.x builds. Replacedmost references to “BlueCore01” with “BlueCore”, except where BlueCore01b andBlueCore2-External remain specific. Added section on HCI Event Emission. Addedparameter limits and range advice for HOLD_MODE, SNIFF_MODE,PARK_MODE, CREATE_CONNECTION and REMOTE_NAME_REQUEST.Extended QOS_SETUP description. Added comments on HCI command flowcontrol. Added comments for CHANGE_CONNECTION_LINK_KEY. Updatedbccmd MAP_SCO_PCM section.

BlueCore

CSR’s Implementation of HCI on BlueCore

AN107

October 2002

Bluetooth™ and the Bluetooth logos are trademarks owned by Bluetooth SIG Inc, USA and licensed to CSR.

BlueCore is a trademark of CSR.

All other product, service and company names are trademarks, registered trademarks or service marks of theirrespective owners.

CSR’s products are not authorised for use in life-support or safety-critical applications.

csr’s implementation of hci on bluecore an107read.pudn.com/downloads287/doc/1296035/141_hci... ·...

Documents