How_To_Writing_BlueCore_Applications

_äìÉi~Ä qj
Writing BlueCore Applications
User Guide
December 2007
CSR
Cambridge Science Park
Milton Road
Cambridge CB4 0WH
United Kingdom
Registered in England 4187346
Tel: +44 (0)1223 692000
Fax: +44 (0)1223 692001
www.csr.com
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.

Contents
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
4 Application Architecture ............................................................................................................................. 13
4.1 The Application Task ............................................................................................................................. 13
4.2 Profile and Support Tasks ..................................................................................................................... 14
4.3 Firmware................................................................................................................................................ 14
4.4 Message Scheduler............................................................................................................................... 15
5 Planning and Coding an Application.......................................................................................................... 16
5.1 Planning the Application ........................................................................................................................ 16
5.2 Coding Overview ................................................................................................................................... 16
5.2.1 Initialising Tasks......................................................................................................................... 16
5.2.2 Dynamic (Lazy) Tasks................................................................................................................ 18
5.2.3 Message Handling ..................................................................................................................... 21
6 Using the Bluetooth Radio, Working Example .......................................................................................... 22
6.1 Initialisation (common)........................................................................................................................... 23
6.2 Enable Inquiry and Page Scan (hello_world_b)..................................................................................... 23
6.3 Register the L2CAP PSM (common) ..................................................................................................... 23
6.4 Initiate an L2CAP Connection (hello_world_a) ...................................................................................... 23
6.5 Simple Pairing (common) ...................................................................................................................... 24
6.6 Authorising the L2CAP connection (hello_world_b)............................................................................... 24
6.7 Accept the L2CAP connection (hello_world_b)...................................................................................... 25
6.8 L2CAP Connection Confirmation (common)..........................................................................................25
7 Technical Support........................................................................................................................................ 26
Document References ........................................................................................................................................ 27
Terms and Definitions ........................................................................................................................................ 28
Document History ............................................................................................................................................... 32
Document Feedback ........................................................................................................................................... 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
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 2 of 32

Contents
Figure 3.3: LED Flashing Application Example 3 .................................................................................................. 12
Figure 4.1: Typical Application Architecture .......................................................................................................... 13
Figure 4.2: Initialising a Task ................................................................................................................................ 14
Figure 4.3: MessageLoop Function Call................................................................................................................ 15
Figure 5.1: Defining a Task Data Structure ........................................................................................................... 17
Figure 5.2: Declaring an Application Task............................................................................................................. 17
Figure 5.3:Initialising an Application Task ............................................................................................................. 17
Figure 5.4: Initialising a Profile Task ..................................................................................................................... 18
Figure 5.5: Message Handling Code..................................................................................................................... 21
Figure 6.1: L2CAP Connection Message Sequence Chart ................................................................................... 22
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 3 of 32

General
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 prequalified
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 architectural 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 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.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 4 of 32

Tasks, Messages and Message Handlers
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.
_äìÉi~Ä qj Writing BlueCore Applications
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.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 5 of 32

Tasks, Messages and Message Handlers
2.2.1 Message ID Numbering
The base number for Message IDs adhere to the following conventions:
• Messages send by a task to itself start at 0x00.
• System messages start at 0x8000.
• Messages sent by specific profile libraries to tasks have been assigned base values e.g. the connection
library messages start at base 0x7000 and the SPP library messages start at 0x6f00. See Appendix
B.
2.2.2 Sending Messages
A number of functions are provided to facilitate the sending of messages, see message.h in the on-line help C
Reference Guide.
2.3 Message Handling
The message handling facility for each task must be able to successfully handle all the message ids and states
that can be passed to it.
In practice the developer’s main responsibility is to provide the message handling code for the messages that will
be received by the application task.
Note:
The message handlers for profile and support tasks initialised from BlueLab or SDK libraries need not
concern developers. The handlers for these tasks are implemented by the libraries and are selected as a
result of calling the appropriate Init function.
The application must handle messages received from the libraries that it has initialised.
2.3.1 MessageLoop function
The MessageLoop function controls the main scheduler loop and handles the delivery of task messages.
Messages are added to the queue in the order they are due to be delivered. The scheduler checks the first
message in the queue and if due delivers the message to the appropriate task.
Note:
The MessageLoop function never returns and therefore is the last function called before the return
statement in main.
Tasks and messages allow the application developer to split the application up into cooperating modules (i.e.
tasks) that handle messages from the firmware and each other.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 6 of 32

