Simulator user guide

Great Events of the Twentieth Centuryi
Great Events of the Twentieth Centuryi
i
Contents i
Introduction 1
Overview 1
Audience 1
How This Guide is Organised 2
Document Conventions 3
Getting Started 4
Overview 4
System Requirements 4
Installation Procedure 5
Verifying the Installation 5
Using the Simulator 19
Overview 19
Device Maintenance 20
Running applications 30
Using The Simulation Console 31
Link Security 35
Event Logging 38
Device Discovery 43
Overview 43
Device Inquiry 43
Device Retrieval 47
Creating Services 49
Overview 49
Service Record Creation 49
Service Record Publication 50
Service Record Update 51
Update of Device Service Class 52

Contents
Great Events of the Twentieth Centuryii
ii
Contents
Accessing Services 53
Overview 53
Service Discovery 53
Client Retrieval of Service Attributes 59
Using RFCOMM 61
Overview 61
Server Side RFCOMM 62
Client Side RFCOMM 65
Using L2CAP 67
Overview 67
Server Side L2CAP 67
Client Side L2CAP 71
Connection Configuration 72
Using OBEX 74
Overview 74
OBEX Protocol Overview 75
Server Side OBEX 78
Client Side OBEX 82
OBEX Authentication 85
Impronto Specific Classes 90
Overview 90
Configuration classes 90
Utilities 91
Comparing the simulator and real devices 93
Connections 93
Applications and devices 93

Impronto System Properties 95
Overview 95
Great Events of the Twentieth Centuryiii
iii
Contents
J2ME and the GCF 97
Overview 97
J2ME Configurations 97
J2ME Profiles 99
CLDC Connectivity 99
The Bluetooth Control Center 102
Overview 102
Security 102
Other BCC Functionality 105
The BCC Security Model 106
Great Events of the Twentieth Century1
1
Introduction
The Impronto Simulator provides a simulated Bluetooth environment that allows
developers to build Bluetooth-enabled Java applications without deploying them on
Bluetooth devices. The Impronto Simulator is 100% Java and supports the standard
JABWT (Java APIs for Bluetooth Wireless Technologies) developed by the JSR-82 expert
group.
The following features are supported in the product:
• Provides full support for L2CAP, RFCOMM, OBEX, SDP, HCI, BCC
• Runs actual application code in simulated mode
• Provides a management console for tracking and controlling the run-time behaviour of
devices and networks
• Allows users to create and configure virtual devices using the management console
• Has full logging capability for Bluetooth events, and can capture events for specific

devices with event filtering
• Supports J2ME applications for Windows and Linux
This guide is intended for the following audience:
• Experienced Java developers who wish to build Java-based Bluetooth applications.
• Software test engineers who require a simulated test environment for Bluetooth
enabled applications
Overview
Audience
Great Events of the Twentieth Century2
2
CHAPTER 1: Introduction
This guide is organised into 4 main sections
• Getting Started
• Using the Simulator
• JABWT Development
• Developing with the Impronto Simulator
Getting Started - Chapter 2
This section provides system requirements and installation instructions. It includes
detailed instructions on how to run the Echo demo, a simple application that can be used to
verify that the installation of the product was successful.
Using the Simulator - Chapter 3
This chapter describes how to use the Impronto Simulator. It introduces product features
such as simulated device configuration and logging, and explains how to use them when
running applications.
JABWT Development - Chapters 4 - 9
This section of the guide provides an introduction to the major topics an application
developer should be familiar with when developing JABWT applications. The topics
covered are:
• Device Discovery
• Service Discovery

• Service Registration
• Using the L2CAP protocol
• Using the RFCOMM protocol
• Using the OBEX protocol
Developing with the Impronto Simulator - Chapters 10 - 11
This section includes topics specific to developing with Impronto, including an overview of
the useful Java libraries provided with Impronto, and a discussion of the differences
between working with the simulator and using real Bluetooth devices.
How This Guide is Organised
Great Events of the Twentieth Century3
3
CHAPTER 1: Introduction
Java and Bluetooth Technology - Chapters 12 - 14
This section introduces important Java and Bluetooth concepts that relate to the Impronto
Simulator. It provides an overview of J2ME technologies, including CLDC and MIDP.
This section also includes a chapter introducing the Bluetooth Control Center (BCC) and
JABWT security.
The following conventions have been adopted in this document:
All Java code in the text appears like this.
All user input and menu selections referred to in the text appear like this
like thislike this
like this.
The Impronto Simulator can run on both the Linux and Windows platforms. In this guide
the character /
/ /
/ has been used as a directory separator. Please replace this character with \
\ \
\
if you are running the product on a Windows platform.
The string {

simulator_home
} represents the directory into which the Simulator was
installed.
Document Conventions
Great Events of the Twentieth Century4
4
Getting Started
This chapter guides you through the installation of the Impronto Simulator and a simple
verification of the installation. It includes the following topics
• System Requirements
• Installation Procedure
• Building and Running the Echo Demo
Software Requirements
The software requirements are as follows:
• JDK 1.4
• Windows 2000 or Redhat Linux
For J2ME development:
• me4se,
Hardware Requirements
• At least a Pentium processor with at least 64 MB of RAM
• 70 MB of disk space
Overview
System Requirements
Great Events of the Twentieth Century5
5
CHAPTER 2: Getting Started
Run the self-extracting installer as follows, java -jar simulator-installer.jar
java -jar simulator-installer.jarjava -jar simulator-installer.jar
java -jar simulator-installer.jar, and follow the
on-screen instructions.

