Creating a Personal Area Network (PAN)

We are looking at a two device PAN in this tutorial. So if you want to run the example it must be installed on both devices. One device will initiate a connection and the other will listen for a connection. We will refer to the listener as D1 and the initiator as D2 when necessary.

Using the Tutorial

The code fragments in this tutorial are derived from the Bluetooth Example application available in /src/COMMON/DEVELOPERLIBRARY/examples/Bluetooth/BTExample1. Although the code has been reformatted to the requirements of the tutorial there is always enough information included with the code to find the actual example code.

Intended Audience:

This tutorial is designed for Symbian licensees only. Several APIs mentioned ad used throughout this tutorial series are only available in a device creators kit environment.

Basic procedure:

The high level steps to create a PAN are:

Configure the Pan services extension table and the LAN services table in CommDB.
Load the Bluetooth Stack
Start the PAN connection

Configuring CommDB PAN IAP

The PAN IAP (PANServiceExtensions table) will need to be configured for both devices. D1 will need to start a PAN listening connection. D2 will look for a listening device (D1) and connect to that device.

To configure CommDB tables for PAN do the following:

Open CommDB.

CCommsDatabase* db = CCommsDatabase::NewL();
CleanupStack::PushL(db);

Open a view on the PANServiceExtensionsTable1 table.

CCommsDbTableView* tableView =
db->OpenTableLC(TPtrC(PAN_SERVICE_EXTENSIONS));
TBuf<KMaxBufferSize> tableName;
tableView->GotoFirstRecord();
tableView->ReadTextL(TPtrC(COMMDB_NAME), tableName);

Check that we are looking at the correct table.

if(tableName == TPtrC(_S("PANServiceExtensionsTable1")))

The above simply ensures that the table name is what was expected.

Open the table for editing.

User::LeaveIfError(tableView->UpdateRecord());

Set the device to listen for incoming PAN connection requests if necessary.
```
tableView->WriteBoolL(TPtrC(PAN_ALLOW_INCOMING),aIsListening);
```
The value of aIsListening is ETrue for D1, the listening device.
Decide if the device will prompt for remote devices.
```
tableView->WriteBoolL(TPtrC(PAN_PROMPT_FOR_REMOTE_DEVICES),aUsePANNotifier);
```
The value of aUsePANNotifier is EFalse when you do not want the user to be prompted for a device. As with step 4 above this is the configuration for D1, the listening device, which will be accepting incoming connections instead of seeking other devices.
Set the PeerMacAddress to the Bluetooth device address of the device joining the PAN if known or to NULL if not known.

D2 will prompt for a Bluetooth device address (aDevAddr) when making the connection. So if aDevAddr exists then the device is trying to initiate a PAN with D1, the listening device. The Peer Mac Address of the listener will be returned by the notifier (see "Finding the Bluetooth Device Address") and added to the CommDB table as shown.
```
if(aDevAddr)
{
 TBuf<KMaxBufferSize> buf;
 aDevAddr->GetReadable(buf);
 tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), buf);
}
```
D1 is the listener and so will not need a Bluetooth device address when creating the listening connection.
```
else
{
 tableView->WriteTextL(TPtrC(PAN_PEER_MAC_ADDRESSES), _L(""));
}
```

Commit the CommDB PANServiceExtensionsTable changes.

User::LeaveIfError(tableView->PutRecordChanges());// Finish update
User::LeaveIfError(db->CommitTransaction());
}

The code above comes from CPanConnections::ConfigureIAPL() in "exampleroot/src/panconnection.cpp ".

