xbee_setup.3

.\" 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_SETUP 3  2009-11-01 "GNU" "Linux Programmer's Manual"
.SH NAME
xbee_setup, xbee_setuplog, xbee_setupAPI, xbee_setuplogAPI
.SH SYNOPSIS
.B #include <xbee.h>
.sp
.BI "int xbee_setup(char *" path ", int " baudrate ");"
.sp
.BI "int xbee_setuplog(char *" path ", int " baudrate ", int " logfd ");"
.sp
.BI "int xbee_setupAPI(char *" path ", int " baudrate ", char " cmdSeq ", int " cmdTime ");"
.sp
.BI "int xbee_setuplogAPI(char *" path ", int " baudrate ", int " logfd ", char " cmdSeq ", int " cmdTime ");"
.ad b
.SH DESCRIPTION
.sp
.B A VERSION OF THIS FUNCTION MUST BE CALLED BEFORE ANY OTHER libxbee FUNCTION!
The
.BR xbee_setup ()
function will setup libxbee so that it can handle an XBee.
It takes 2 arguments.
.sp
The argument
.I path
is the path to the serial port that the XBee is connected to (e.g. /dev/ttyUSB0).
.sp
The
.I baudrate
is the baud rate that the local XBee is configured to run at. The following are avaliable:
.in +2n
.nf
.B 1200
.B 2400
.B 4800
.B 9600
.B 19200
.B 38400
.B 57600
.BR 115200 " - this is potentially unstable (read the XBee manual to find out why...)"
.fi
.in
.sp
Using
.BR xbee_setuplog ()
is exactly the same, but instead you give an open file descriptor. All log messages will be written to this file (you can use stderr or stdout if you want!). NOTE: The file descriptor is
.BR dup ()'ed
before use, so you may close it immediately. Providing a value of
.B 0
will disable the log output.
.sp
Using
.BR xbee_setupAPI ()
is exactly the same, but instead you provide the 'Command Sequence' character and the 'Guard Time' that your local XBee has been configured with.
libxbee will then place your XBee in API mode 2, and when you call
.BR xbee_end ()
it will return your XBee to its previous API mode.
.sp
Using
.BR xbee_setuplogAPI ()
is simply a combination of
.BR xbee_setuplog ()
and
.BR xbee_setupAPI ()
.SH "RETURN VALUE"
If any error occures,
.B -1
is returned. Otherwise
.B 0
is returned.
.SH EXAMPLE
To setup libxbee to use /dev/ttyUSB0 at 57600 baud:
.in +4n
.nf
#include <xbee.h>
if (xbee_setup("/dev/ttyUSB0",57600) == -1) {
  printf("Oh no...\n");
  exit(1);
}
.fi
.in
.SH NOTE
If libxbee is compiled with
.B DEBUG
defined, then the log output will ALWAYS be enabled. If no file descriptor is provided, then stderr will be used.
.SH AUTHOR
Attie Grande <attie@attie.co.uk> 
.SH "SEE ALSO"
.BR libxbee (3),
.BR xbee_newcon (3),
.BR xbee_getpacket (3),
.BR xbee_senddata (3)