This will install the Impronto Simulator, example applications, and the ant
ant ant
ant build tool.
Information about ant is available from
After the installation has completed, you will need to install your license file in order to use
the simulator.
The file must be copied into the simulator configuration directory, {
simulator_home
}/
config.
Using J2ME applications with Impronto
J2ME applications may be tested with Impronto Simulator using
me4se
, a J2ME emulation
environment for J2SE, available for download from s version of
Impronto has been tested against me4se version 2.1.2, which is shipped with the
Simulator.
The following section explains how to verify your installation using both J2ME and J2SE.
Your Impronto installation includes a number of sample applications that you can use to
verify that your installation has been successful and to practise using the simulator. The
sample applications are Chat, and Echo. All examples run on J2SE and J2ME.
This section steps through running the Echo demo, a very simple client-server application
in which the client connects to and sends a message to the server, and the server replies
with the same message. Both the client and server have a simple graphical interface, and
the application has two preconfigured simulated devices that communicate using the
L2CAP protocol.
To verify your installation, you need to:
• set up your development environment
• build the demo applications
• start the Bluetooth Simulation Console tool

Installation Procedure
Verifying the Installation
Great Events of the Twentieth Century6
6
CHAPTER 2: Getting Started
• run the Echo demo and verify its output
Set-up Environment
To set up your environment to build the examples, do the following:
• On Windows, type set PATH=%PATH%;{
set PATH=%PATH%;{set PATH=%PATH%;{
set PATH=%PATH%;{
simulator_home
simulator_homesimulator_home
simulator_home
}\ant\bin
}\ant\bin}\ant\bin
}\ant\bin
• On Linux, type export PATH=$PATH:{
export PATH=$PATH:{export PATH=$PATH:{
export PATH=$PATH:{
simulator_home
simulator_homesimulator_home
simulator_home
}/ant/bin
}/ant/bin}/ant/bin
}/ant/bin
Build the sample applications
Now you need to build the sample applications:
• Change to the {
simulator_home

}/examples directory
• Type ant
ant ant
ant to build all applications
Start the Bluetooth Simulation Console
If you are using Windows and specified that you would like a desktop or Start menu
shortcut added when installing the simulator, you can start the Bluetooth Simulation
Console using this shortcut. Otherwise:
• Change to the {
simulator_home
}/bin directory
• On Windows, type manager
managermanager
manager
• On Linux, type ./manager&
./manager&./manager&
./manager&
The Bluetooth Simulation Console should display, as in the next figure:
Great Events of the Twentieth Century7
7
CHAPTER 2: Getting Started
Great Events of the Twentieth Century8
8
CHAPTER 2: Getting Started
The following two sections guide you through running the Echo sample in J2SE and J2ME.
Run the Echo demo application - J2SE
This section tells you how to run the Echo sample application and verify its output in a J2SE
environment.
• Change to the {
simulator_home

}/examples/echo/bin directory
• On Windows, type start echo-server
start echo-serverstart echo-server
start echo-server
• On Linux, type echo-server&
echo-server&echo-server&
echo-server&
The server GUI will display:
A friendly name should be provided for the server - this name will be used to identify the
server device in the simulator.
• To set the friendly name, first select the Set Friendly Name
Set Friendly NameSet Friendly Name
Set Friendly Name option from the Server
ServerServer
Server
menu
• Then enter the name - let’s call it foo
foofoo
foo - in the dialog as shown below, and click OK
OKOK
OK
Great Events of the Twentieth Century9
9
CHAPTER 2: Getting Started
You now need to start the server so that it is ready to accept connections from the Echo
client.
• Start the server by selecting Server - Start
Server - StartServer - Start
Server - Start
The server will display the following message if it started successfully

If you check the Simulation Console, this should also be updated as in the figure below -
the device foo
foo foo
foo appears in the simulated network display and in the list of active devices.
Great Events of the Twentieth Century10
10
CHAPTER 2: Getting Started
Once you have started the server, the next step is to run the Echo client. You should open a
new command prompt window.
• On Windows, type start echo-client
start echo-clientstart echo-client
start echo-client
Great Events of the Twentieth Century11
11
CHAPTER 2: Getting Started
• On Linux, type echo-client&
echo-client&echo-client&
echo-client&
Like the Echo server device, the client device should also have a friendly name. In addition,
you must specify the server application that the client is to use.
• To specify a friendly name for the client, select the Set Friendly Name
Set Friendly NameSet Friendly Name
Set Friendly Name option from the
Client
ClientClient
Client menu
• Then enter the name in the dialog as shown and click OK
OKOK
OK
• Now select Select Server