ConfigureIAPL(TBool aIsListening,TBTDevAddr* aDevAddr,TBool aUsePANNotifier)
{

The function is called when a connection is started. This function is called with three values: aIsListening, aDevAddr, and aUsePANNotifier.

Attribute	Value
`aIsListening`	when called from `CPanConnections::StartConnection()`: `ETrue` if the device is listening for an incoming connection. `EFalse` if the device is not listening for an incoming connection.
`aDevAddr`	The Bluetooth device address.
`aUsePANNotifier`	when called from `CActiveConsole::ProcessKeyPressL()`: `ETrue` if the PAN notifier is needed. `EFalse` if the PAN notifier is not needed.

Attribute

Value

aIsListening

when called from CPanConnections::StartConnection():

ETrue if the device is listening for an incoming connection.
EFalse if the device is not listening for an incoming connection.

aDevAddr

The Bluetooth device address.

aUsePANNotifier

when called from CActiveConsole::ProcessKeyPressL():

ETrue if the PAN notifier is needed.
EFalse if the PAN notifier is not needed.

Finding the Bluetooth Device Address

The following code shows how to get and manipulate the Bluetooth device address:

...
TBTDevAddr devAddr; // Bluetooth device address.
//
TMenuMode = iMode; // from console.h
//
iMode = EPan;    //Ask user which device address we should connect to...
RNotifier notify; // get a notifier
User::LeaveIfError(notify.Connect()); // connect to the notifier
TBTDeviceSelectionParamsPckg pckg; // Bluetooth device parameters package
TBTDeviceResponseParamsPckg resPckg; // Response parameters package
TRequestStatus stat;
 // Start the notifier.
notify.StartNotifierAndGetResponse(stat,KDeviceSelectionNotifierUid,pckg,resPckg);
 // Wait for the notifier results.
User::WaitForRequest(stat);
notify.CancelNotifier(KDeviceSelectionNotifierUid);
 // Close the notifier now that we have the device details.
notify.Close();
User::LeaveIfError(stat.Int()); 
 // extract the Bluetooth device address from the notifier results.
devAddr = resPckg().BDAddr();
 // start the PAN connection request, send the Bluetooth device address.
iPanConnection->StartConnection(&devAddr, EFalse, EFalse);

Note: this fragment taken from CActiveConsole::ProcessKeyPressL() in "exampleroot/src/console.cpp ".

Loading the Bluetooth Stack

The Bluetooth stack will need to be loaded before a PAN is created.

Initialise()
{
 _LIT(KPDDName, "EUART1");        
 _LIT(KLDDName, "ECOMM");    
 TInt rerr = KErrNone;
 rerr = StartC32();// For any Serial comms
 // Load required drivers
 User::LoadPhysicalDevice(KPDDName);
 User::LoadLogicalDevice(KLDDName);
 iSockSvr.Connect();
 TProtocolDesc iProtocolInfo;
 TRequestStatus status;
 iSockSvr.FindProtocol(_L("L2CAP"), iProtocolInfo);
 // After Socket server is connected, start L2CAP protocol
 iSockSvr.StartProtocol(iProtocolInfo.iAddrFamily,
 iProtocolInfo.iSockType,iProtocolInfo.iProtocol, status);
 User::WaitForRequest(status);
}

The code above shows how to load the Bluetooth Stack using standard sockets.

Starting the PAN Connection

Now that you have loaded the Bluetooth stack and configured the PAN service extensions table a PAN connection can be opened.

Define the connection preferences.

 // EGeneralIAP = 1
PanProfileIAPs iap(EGeneralIAP); // panconnection.h
connPref.SetIapId(iap);
iConnPref.SetDialogPreference(ECommDbDialogPrefDoNotPrompt);
TInt rerr = iSockSvr.Connect();
if(rerr == KErrNone)
{

Load the Bluetooth stack.
```
Initialise();
```
Covered in the previous section.
Open the connection
```
rerr = iConnection.Open(iSockSvr);
```

Start the session if the connection opened correctly:

if(rerr == KErrNone)
{
 iConnection.Start(iConnPref,iStat);    
 User::WaitForRequest(iStat);
}
if(iStat==KErrNone)    
{

The code above is derived from CPanConnections::StartIAP() in "exampleroot/src/panconnection.cpp ".

That's all there is to creating a PAN.

What's next?

Having created a PAN you will need to add and remove devices and close the PAN. The following will help:

Creating a Personal Area Network (PAN) - This document
Adding a device to the PAN
Removing a device from the PAN
Closing the PAN

Parent topic: Bluetooth PAN Profile Tutorial