Task and Messages, Working Examples
3 Task and Messages, Working Examples
The previous chapter introduced the concepts of tasks, messages and message handling.
This chapter looks at working examples to examine how these principals are applied in simple implementations of
code and gives a brief explanation of the elements within the code.
3.1 Example 1
The first example looks at a single task application that flashes an LED on a PIO pin with a regular on/off period
of 500 milliseconds.
Note:
The application has been chosen for simplicity, as it is one of the few examples that can be run on BlueCore
chips without using the connection library.
To do this the code:
• Defines a state for the single task required.
• Defines a handling routine for messages (that will read the state of a PIO pin and switch it at regular
intervals).
• Sets the PIO as output.
• Declares an instance of the task and initialises it.
• Sends an initial message that will invoke the handler code.
• Calls the MessageLoop function.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 7 of 32

Task and Messages, Working Examples
3.1.1 The Code
3.1.2 Analysis of Code
Figure 3.1: LED Flashing Application Example 1
1. The code employs functions declared in the message.h and pio.h header files so the first step is to
#include these files:
2. The next line of code defines a variable used to set a mask that identifies the PIO pin number that the
LED is attached to (in this example PIO 6):
_äìÉi~Ä qj Writing BlueCore Applications
3. The next step is to define a structure for the task state. This is done using the typedef specifier:
This defines a structure for the task and gives it the type ToggleTask.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 8 of 32

Task and Messages, Working Examples
The first element of the structure, i.e. task, has the type TaskData defined as:
{ void (*handler)(Task, MessageId, Message); }
This consists of a pointer to a function that takes the three standard message fields as arguments i.e. a
handler function.
4. The next block of code defines the message handler function MyHandler:
This code accepts a message as arguments then:
• change is assigned the value in change by casting t (the task’s address) to a pointer of type
ToggleTask pointing to the change field.
• Calls the PioSet function, the arguments passed to it have the effect of flipping the LED state i.e.
if the LED is on it is switched to off and vice versa.
• The final statement sends a message after a delay of 500 milliseconds. The message scheduler
delivers the message to MyHandler and the process is repeated, resulting in the LED flashing
on/off every 500 milliseconds.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 9 of 32

