CS-110344-UGP2
© Cambridge Silicon Radio Limited 2007-2008
This material is subject to CSR’s non-disclosure agreement.
CSR
Cambridge Science Park
Milton Road
Cambridge CB4 0WH
United Kingdom
Registered in England 3665875
Tel: +44 (0)1223 692000
Fax: +44 (0)1223 692001
www.csr.com
_äìÉi~Ä
qj
Writing BlueCore Applications
User Guide
Issue 2
Contents
CS-110344-UGP2
© Cambridge Silicon Radio Limited 2007-2008
This material is subject to CSR’s non-disclosure agreement.
Page 2 of 32
_äìÉi~Ä
qj
Writing BlueCore Applications
Contents
1 General............................................................................................................................................................ 4
1.1 Introduction.............................................................................................................................................. 4
2 Tasks, Messages and Message Handlers .................................................................................................... 5
2.1 Tasks ..................................................................................................................................................... 5
2.2 Messages ................................................................................................................................................ 5
2.2.1 Message ID Numbering ............................................................................................................... 6
2.2.2 Sending Messages....................................................................................................................... 6
2.3 Message Handling................................................................................................................................... 6
2.3.1 MessageLoop function ................................................................................................................. 6
3 Task and Messages, Working Examples ..................................................................................................... 7
3.1 Example 1................................................................................................................................................ 7
3.1.1 The Code ..................................................................................................................................... 8
3.1.2 Analysis of Code .......................................................................................................................... 8
3.2 Example 2.............................................................................................................................................. 11
3.2.1 The Code ................................................................................................................................... 11
3.2.2 Analysis of Code ........................................................................................................................ 11
3.3 Example 3.............................................................................................................................................. 12
3.3.1 The Code ................................................................................................................................... 12
3.3.2 Analysis of Code: ....................................................................................................................... 13
4 Application Architecture ............................................................................................................................. 14
4.1 The Application Task ............................................................................................................................. 14
4.2 Profile and Support Tasks ..................................................................................................................... 15
4.3 Firmware................................................................................................................................................ 15
4.4 Message Scheduler............................................................................................................................... 16
5 Planning and Coding an Application.......................................................................................................... 17
5.1 Planning the Application ........................................................................................................................ 17
5.2 Coding Overview ................................................................................................................................... 17
5.2.1 Initialising Tasks......................................................................................................................... 17
5.2.2 Dynamic (Lazy) Tasks................................................................................................................ 19
5.2.3 Message Handling ..................................................................................................................... 22
6 Using the Bluetooth Radio, Working Example .......................................................................................... 23
6.1 Initialisation (common)........................................................................................................................... 24
6.2 Enable Inquiry and Page Scan (hello_world_b)..................................................................................... 24
6.3 Register the L2CAP PSM (common) ..................................................................................................... 24
6.4 Initiate an L2CAP Connection (hello_world_a) ...................................................................................... 24
6.5 Simple Pairing (common) ...................................................................................................................... 25
6.6 Authorising the L2CAP Connection (hello_world_b).............................................................................. 25
6.7 Accept the L2CAP Connection (hello_world_b)..................................................................................... 26
6.8 L2CAP Connection Confirmation (common).......................................................................................... 26
7 Technical Support........................................................................................................................................ 27
Document References ........................................................................................................................................ 31
Terms and Definitions ........................................................................................................................................ 31
Document History ............................................................................................................................................... 32
Document Feedback ........................................................................................................................................... 32
Contents
CS-110344-UGP2
© Cambridge Silicon Radio Limited 2007-2008
This material is subject to CSR’s non-disclosure agreement.
Page 3 of 32
_äìÉi~Ä
qj
Writing BlueCore Applications
List of Figures
Figure 3.1: LED Flashing Application Example 1 .................................................................................................... 8
Figure 3.2: LED Flashing Application Example 2 .................................................................................................. 11
Figure 4.1: Typical Application Architecture .......................................................................................................... 14
Figure 4.2: Initialising a Task ................................................................................................................................ 15
Figure 4.3: MessageLoop Function Call................................................................................................................ 16
Figure 5.1: Defining a Task Data Structure ........................................................................................................... 18
Figure 5.2: Declaring an Application Task............................................................................................................. 18
Figure 5.3:Initialising an Application Task ............................................................................................................. 18
Figure 5.4: Initialising a Profile Task ..................................................................................................................... 19
Figure 5.5: Message Handling Code..................................................................................................................... 22
Figure 6.1: L2CAP Connection Message Sequence Chart ................................................................................... 23
General
CS-110344-UGP2
© Cambridge Silicon Radio Limited 2007-2008
This material is subject to CSR’s non-disclosure agreement.
Page 4 of 32
_äìÉi~Ä
qj
Writing BlueCore Applications
1 General
_äìÉi~Ä» SDKs provide developers with a series of libraries that support the implementation of Bluetooth
applications that run on _äìÉ`çêÉ∆ chips.
The use of the supplied libraries allows engineers to develop BlueCore applications that implement Bluetooth
Profiles without becoming distracted by the complexity of the underlying Bluetooth Protocols.
This approach has the additional benefit of allowing the underlying BlueCore firmware to be considered as a pre-
qualified component of the final product.
This document illustrates at a conceptual level how the source code and supplied libraries are used to build
Bluetooth applications to run on BlueCore chips.
This document should be read in conjunction with the Reference Guides provided as part of BlueLab’s on-line
documentation that details the library-defined functions and the messages generated by the supplied libraries.
1.1 Introduction
This document introduces the fundamental concepts employed when developing applications designed to run on
CSR’s BlueCore chips.
The document covers:
The fundamentals of tasks, messages and message handling
How these are used by the libraries
How this defines the architecture of a typical BlueCore application
The basic concepts and simple coding examples in this document are intended to illustrate good practice when
writing code to run on BlueCore’s Virtual Machine (VM) and to help engineers gain a clearer understanding of
using BlueLab SDKs to develop applications.
In addition the reference applications supplied with BlueLab provide engineers with a valuable resource that can
be used as a basis for their own application development or simply to help increase the understanding of how to
implement BlueCore applications.
The VM Memory Mapping and Memory Usage application note is also recommended reading for engineers
embarking on the process of developing BlueCore applications.
Tasks, Messages and Message Handlers
CS-110344-UGP2
© Cambridge Silicon Radio Limited 2007-2008
This material is subject to CSR’s non-disclosure agreement.
Page 5 of 32
_äìÉi~Ä
qj
Writing BlueCore Applications
2 Tasks, Messages and Message Handlers
It is important to understand the concept of tasks, messages and message handling as they are integral to the
way BlueLab applications are implemented.
The sections
2.1 to 2.3 introduce these concepts:
2.1 Tasks
Tasks are the basic architectural building blocks used to construct an application and to provide an interface with
the BlueCore firmware.
Tasks provide functionality to the application i.e. an instance of the appropriate task must be initialised by the
code in order for the functionality it supports to be available to the application.
A task is basically a message handling function and a structure containing the task’s current state. All tasks are
run as a single thread i.e. tasks do not execute concurrently.
The tasks that make up the application include a top level task known as the application task. The application
task responds to messages and controls the behaviour of the application.
Note:
More complex applications may define more than one application task.
2.2 Messages
Messages pass information between the tasks and are constructed in the form:
Task t, MessageId id, Message payload
The elements of a message are described below:
Task t: Identifies the destination of the message i.e. it is a pointer to the recipient task e.g.
&AppTask.
MessageId id: is the message label that allows the task receiving the message to identify the
appropriate function within the handler code.
The
MessageId id also implies the fields that can be expected in the payload. This allows the
required information to be extracted by casting pointers to the payload fields.
Note:
By convention, a message’s structure is always enumerated as the Message Id with a suffix of _T.
For example, the structure of the message
CL_INIT_CFM is enumerated as Type
CL_INIT_CFM_T.
Message payload: The payload should contain any state data required by the handler function to
correctly react to the message. The payload is freed after the message has been delivered.
To maximise the efficient use of memory the data passed in the payload should be kept to the minimum
required by the message handling function to implement the appropriate response.
In some cases, the message id alone may be sufficient. Therefore, the payload field is optional and can
be
Null.