Select ServerSelect Server
Select Server from the Client
ClientClient
Client menu
• Select the server application “Echo”, running on device “foo”, as shown in the dialog
below, leaving the default setting of No Authentication/No Encryption
No Authentication/No EncryptionNo Authentication/No Encryption
No Authentication/No Encryption
Great Events of the Twentieth Century12
12
CHAPTER 2: Getting Started
Finally, you need to start the client
• Start the client by selecting Client - Start
Client - StartClient - Start
Client - Start
Great Events of the Twentieth Century13
13
CHAPTER 2: Getting Started
As you can see, the client GUI is updated to show the transfer of information between the
client and the server.
The server GUI is also updated, as in the figure below:
Great Events of the Twentieth Century14
14
CHAPTER 2: Getting Started
And if you look at the Simulation Console, you can see both the client and server devices,
and the connection between them.
Great Events of the Twentieth Century15
15
CHAPTER 2: Getting Started
Run the Echo demo application - J2ME

Launch the server application:
• Run

the MIDP Echo
MIDP Echo MIDP Echo
MIDP Echo application
• Select Server
ServerServer
Server to start the server application
Great Events of the Twentieth Century16
16
CHAPTER 2: Getting Started
If you check the Simulation Console, this should also be updated as in the figure below -
the device Device1
Device1 Device1
Device1 appears in the simulated network display and the list of active devices,
and a new tab representing Device 1
Device 1Device 1
Device 1 has been added to the console.
Once you have started the server, the next step is to run the Echo client:
• Run the MIDP Echo
MIDP EchoMIDP Echo
MIDP Echo application
• Select Client
ClientClient
Client to start the client application
The client will search for, and then connect to, the server. The Echo client and server will
then exchange data.
The client GUI is updated to show the transfer of information between the client and the
server. Notice that the server GUI is also updated.

The client device appears in the Simulation Console as Device2
Device2Device2
Device2 along with the server
device, and the link between them is represented graphically as a line between the
devices, as shown in the second diagram below.
Great Events of the Twentieth Century17
17
CHAPTER 2: Getting Started
Great Events of the Twentieth Century18
18
CHAPTER 2: Getting Started
Great Events of the Twentieth Century19
19
#
Using the Simulator
The Impronto Simulator allows you to run JABWT-compliant Bluetooth applications in a
simulated environment. This environment consists of:
• Applications, running as clients or servers, each running in a separate Java Virtual
Machine (VM)
• A set of simulated devices, defined by the user using the Bluetooth Simulation Console.
Each device runs in the same VM as the application that uses it. The simulator currently
permits only a single application to run on each simulated device.
• A simulation co-ordinator which manages active devices and routes communications
between devices in the simulated network
• The Bluetooth Simulation Console, which monitors events and allows dynamic update
of device characteristics
When you run an application, you specify the device characteristics you would like the
application to use. The simulator creates the appropriate virtual device, and the Bluetooth
Simulation Console is updated to show the currently active devices. Each active device can
be selected and its characteristics viewed and updated dynamically.

Java applications that conform to the JABWT standard will not require any code changes to
use this simulated environment. You simply need to set one or more system properties to
allow an application to access its own simulated device.
The Simulation Console also includes a logging mechanism that allows you to activate
logging for specific devices and filter logged events.
This chapter explains how to do the following:
Overview
Great Events of the Twentieth Century20
20
CHAPTER 3: Using the Simulator
• Create Bluetooth device descriptions using the Simulation Console
• Use the Simulation Console to monitor sessions and dynamically update device
characteristics
• Use the Simulation Console to activate security for a device and perform device
authentication
• Activate logging and event filtering
In order to run applications in the simulated environment, you must first define the
characteristics of the devices that will be used by your applications. The Bluetooth
Simulation Console allows you to create new devices and edit existing devices. The
characteristics of each device are stored in individual XML configuration files in the
Simulator configuration directory. This directory is located by default in {
simulator_home
}/
config.
Device Maintenance Commands
You can find the device maintenance commands in the Simulation Console’s File
FileFile
File menu.
(Since we will not be using them, the Network and Service Views have been turned off in
the screenshots which follow. This is achieved by unchecking the Views

ViewsViews
Views menu item under
the Configure
ConfigureConfigure
Configure menu.)
Device Maintenance
Great Events of the Twentieth Century21
21
CHAPTER 3: Using the Simulator
Let’s look at how to create a new simulated device. As there is a blank tab already open,
you can use it to fill in the details of your device.
Device Characteristics
You use the form on the right-hand side of the screen to input device characteristics. You
type in a sequence of 12 hexadecimal digits for the Bluetooth Address
Bluetooth AddressBluetooth Address
Bluetooth Address - this is the unique
address that identifies each Bluetooth-enabled device. Then you type in a string for the
Friendly Name
Friendly NameFriendly Name
Friendly Name to be used by this device. This is a user-friendly name mapped to the
Bluetooth address that can be used to identify your device.
You check the box labelled Connectable
ConnectableConnectable
Connectable if the device is to be connectable. If this box is
unchecked then no device will be able to connect to this device. This flag should always be
set for servers.