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

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:

1. Open CommDB.

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

2. 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.

3. Open the table for editing.

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

4. 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.

5. 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.

6. 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(""));
   }

7. 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.

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".

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.

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

1. Define the connection preferences.

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

2. Load the Bluetooth stack.

   Initialise();

   Covered in the previous section.

3. Open the connection

   rerr = iConnection.Open(iSockSvr);

4. 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.

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