Release Notes for S60 Platform: Bluetooth Point-to-Multipoint Example v2.0

S60 Platform: Bluetooth Point-to-Multipoint Example v2.0

--------------------------------------------------------

This C++ example demonstrates the use of Bluetooth technology: device and service

discovery, connection establishment to one or more devices, communication between

devices, and disconnection. The Bluetooth RFCOMM protocol (RS-232 serial port

emulation) is used as a transport protocol.

Bluetooth basics:

----------------

The difference between a master and a slave needs to be distinguished first in order

to understand this example. A master is a device that establishes the connections

to remote devices, slaves. A slave cannot establish any connections; it will act as

a listener to incoming connections from the master device. The master discovers

slave devices and their services and is capable of connecting to multiple slaves and

holding these connections active simultaneously. In essence, the point-to-multipoint

connectivity defined here is a single master device (point) connecting to multiple

slave devices (multiple points).

A number of Bluetooth APIs provide the following capabilities that are demonstrated

in this example. Device discovery inquires for Bluetooth devices within range. Service

discovery inquires the discovered Bluetooth devices for the services they offer, filtering

the service discovery query to return only the service class required; in this way, the

service discovery query will only return the service entries that match the service class

of our service. Connection will then be established to all the remote Bluetooth devices

found to be offering the service we require. Once the connections are established,

messages can be sent from the master device to the connected slaves, and vice versa,

from a slave to its master device.

The slave mode initiates the application to act as a slave. In the slave mode, the

application listens to incoming connections and advertises its available service. The

master device will then be able to find the service offered by the slave by performing

device/service discovery and connection establishment to the slave’s listening

channel/port.

There are many Bluetooth protocols over which the connection can be accomplished.

RFCOMM is used in this example but also OBEX and L2CAP, among others, are

suitable for third-party applications.

--------------------------------------------------------------------------------

PREREQUISITES

Symbian C++ basics

Understanding the Bluetooth technology basics

--------------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

CBluetoothPMPExampleEngine:

Acts as an engine and handles the connections.

CDeviceDiscoverer:

Is used in device discovery.

CServiceDiscoverer:

Is used in service discovery.

CConnector:

Wraps a socket connection. CListener sets up a listening channel (notice

the different versions listener.cpp and listener_26.cpp).

Main Symbian classes used:

RSocketServ:

Socket Server

RHostResolver:

Provides an interface to host name resolution services, such as DNS,

that may be provided by particular protocol modules.

CSdpAgent:

Service discovery agent.

SdpSearchPattern:

Service discovery search pattern.

RSdp iSdp:

Service discovery protocol session.

--------------------------------------------------------------------------------

KNOWN ISSUES

The application is intended to be used on real devices, not on the emulator.

Problems may occur if many Bluetooth devices are in range. It will at least

take a lot longer for device and service discovery to complete.

Carbide causes a build warning NewApplication__Fv @1[BtPmpEx.def],

which can be ignored.

--------------------------------------------------------------------------------

RUNNING THE EXAMPLE

Launch the application on your device. A canvas displaying the application

name will appear; the application is ready for use. The Options menu provides

the following functionality:

Slave operations:

-----------------

Start slave:

Select this command to set the desired device(s) to listen for the incoming

connection. The application begins to advertise its available service.

Once the master has connected to the slaves, the slaves will display a

notification that they have been connected.

Connected slaves are able to send and receive messages.

Master operations:

------------------

Discover devices:

Discover the Bluetooth devices within range. Once the device discovery

completes, the discovered devices will be displayed.

Discover services:

Perform service discovery on the discovered devices. Once the service discovery

completes, the application will display the devices that advertise and

offer the service we require.

Connect devices:

Connect to the listening channel/port of the devices that offer the required

service. Once the connections are established, the names of the connected

devices are displayed.

Note that when the application is already connected to remote device(s), the

menu option "Connect Devices" actually disconnects the current connections

before creating new connections.

Show connected:

Displays the connected devices.

Common operations for slave and master:

---------------------------------------

Send message:

Prompts the user to enter a message and send it to the connected device.

When sent from the master device, the message will be sent to all connected

slaves. When sent from any of the slave devices, the message will first be

sent to the master which then echoes it to the other slaves (note that there is no

direct connection between the slaves and the echo functionality has to be

implemented into the application logic).

Clear screen:

Clears the log information on the screen.

When the application is running, the log shows the current situation. It shows what

devices are found, which of them contains the specified service, and what messages are