Task and Messages, Working Examples
5. The next line of code initialises the task:
It defines a task, toggle with parameters that point to the handler function and set the bit mask for the
PIO connected to the LED i.e. the handler will set PIO 6 (see #define statement).
6. The final block of code is the main function:
Looking at these statements individually:
• The first statement sets the PIO pin to which the LED is connected to output.
• The second sends a message to the handler, this kicks-off the LED sequence.
• The third statement calls the MessageLoop() function for message delivery.
• The final line complies with the ANSI C requirement to return a value.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 10 of 32

Task and Messages, Working Examples
3.2 Example 2
Example 2 expands on example 1 by adding a second flashing LED. This is achieved by adding a second task (in
this example called flash).
As no connection task is required, no AppTask as such is needed.
3.2.1 The Code
3.2.2 Analysis of Code
Figure 3.2: LED Flashing Application Example 2
This section considers how the code has been adjusted to add the second LED. Essentially this involves just 4
lines of code:
_äìÉi~Ä qj Writing BlueCore Applications
1.
Defines a label for the PIO pin to which the LED is connected (in this case PIO 7).
2.
Initialises a second task flash with parameters that point to the handler function and set the bit mask
for the PIO connected to a second LED i.e. the handler will set PIO 7 (see #define statement).
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 11 of 32

Task and Messages, Working Examples
3.
Sets the PIOs connected to the LEDs direction to output.
4.
Finally, the second LED is started by the MessageSendLater function, the final parameter of which
dictates the delay (in milliseconds) before the message is sent.
3.3 Example 3
Example 3 examines an alternative method of controlling the flashing LEDs. The salient point in this example is
the addition of a field the Task structure used to control the timing of the LEDs flashing sequence.
3.3.1 The Code
_äìÉi~Ä qj Writing BlueCore Applications
Figure 3.3: LED Flashing Application Example 3
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 12 of 32

Application Architecture
4 Application Architecture
This chapter describes how a typical BlueLab application uses tasks and messages to support Bluetooth profiles.
The application architecture can be considered in three parts:
• The application task.
• The profile and support tasks (including the connection task).
Note:
• The firmware.
These are library tasks provided by CSR to implement common functions, such as Bluetooth
profiles.
The architecture of the application is best illustrated graphically:
Application
Layer
Key:
Profile and
Support Tasks
Firmware Layer
= Messages
= Function Calls
4.1 The Application Task
Connection Task
Application Task
task1 task1 task1
BlueStack
Figure 4.1: Typical Application Architecture
Support Task
PIO
_äìÉi~Ä qj Writing BlueCore Applications
The application itself must be initialised as a task, and is generally known as the AppTask.
Defining a structure for the AppTask and coding the message handler represents the minimum requirement
when developing a BlueCore application.
The data structure for the AppTask is determined by the specific application’s requirements and should include
any data required to identify the state of the other tasks used by the application.
See section 5.2 for a more in-depth description of the AppTask.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 13 of 32

Application Architecture
4.2 Profile and Support Tasks
BlueLab provides libraries that implement commonly used functionality, including Bluetooth profiles, to support
the development of BlueCore applications.
Note:
The libraries support a wide range of Bluetooth Profiles. The addition of further libraries is a major objective
in the ongoing development of BlueLab.
To use a profile or support library in an application the developer must #include the appropriate library header
file and calls the initialisation function to create an instance of the task. See Figure 4.2.
The resultant task can then be regarded as a black box that handles any messages it receives and responds with
a message to the application task where appropriate.
Figure 4.2: Initialising a Task
The code in Figure 4.2 initialises the connection library. The connection task created can support multiple
connections and should only be called once.
The application task receives an _INIT_CFM message when a task is created. The message->
status indicates whether the task was created successfully or not.
As long as the developer’s application message handler code correctly handles messages received from an
instance of a task, the task will provide the expected functionality.
Note:
It is important to initialise the connection library before any other profile libraries because the connection
library task is required during the creation of profile tasks.
4.3 Firmware
BlueLab and SDK applications interface with the BlueStack element of the BlueCore firmware through the
connection task, i.e. the connection library gives access to Bluetooth features on BlueCore.
When the connection task is initialised, the developer need not be concerned with how the connection task
implements underlying functionality supported by the firmware.
_äìÉi~Ä qj Writing BlueCore Applications
The developer can concentrate on handling the limited number of messages that the application task can
potentially receive from the connection task.
Note:
Details of the messages generated by a connection task can be found in the xIDE on-line Reference Guide.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 14 of 32

Application Architecture
4.4 Message Scheduler
BlueLab and application SDKs provides a function to implement message scheduling. This function handles the
delivery of task messages.
Figure 4.3: MessageLoop Function Call
The MessageLoop function acts on queued messages owned by the tasks. Messages are added to the queue
in delivery due time order. The scheduler looks at the first message in the queue and if due, delivers it as
arguments to the appropriate task handler.
After a message has been passed to the task handler the MessageLoop function frees the original message
payload before handling the next message in the queue or waiting until another message is added to the queue.
Note:
The message scheduler is not pre-emptive. It is therefore important that all handler functions run to
completion and do not loop forever.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 15 of 32

Planning and Coding an Application
5 Planning and Coding an Application
This chapter considers the process of planning an application and gives a brief overview of the coding
requirements.
5.1 Planning the Application
The first step when developing an application is to determine the tasks required to provide the desired
functionality.
In practical terms Bluetooth applications always require:
• An application task
• A connection task
The other tasks depend on the type of device being developed and it is the developer’s responsibility to identify
the Profile and Support tasks that are required by their application.
When all the tasks that are required to build the application have been identified, the developer can begin to
consider the code required to support them.
5.2 Coding Overview
This section gives a high-level overview of the elements that constitute an application.
In simplistic terms the finished application code needs to:
1. Set up and initialise the required tasks.
2. Handle the messages received by the application task.
These two basic requirements constitute the essential elements of all BlueCore application code. The actual way
the code handles these requirements is largely at the discretion of the developer.
The code required to implement an actual application can become complex. However, sections 5.2.1 and 5.2.3
give brief description of the main elements.
5.2.1 Initialising Tasks
The code required to initialise a task depends on whether the task is developed by the software engineer e.g. the
application task, or is a task supported by a BlueLab library e.g. a profile task.
Initialising an Application Task
Setting up and initialising an application task involves three distinct steps:
• Typedef a data structure for the application task.
• Declare a variable for the application task.
• Initialise the application task states.
_äìÉi~Ä qj Writing BlueCore Applications
When initialising an engineer defined task the developer is responsible for including code to handle each of the
above steps.
Defining Task State Structures
The structure of the application task data type is at the discretion of the developer. It should allow for any data
required to identify the state of other tasks and any other data the developer may want to use within the
application.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 16 of 32

Planning and Coding an Application
It is the developer’s responsibility to define a suitable structure for the application task.
Figure 5.1 indicates a typical typedef for a simple Serial Port Profile (SPP) application task.
Note:
SPP has been selected as it is provides a simple example
Figure 5.1: Defining a Task Data Structure
When declaring a structure for a task the TaskData element is mandatory and must be the first element of the
structure.
Note:
TaskData is defined as:
Declaring the AppTask variable
{ void (*handler)(Task, MessageId, Message); }
When the structure for the application task has been defined, the application task can be declared e.g.:
Figure 5.2: Declaring an Application Task
This declaration defines the application task as a static variable called theSppApp with a data type as defined
by sppTaskData.
Initialising the Application Task
The task is initialised by setting up the task’s message handler:
Figure 5.3:Initialising an Application Task
_äìÉi~Ä qj Writing BlueCore Applications
In most cases it is also desirable to set up initial states for any variables associated with the task data.
Initialising a ProfileTask
When initialising a task supported by BlueLab or SDK libraries simply calling the appropriate Init function (with
the argument pointing to the address of the application task handler) performs all the necessary steps for the task
to be used by the application e.g:
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 17 of 32

Planning and Coding an Application
Figure 5.4: Initialising a Profile Task
Each time an Init function is called an instance of the respective task is created, memory allocated and a
pointer to it is sent back to the application task.
Note:
ConnectInit is a special case in that it can only be called once. The connection task can maintain
multiple connections in a single instance of the task.
5.2.2 Dynamic (Lazy) Tasks
From BlueLab v4.0 onwards dynamic (or lazy) tasks will be supported in VM applications.
Note:
In computer programming, lazy initialization delays the creation of an object, the calculation of a value, or
some other expensive process until the first time it is needed. (from Wikipedia)
Lazy tasks provide the following benefits:
• A task instance is created and destroyed dynamically when needed. This provides better use of the
limited memory resources available to a VM application.
• More profiles can be supported in a single application since they do not need a task instance to be
allocated on start up.
• An application needs to call the initialisation function of a profile library only once. This simplifies the
application initialisation state machine.
Note:
Without dynamic tasks the application needs to call the init function multiple times if it wants to
support more than one instance of the profile
• Without dynamic tasks a service record is registered for each profile instance. For example, if the
application wishes to support two simultaneous HFP connections it calls HfpInit() twice. This
registers two service records (with different RFCOMM server channels) with the SDP server in
BlueStack. Although this is within specification it makes for a less elegant implementation as it requires
the service record to be unregistered when that service has been connected to (and registered again
when the connection is dropped).
• Support can be provided for multiple profile instances for profile libraries using L2CAP.
Note:
Without dynamic tasks only a single profile library instance can be supported as only one task
can be sent notifications of incoming connections. For example, this meant that before support
for dynamic tasks only a single AV connection could be maintained.
Registering the Client Task with the Connection Library
For all instances of a dynamic task the first operation is to register it with the connection library, so that an
RFCOMM channel or L2CAP PSM can be allocated. During this process the profile library also registers a
profile_task_recipe. This is stored by the connection library and is used to dynamically create an
instance of the specified profile library when required.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 18 of 32

Planning and Coding an Application
The profile_task_recipe is defined as:
typedef struct profile_task_recipe
{
uint16
MessageId
TaskData
uint16
const struct profile_task_recipe
} profile task recipe;
size_instance;
msg_id;
data;
max_channels
*parent_profile;
Where:
size_instance: This is the size of the profile task data for the profile registering with the
connection library.
msg_id: The message the connection library will send to the newly created task.
Data: The task data for the profile task instance i.e. the profile handler function.
max_channels: The maximum number of channels the profile instance will support
parent_profile: The task recipe of the parent profile.
Lazy tasks must be able to accommodate incoming and outgoing connections, each of which is handled
differently:
Incoming Connections
On an incoming connection the task instance needs to be created dynamically by the connection library when
it first receives the incoming connection indication. The connection library does this in two steps:
1. The task instance is allocated and the profile handler set up. The size_instance field is used to
allocate the memory for the task data and the data field is used to initialise the handler function of the
newly created task.
2. The initialisation message (msg_id) is sent to the newly created task.
At this point the profile task instance has been created and partially initialised and the incoming connection
indication can be sent to the new task. The task initialisation message is sent as soon as the task is created. This
means that it will be delivered before any incoming connection indication message and by the time that message
is delivered the profile task will be fully initialised. The incoming connection message is then handled as normal
by the newly created task.
Outgoing Connections
_äìÉi~Ä qj Writing BlueCore Applications
On an outgoing connection the profile library is responsible for creating the profile instance and using it in the
connect request to the connection library. All libraries follow the same convention and the API function for
initiating a connection creates an internal message to send to itself.
The profile instance must be created and initialised before this internal message is sent so that, by the time the
message is delivered, the task is ready to be used.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 19 of 32

Planning and Coding an Application
Destroying a Dynamic Task
Tasks that are allocated dynamically must be destroyed when they are no longer needed. In most cases this will
be when the profile level connection is disconnected. On a disconnect indication, the profile library is responsible
for notifying any clients of the disconnect and then cleaning up its state and destroying the profile task instance.
When a client has received a disconnect indication it must not attempt to use the profile task instance (identified
in the indication message) as that task has already been destroyed.
Note:
A disconnect is not the only case where a task will need to be destroyed. Other cases include a connect fail
or the rejection of an incoming connection by the application.
When the task needs to clean itself up, there may be outstanding messages for it in the queue.
MessageTaskFlush must be called to ensure any such messages are removed. This is done by the profile
instance as part of the clean up process.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 20 of 32

Planning and Coding an Application
5.2.3 Message Handling
The application task message handler must be able to successfully handle all the message states that can be
passed to it by the other tasks that provide the application functionality.
Typically, the handler consists of switch statements designed to take the appropriate action in response to the
message id and the task state as indicated by a message passed to the handler function. Figure 5.5 shows a
simplified example indicating typical message handler code.
Example:
_äìÉi~Ä qj Writing BlueCore Applications
Figure 5.5: Message Handling Code
It is the developer’s responsibility to ensure that the application task handles the messages it receives, to achieve
the results expected/required by the application.
Note:
By convention, the message structure is always enumerated as the name of the message (i.e. the Message
Id) with a suffix of _T. For example, if the message name is CL_INIT_CFM then the message type will be
CL_INIT_CFM_T.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 21 of 32

Using the Bluetooth Radio, Working Example
6 Using the Bluetooth Radio, Working Example
This section describes how to set up a simple ACL connection between two Bluetooth devices. In this example,
the connection is used for L2CAP and employs Bluetooth 2.1 Simple Pairing Just Works for authentication of the
link.
The example requires two separate communicating applications, a master A application on one device and a
slave B application on the other device.
Double-click on this
xIDE.
icon to open the master A example code which you can then paste into a New project in
Double-click on this
xIDE..
icon to open the master B example code which you can then paste into a New project in
Figure 6.1: L2CAP Connection Message Sequence Chart
Figure 6.1 shows the basic message sequence chart for the applications on two Bluetooth devices,
hello_world_a and hello_world_b. In the example, hello_world_a is the master and initiates the
connection to hello_world_b. Hello_world_b which is inquiry and Page scanning. The BlueStack radio
interactions are simplified, as that is not the focus of this example.
_äìÉi~Ä qj Writing BlueCore Applications
The applications in this example share the majority of their functionality, therefore the description of the code
samples indicates whether it is specific to the master A application, specific to the slave B application or common
to both:
• Common: common to both applications
• hello_world_a: specific to the master A application
• hello_world_b: specific to the slave B application
The initialisation of the connection library, used to provide the functionality and API for creating the L2CAP
connection, is covered in section 5.2.1.
The master A application has been hard coded with the Bluetooth address of the slave B device so that no device
inquiry and discovery phase is required.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 22 of 32

Using the Bluetooth Radio, Working Example
6.1 Initialisation (common)
When a connection has been established and bonded between two devices, the connection library stores the
Bluetooth address of a bonded device and its link keys in PS Keys USR41 to USR49. The example
demonstrates Simple Pairing when making a connection. In order to ensure this is carried out, all previously
authenticated device information is deleted as part of the application initialisation.
6.2 Enable Inquiry and Page Scan (hello_world_b)
The slave B application is configured to enable scans for pages, although in the above example it has been
configured to respond to inquiries as well.
6.3 Register the L2CAP PSM (common)
Both applications must register the L2CAP PSM value that is used to identify the connection, before attempting to
establish the connection. The PSM must be an odd number and is a 16-bit value. In the example, a PSM of 257
is used (see Bluetooth Core Specification for L2CAP).
The BlueStack firmware responds to the PSM registration request with a CL_L2CAP_REGISTER_CFM
message, indicating success or failure.
6.4 Initiate an L2CAP Connection (hello_world_a)
_äìÉi~Ä qj Writing BlueCore Applications
Triggered by the successful registration of the PSM, the master A application initiations an L2CAP connection
request. The Bluetooth address of the device to connect to (&theApp.dev_b) and the PSM of the L2CAP
connection to connect from and to are passed as parameters. In this example, it is the same PSM value.
Further L2CAP configuration parameters can be set but in this example, the default configuration is used by
passing 0 or NULL for the configuration parameter block.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 23 of 32

Using the Bluetooth Radio, Working Example
6.5 Simple Pairing (common)
The example code above is taken from the master A application, although the code is common to both example
applications. The slave B device requests the IO Capability of the Master A device first, and then after the master
A device has responded, it requests the IO Capability of the Slave B device.
The application must interact with BlueStack during the Simple Pairing scenario to indicate the hardware
capability of the device which is being paired. In this example, both the master A device and slave B device
indicate that they have no capability for input or output and also no Out Of Band data is used.
Simple Pairing then proceeds using the Just Works model. Although more secure than the authentication
previous to Bluetooth 2.1, it is still susceptible to a Man In The Middle (MITM) attack. (see Simple Pairing in the
Core Specification).
When the other device, receives the IO Capability Response, it indicates this to the application by a
CL_SM_REMOTE_IO_CAPABILITY_IND message.
6.6 Authorising the L2CAP Connection (hello_world_b)
_äìÉi~Ä qj Writing BlueCore Applications
After Simple Pairing is complete, the CL_SM_AUTHORISE_IND message indicates to the Slave B device that
the Master A device is trying to establish a connection to it. The slave B application authorises the connection on
the indicated L2CAP channel.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 24 of 32

Using the Bluetooth Radio, Working Example
6.7 Accept the L2CAP Connection (hello_world_b)
After the L2CAP channel connection has been authorised, the L2CAP Connection is indicated to the Slave B
application. The application then send a response indicating that the L2CAP connection for the PSM is accepted.
(see the xIDE online C reference Guide).
6.8 L2CAP Connection Confirmation (common)
Both applications receive a CL_L2CAP_CONNECT_CFM message to indicate that the L2CAP connection has
been successfully set-up and is ready to use. The applications can start to transfer data across the radio using
the L2CAP connection.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 25 of 32

Technical Support
7 Technical Support
Further information on all CSR products can be found on the technical support website
(http://www.csrsupport.com).
Developers are also recommended to view the public newsgroups hosted by CSR on the Internet news (NTTP)
server news.csr.com. The newsgroups are a convenient forum for the Bluetooth community to exchange
knowledge and are a valuable source of information.
Set up instructions and guidelines for the use of newsgroups can be found by following the links on the CSR
support website and in an introduction to BlueLab (CSR ref: blab-ug-001P).
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 26 of 32

Document References
Document References
Document
an introduction to BlueLab
BlueLab xIDE user guide
a guide to the BlueLab Libraries
Implementing Streams in BlueLab
VM Memory Mapping and Memory Usage
CSR Reference
blab-ug-001P
blab-ug-002P
CS-101501-UG
CS-110344-UG
CS-110364-AN
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 27 of 32

Terms and Definitions
Terms and Definitions
API
BlueCore®
Bluetooth®
CSR
e.g.
etc
i.e.
L2CAP
MITM
PSM
SPP
VM
xIDE
Application Programming Interface
Group term for CSR’s range of Bluetooth wireless technology chips
Set of technologies providing audio and data transfer over short-range radio connections
Cambridge Silicon Radio
exempli gratia, for example
et cetera, and the rest, and so forth
Id est, that is
Logical Link Control and Adaptation Protocol
Man-In-The-Middle
Protocol Service Multiplexer
Serial Port Profile
Virtual Machine; environment in the BlueCore firmware for running application-specific code
produced with BlueLab
BlueLab’s Integrated Development Environment
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 28 of 32

System Messages
Appendix A
System Messages
This section describes BlueLab’s system messages. They provide a means for a VM application to find out about asynchronous events. Effectively every possible asynchronous event is mapped onto a message from the system. A single task within the application
can register an interest in particular messages. When a task has registered an interest any appropriate message types are routed to that task. If no task registers an interest in a particular message then that message is silently discarded.
Note:
Registering an interest in any BlueStack primitive registers all BlueStack primitives which will then be sent to the registering task
Message Payload Type Task Granularity Description
BLUESTACK_LC_PRIM
BLUESTACK_LM_PRIM
BLUESTACK_HCI_PRIM
BLUESTACK_DM_PRIM
BLUESTACK_L2CAP_PRIM
BLUESTACK_RFCOMM_PRIM
BLUESTACK_SDP_PRIM
BLUESTACK_BCSP_LM_PRIM
BLUESTACK_BCSP_HQ_PRIM
uint16* MessageBlueStackTask System wide The corresponding BlueStack primitives
BLUESTACK_BCSP_BCCMD_PRIM
BLUESTACK_CALLBACK_PRIM
BLUESTACK_TCS_PRIM
BLUESTACK_BNEP_PRIM
BLUESTACK_TCP_PRIM
BLUESTACK_UDP_PRIM
BLUESTACK_FB_PRIM
FROM_HOST Bluestack primitive* MessageHostCommsTask System wide Word-oriented messages passed over BCSP#13
MORE_DATA MessageMoreData* MessageSinkTask Per sink
Data may have arrived on the source corresponding to
the registered sink.
MORE_SPACE MessageMoreSpace* MessageSinkTask Per sink Data may have left the registered sink.
PIO_CHANGED MessagePioChanged* MessagePioTask System wide
PioDebounce (or PioDebounce32) must have been
called to enable the messages
FROM_KALIMBA MessageFromKalimba* MessageKalimbaTask System wide DSP application must be running
ADC_RESULT MessageAdcResult* AdcRequest Per request Task registered per-request using AdcRequest
STREAM_DISCONNECT MessageStreamDisconnect* MessageSinkTask Per sink
Message is sent to *both* tasks registered for source and
sink of the connection.
ENERGY_CHANGED MessageEnergyChanged* MessageSinkTask
Per sink and
request
STATUS_CHANGED NONE MessageStatusTask Per request
SOURCE_EMPTY MessageSourceEmpty* MessageSinkTask Per sink
LONG_MESSAGE_FROM_KALIMBA LongMessageFromKalimba* MessageLongKalimbaTask System wide
USB_ENUMERATED NONE MessageSystemTask System wide
The message is sent to the task associated with the sink
identifying the SCO stream. Estimation must be enabled
(on a single-shot basis) using EnergyEstimationOn
or EnergyEstimationSetBounds.
The message is sent (an a one-shot basis) if any of the
fields specified in the MessageStatusTask change.
Details of the change can then be found using
StatusQuery.
Sent when the source corresponding to the sink becomes
empty (and cannot possibly become full again.)
A long message (longer than four words) is received from
Kalimba.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGPc
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 29 of 32

System Messages
Message Payload Type Task Granularity Description
USB_SUSPENDED MessageUsbSuspended* MessageSystemTask System wide
CHARGER_CHANGED MessageChargerChanged* MessageChargerTask System wide
PSFL_FAULT NONE MessageSystemTask System wide
USB_DECONFIGURED NONE MessageSystemTask System wide
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGPc
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 30 of 32

Library Message Bases
Appendix B
Library Message Bases
This appendix shows the hex value bases for BlueLab library messages.
Library Message Base Library Message Base
Connection 0x7000 FTP Server 0x6500
SPP 0x6f00 Codec 0x6400
HFP 0x6e00 AGHFP 0x6300
A2DP 0x6d00 PBAP Client 0x6200
GAVDP (1) 0x6c00 PBAP Server 0x6100
AVRCP 0x6b00 PIO Library 0x6000
GOEP (OBEX) 0x6a00 DUN Library 0x5f00
FTP Client 0x6900 audio 0x5d00
Battery library 0x6800 GOEPC 0x5c00
OPP Client 0x6700 GOEPS 0x5b00
OPP Server 0x6600 HID 0x7100
(1) The GAVDP library is deprecated from BlueLab v4.0 onwards.
_äìÉi~Ä qj Writing BlueCore Applications
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 31 of 32

Document History
Document History
Revision Date Reason for Change
ISSUE 1 14 DEC 07 Original publication of this document. (CSR reference: CS-110344-UGP1)
Document Feedback
If you have any comments about this document, send an email to comments@csr.com, giving the document
number, title and section with your feedback.
Unless otherwise stated, words and logos marked with or ® are trademarks registered or owned by Cambridge
Silicon Radio Limited or its affiliates. Bluetooth ® and the Bluetooth logos are trademarks owned by Bluetooth SIG,
Inc. and licensed to CSR. Other products, services and names used in this document may have been
trademarked by their respective owners.
_äìÉi~Ä qj Writing BlueCore Applications
The publication of this information does not imply that any license is granted under any patent or other rights
owned by Cambridge Silicon Radio Limited.
CSR reserves the right to make technical changes to its products as part of its development programme.
While every care has been taken to ensure the accuracy of the contents of this document, CSR cannot accept
responsibility for any errors.
CSR’s products are not authorised for use in life-support or safety-critical applications.
CS-110344-UGP1
© CSR plc 2007
This material is subject to CSR’s non-disclosure agreement.
Page 32 of 32