.\" libxbee - a C library to aid the use of Digi's Series 1 XBee modules
.\"           running in API mode (AP=2).
.\" 
.\" Copyright (C) 2009  Attie Grande (attie@attie.co.uk)
.\" 
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.TH XBEE_NEWCON 3  2009-11-01 "GNU" "Linux Programmer's Manual"
.SH NAME
xbee_newcon, xbee_purgecon, xbee_endcon
.SH SYNOPSIS
.B #include <xbee.h>
.sp
.BI "xbee_con *xbee_newcon(unsigned char " frameID ", xbee_types " type ", ...);"
.sp
.BI "void xbee_purgecon(xbee_con *" con ");"
.sp
.BI "void xbee_endcon(xbee_con *" con ");"
.ad b
.SH DESCRIPTION
The
.BR xbee_newcon ()
function will setup a new connection with the specified settings.
It takes at least 2 arguments, and potentially up to 4 depending on the
.I type.
.sp
.B NOTE:
Packets will only be collected when they match an active connection.
You must setup a connection in order to recieve packets.
.sp
The argument
.I frameID
allows similar functionality to that of TCP/IP port numbers. This is 1 
.I unsigned char
(or 8-bit integer) that identifies where the data is coming from or going to.
.s
The
.I type
specifies the type of connection you would like. The following types are avaliable:
.TP
.B xbee_localAT
communicates AT commands with the local XBee
.TP
.B xbee_txStatus
recieves transmit status information from the local XBee
.TP
.B xbee_modemStatus
recieves modem status information from the local XBee
.TP
.B xbee_16bitRemoteAT
communicates AT commands with a remote node (using 16-bit addressing)
.TP
.B xbee_64bitRemoteAT
communicates AT commands with a remote node (using 64-bit addressing)
.TP
.B xbee_16bitData
sends/recieves data through a remote node (using 16-bit addressing)
.TP
.B xbee_64bitData
sends/recieves data through a remote node (using 64-bit addressing)
.TP
.B xbee_16bitIO
sends/recieves I/O data through a remote node (using 16-bit addressing)
.TP
.B xbee_64bitIO
sends/recieves I/O data through a remote node (using 64-bit addressing)
.TP
.B xbee2_data
sends/recieves data using a Series 2 XBee (uses 64-bit addressing)
.TP
.B xbee2_txStatus
recieves transmit status information from the local Series 2 XBee
.PP
If you are using
.BR xbee_localAT ", " xbee_txStatus ", " xbee2_txStatus " or " xbee_modemStatus
then only the
.I frameID
and
.I type
arguments are required.
.sp
If you are using any 16-bit connection, you must also specify 1 right aligned integer,
containing the 16-bit address (e.g. 0x1234).
.sp
If you are using any 64-bit connection, you must also specify 2 integers containing the
64-bit address, first the high 32-bits, then the low 32-bits.
.sp
The
.BR xbee_purgecon ()
function is very basic. It removes any packets that have been collected in the buffer for the specified connection.
.sp
The
.BR xbee_endcon ()
function is used to end a connection. This will stop collecting packets for the given connection, and remove any packets from the buffer.
.SH "RETURN VALUE"
A pointer to the connection is returned. A connection can only be made once, using the same
.I type
,
.I frameID
and address (if needed). The second call using the same parameters will return the same
connection.
.sp
For information on using callback functions for packet handling please see
.BR xbee_con (3)
or
.B callback.c
in the SVN sample directory.
.SH EXAMPLE
To create a local AT connection:
.in +4n
.nf
#include <xbee.h>
xbee_con *con;
con = xbee_newcon('A', xbee_localAT);
.fi
.in
.sp
To create a 16-bit Data connection:
.in +4n
.nf
#include <xbee.h>
xbee_con *con;
con = xbee_newcon('A', xbee_16bitData, 0x1234);
.fi
.in
.sp
To create a 64-bit Data connection:
.in +4n
.nf
#include <xbee.h>
xbee_con *con;
con = xbee_newcon('A', xbee_64bitData, 0x0013A200, 0x40081826);
.fi
.in
.SH AUTHOR
Attie Grande <attie@attie.co.uk> 
.SH "SEE ALSO"
.BR libxbee (3),
.BR xbee_setup (3),
.BR xbee_getpacket (3),
.BR xbee_con (3),
.BR xbee_senddata (3)