sent between devices. The log is written to the top of the screen.

--------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

The source code can be compiled on all S60 SDKs. Steps for building and

installing the application to a device depend on the S60 platform version:

Mobile device: S60 3rd Edition and later

-------------------------

go to \group

check that the right mmp (BluetoothPMPExample_3rd.mmp) is selected in the bld.inf file

run bldmake bldfiles

run abld build gcce urel

go to \sis

run makesis BTex_3rd.pkg

Sign the sis package file, either by self-signing it or using a developer certificate.

For further information on self-signing, see the "How to sign .sis" document in the SDK.

run signsis BTex_3rd.sis

Install the created and signed SIS file to your device.

Mobile device: S60 2nd Edition, Feature Packs 2 and 3

-------------------------------------

go to \group

check that the right mmp (BluetoothPMPExample_2ndFP2.mmp) is selected in the bld.inf file

run bldmake bldfiles

run abld build armi urel

go to \sis

run makesis BTEx_2ndFP2.pkg

Install the created SIS file to your device.

Mobile device: S60 1st Edition, S60 2nd Edition, and S60 2nd Edition, Feature Pack 1

-----------------------------------------------------------

go to \group

check that the right mmp (BluetoothPMPExample_1st.mmp) is selected in the bld.inf file

run bldmake bldfiles

run abld build armi urel

go to \sis

run makesis BTEx_1st.pkg

Install the created SIS file to your device.

Emulator (WINSCW)

-----------------

Go to /BluetoothPMPExample_v2_0/group

bldmake bldfiles

abld build winscw udeb

Start the emulator.

Carbide.c++ IDE

---------------

1. Make sure that the path for the current Carbide workspace does not contain any whitespace characters.

If necessary, select a new workspace folder in Carbide (File -> Switch workspace…).

2. Extract the example package to a temporary folder.

3. Select File -> Import… -> Symbian MMP File, click Browse, find the .mmp file you want to

import, and select the appropriate SDK/configurations. Check that 'Copy source files into workspace'

is selected, and then click Finish.

The project is now ready to be built.

--Mobile device (S60 3rd Edition)

Select Project -> Properties -> C/C++ Build

Set Configuration: "S60 3.0 Phone (GCCE) Release" and press OK.

Select Project -> Build project

Install the SIS file to the device.

--Mobile device (S60 1st and 2nd Edition)

Select Project -> Properties -> C/C++ Build

Set Configuration: "S60 2.6 Phone (ARMI) Release" or "S60 2.6 Phone (Thumb) Release"

and press OK.

Select Project -> Build project

Install the SIS file to the device.

--Emulator (WINSCW)

Select Project -> Properties -> C/C++ Build

Set Configuration: "S60 3.0 Emulator Debug" or "S60 2.6 Emulator Debug" and press OK.

Select Project -> Build project

Select Run -> Run As -> Run Symbian OS Application

--------------------------------------------------------------------------------

COMPATIBILITY

S60 3rd Edition

S60 2nd Edition

S60 1st Edition

Tested with Nokia 3650, Nokia 6600, Nokia 6630, Nokia E60, and Nokia E61.

Created / tested with Series 60 SDK 1.2 for Symbian OS, Supporting Metrowerks Codewarrior for Symbian OS

and with Series 60 2nd Edition SDK for Symbian OS, Supporting Feature Pack 2, for C++, Supporting Metrowerks CodeWarrior

and with S60 3rd Edition SDK for Symbian OS, for C++, Supporting Metrowerks CodeWarrior

--------------------------------------------------------------------------------

VERSION HISTORY

2.0 Ported from S60 2nd to S60 3rd Edition. Because of changes in the Symbian Bluetooth

architecture in Symbian OS v8.0a and major changes in Symbian OS v9.1,

three different builds of the example are needed:

Bluetooth_PMP_1st:

- Supports S60 1st Edition, S60 2nd Edition, and S60 2nd Edition, Feature Pack 1.

Bluetooth_PMP_2ndFP2:

- Supports S60 2nd Edition, Feature Packs 2 and 3.

Bluetooth_PMP_3rd:

- Supports S60 3rd Edition and later releases.

- Due to Symbian platform security, the following user-granted capabilities

are needed:

LocalServices, UserEnvironment, ReadUserData, WriteUserData, NetworkServices.

1.0 First release. Supports S60 1st Edition, S60 2nd Edition, and S60 2nd Edition, Feature Pack 1.

--------------------------------------------------------------------------------