btConnect (Function)

This function makes a connection to another Bluetooth device. To connect to a device, use the device number obtained from btSearch or specify the address of the device directly. Up to four connections can be handled simultaneously, which allows connections to both printers, headsets, etc. at the same time. However, only one audio connection is supported, so only one headset or other audio device may be connected at any given time.

The function returns a connection ID, which is the connection handle that is used when the connections are accessed. The ID is used in many cases - for example when transmitting data or when the connection must be disconnected. The ID is always the first available connection slot, and when an ID is disconnected, the slot will be available for a new connection.

When btConnects returns with the connection ID, the connection is not established yet - this is done asynchronously by the firmware. This means that several connections may be set up without waiting for the first connection to be established. The connections will be processed according to the assigned connection ID number. Use the btConnection function block to retrieve information about the connection. It will indicate when any changes occur to a connection - that could be connection establishment, disconnections, etc.

To connect to a headset, the headset parameter must be set to TRUE. Consult the user manual of the headset to determine the PIN. A headset connection uses two connections slots; one for control and one for audio. Please see btHsOpen for further information about using a headset.

The PIN input parameter is the PIN defined by the device to connect to. The Bluetooth module can only handle one PIN at a time, though. The btSetPin is used for incoming connections through btListen, and outgoing connection PINs are defined when a connection is initiated with btConnect. When a connection (through btConnect) is done with being processed, the Bluetooth module PIN will return to the PIN defined by btSetPin (if btListen is not used, this is irrelevant), or if more than one outgoing connection is pending, the module will initiate the next connection with the PIN associated for that connection.

When a connection to a device is established, the Bluetooth smart antenna stores the pairing info (address, passkey, etc.) which allows for a lost connection to be reestablished without user interaction.

The Bluetooth smart antenna supports up to 16 simultaneous pairings, and when 16 devices have been paired, no new pairings will be stored.

Input:

device : INT

The device number found with btSearch (either use device or address - not both).

address : STRING

The device address.

Pin : STRING

The PIN of the device to connect to. Maximum 16 characters.

Headset : BOOL

Set TRUE if connection is a headset.

Returns: SINT

The connection ID

Declaration:

FUNCTION btConnect : SINT;
VAR_INPUT
  address : STRING := "";
  device : INT;
  Pin     : STRING := "";
  Headset : BOOL;
END_VAR;

Example:

INCLUDE rtcu.inc
 
PROGRAM test;
VAR
  ConID_out   : SINT;
  ConID_in     : SINT;
  buffer       : ARRAY[1..127] OF SINT;
  RXbuffer_out : ARRAY[1..127] OF SINT;
  RXbuffer_in  : ARRAY[1..127] OF SINT;
  btRX_out     : btReceiveData;
  btRX_in      : btReceiveData;
  btCon_out   : btConnection;
  btCon_in   : btConnection;
END_VAR;
 
// Open the Bluetooth library
btOpen(name := "RTCU MX2");
 
// Set the Pin for incoming connections
btSetPin(pin := "1234");
 
// Initiate the outgoing connection
ConID_out:=btConnect(address:="00:e0:98:ae:17:23",pin:="0000");
DebugFmt(message:="Outgoing Connection ID =\1", v1:=ConID_out);
 
// Initiate the incoming connection
ConID_in:=btListen();
DebugFmt(message:="Incoming Connection ID =\1", v1:=ConID_in);
 
// setup the receive and connection function blocks
btRX_out.Data:=ADDR(RXbuffer_out);
btRX_out.MaxSize:=SIZEOF(RXbuffer_out);
btRX_out.id:=ConID_out;
btCon_out.id:=ConID_out;
 
// setup the receive and connection function blocks
btRX_in.Data:=ADDR(RXbuffer_in);
btRX_in.MaxSize:=SIZEOF(RXbuffer_in);
btRX_in.id:=ConID_in;
btCon_in.id:=ConID_in;
 
BEGIN
btCon_out();
btCon_in();
btRX_out();
btRX_in();
 
IF btCon_out.changed THEN
  DebugMsg(message:="Connection info changed:");
  DebugFmt(message:="    Connected=\1",v1:=INT(btCon_out.connected));
  DebugMsg(message:="    Address="+btCon_out.Address);
  DebugFmt(message:="    Error=\1", v1:=btCon_out.Errorcode);
END_IF;
 
IF btCon_in.changed THEN
  DebugMsg(message:="Connection info changed:");
  DebugFmt(message:="    Connected=\1",v1:=INT(btCon_in.connected));
  DebugMsg(message:="    Address="+btCon_in.Address);
  DebugFmt(message:="    Error=\1", v1:=btCon_in.Errorcode);
END_IF;
 
IF btRX_out.ready THEN
  DebugMsg(message:="Data Received from outgoing connection");
END_IF;
 
IF btRX_in.ready THEN
  DebugMsg(message:="Data Received from incoming connection");
END_IF;
 
  ...
 
END;
 
END_PROGRAM;