Using Bluetooth BTComm

Purpose

This document shows you how to set up a BTComm serial port in exclusive mode.

Opening a BTComm Connection

First you need to create some objects.

// Opening a simple BTCOMM connection.
// Create an RCommServ object.
RCommServ iCommServ;
// Create an RComm object.
RComm iComm;
// Required LITs
_LIT(KTxtBTCOMM,"BTCOMM");
_LIT(KTxtBTCommName,"BTCOMM::");

Connect to the serial comms server:

iCommServ.Connect();

Load the Bluetooth BTComm CSY module using RCommServ::LoadCommModule().

iCommServ.LoadCommModule(KTxtBTCOMM);

Prepare the port name for the connection.

TBuf8<15> commname(KTxtBTCommName);
commname.AppendNum(0);

The TDes8::AppendNum() function above appends the decimal character '0', representing the port for this example, onto the end of the 'commname' descriptor. The RCommServ::GetPortInfo() function is used to discover the port number if it is not known.

Open and configure the BTComm serial port.

User::LeaveIfError(iComm.Open(iCommServ,commname,ECommExclusive));

RComm::Open() uses three parameters for a Bluetooth connection, they are shown in the following table:

The code above assumes your application is opening a BTComm port using the default BTComm CSY.

Using the Bluetooth Serial port

The point of opening a port is to enable data transfer. RComm allows you to read and write data over the port. There are several kinds of read and write methods available.

Reading

RComm::Read() reads data from the serial port. There are several variants of the Read() method. The standard read provides a TRequestStatus and the TDes8 descriptor as a buffer. All reads from the serial device use 8-bit descriptors as data buffers. The number of bytes is set to the maximum length of the descriptor. A length can be provided as a parameter when a known length is required. In that case the number of bytes is set to aLength. A timeout can be applied to data being read from the serial port using TTimeIntervalMicroSeconds32 aTimeOut. The timeout read can either use the default maximum length of the descriptor or a specific aLength for the number of bytes in the buffer.

The simplest variant of Read() is shown here:

iComm.Read(iStatus, iBuffer);

iComm is the instance of RComm opened earlier.

RComm::ReadOneOrMore() is similar to the standard Read() method in that it reads any data in the buffer up to the maximum length of the descriptor. If the buffer is empty ReadOneOrMore() waits until one or more byte arrives.

Writing

RComm::Write() writes data to the serial port. There are several variants of Write(). The standard write provides a TRequestStatus and the TDes8 descriptor as a buffer. All writes from the serial device use 8-bit descriptors as data buffers. The number of bytes is set to the maximum length of the descriptor. A length can be provided as a parameter when a known length is required. In that case the number of bytes is set to aLength. A timeout can be applied to data being written to the serial port using TTimeIntervalMicroSeconds32 aTimeOut. The Write() will terminate after the timeout if the data has not been sent. The timeout write can either use the default maximum length of the descriptor or a specific aLength for the number of bytes in the buffer.

The simplest variant of Write() is shown here:

iComm.Write(iStatus,iBuffer);

Cancelling

You can cancel a pending Read() or Write() using ReadCancel() or WriteCancel().

iComm.ReadCancel();

The TRequestStatus of the pending Read(), ReadOneOrMore() or Write() will be set to KErrCancel.

Closing your Connection

Close the serial port using RComm::Close():

iComm.Close();

Closes the serial port.