This is an old revision of the document!


XBEE CODE

This is a explanation of the library made for xbee (ALL CODE WRITTEN FOR ARDUINO IDE based off of avr-g++ GNU compiler)

Copyright (c) Justin Downs 12/9/08 All right reserved. 
for more info/tutorials visit
www.GRNDLAB.com
This library is free software; you can redistribute it 
and/or modify it under the terms of the GNU Lesser 
General Public License as published by the Free Software 
Foundation; either version 2.1 of the License, or 
(at your option) any later version.
This library 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 Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public 
License along with this library; if not, write to the Free Software 
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Library overview:

These libraries allow you to send and receive data using the Xbee API formating. The Xbee libraries are broken up into:

Series 1 code libraries→

xbeeSendRseries1
xbeeATseries1

Series One when imported end in “so” (for example <xbeeSRso>)

Series 2 code libraries→ xbeeSendRseries2

xbeeATseries2

Series Two when imported end in “st” (for example <xbeeSRst>

and a data parser library→ xbeeIOdataparser When imported shows as (for example <xbeeIOdataParser>)

The libraries are broken up according to their functionality and which series they are for. The series 1 and series 2 modules have different types of API formatting which require different parsing techniques.

The xbeeSendRseries(X) libraries do simple data sending and receiving, which you would use if you are sending information around a network or between two modules.

The xbeeATseries(X) libraries allow you to send and execute Specific AT commands on your local xbee (the one your microcontroller is attached to) and to remote xbees. This is what you use for forced polling of input/output lines on a xbee and to reconfigure the network from your microcontroller.

The xbeeIOdataparser library allows you to take data you have received from a IO request using the “IS” command or if you are doing a timed polling with the “IR” command. It parses just the returned data so you can use it with series 1 or 2 but be careful to originally parse the data in the right way. For instance the data packet from a “IS” request comes back as a AT command response and has to be parsed with the xbeeATseries library first while a packet sent after setting the “IR” option comes as a normal data packet and you should use the xbeeSendRseries library to read the data in originally.

Below is the overview of the functions from each class and what they do:

XBEE Libray API (function descriptions) Series 1:

The series one modules do not support multiple hop addressing and pin reading has to be done using virtual wires or utilizing the “IR” setting.

xbeeATseries 1:

This library allows you to send AT commands locally (to the xbee connected to your microcontroller).

xbeeATseries 1 functions:
xbeeATso()
//constructor
boolean sendLocalAtCommandWithOptions (char* _ATcommand, char* _AToptions, int _optionsize)
//sends AT commands to the local xbee with options
boolean sendLocalAtCommand(char* _ATcommand)
//sends AT commands to the local xbee
boolean getLocalATCommandData(int _timeOut= 500)
//waits for AT reply packet gets AT reply and fills receivedData
 
//Utility functions
//Information about the parsed input API packet.
int getPacketLength()
//returns the length of the API packet
byte getApiIdentifier()
//gets the API identifier
byte* getAutoReceivedData()
//gets the data and puts it into a array that can be accessed by the returned pointer
int getDataLength()
//returns the length of the data (in BYTES) sent
byte getchecksum()
//gives you the checksum
 
//AT SPECIFIC RETURNS
byte getframeID()
//AT reply gives you frameID
const char* getATcommand()
//AT reply returns what AT command was sent
byte getstatus()
//AT reply status 0 = OK 1 = Error 2 = Invalid Command 3 = Invalid Parameter 

XbeeATseries 1 Function Descriptions:

boolean sendLocalAtCommandWithOptions (char* _ATcommand, char* _AToptions,int _optionsize)

Used to send local AT commands with options the arguments are, in order →

a pointer to a char list that holds the AT command such as:

char myCommand[]={'D','O'};

a pointer to a char list that holds the AT options such as:

char myOption[]={0x04};

the number of bytes in the options as a int such as:

int myOptionSize=1;

Returns true with a successful sending of the data.

So all together this would send the AT command to change turn on pin 20 on the xbee and would look like this.

xbeeATso xbeeAT;
 
char myCommand[]={'D','O'};
 
char myOption[]={0x04};
 
int myOptionSize=1;
 
void loop(){
xbeeAT.sendLocalAtCommandWithOptions (myCommand, myOption,1);
 
//or you could just say
xbeeAT.sendLocalAtCommandWithOptions ("DO", myOption,1);
}
boolean sendLocalAtCommand(char* _ATcommand) 

Used to send local AT commands without options the arguments are, in order → a pointer to a char list that holds the AT command such as:

char myCommand[]={'D','L'};

Returns true with a successful sending of the data.

So all together this would send the AT command to read the low part of the destination address on the xbee and would look like this.

xbeeATso xbeeAT;
 
char myCommand[]={'D','L'};
 
void loop(){
xbeeAT.boolean sendLocalAtCommand(char* _ATcommand);
}
boolean getLocalATCommandData(int _timeOut= 500);

Used to receive and parse AT command responses the argument is (default 500 mills) → the timeout for waiting for valid data from the xbee as a int. Returns true with a successful parsing of the data.

So you would call this function after making a AT request. After you parse the reply with this function you have access to all the return information using the other utility functions and would look like this.

xbeeATso xbeeAT; char myCommand[]={'D','L'};
void loop(){
 
xbeeAT.boolean sendLocalAtCommand(myCommand);
delay(1000); // give some time to reply
xbeeAT.getLocalATCommandData(); // receive and parse the data
// then look at it
Serial.println("packetLength");
Serial.println(xbeeAT.getPacketLength(),HEX); //returns the length of the API packet
Serial.println("apiIdentifier");
Serial.println(xbeeAT.getApiIdentifier() ,HEX); //gets the API identifier
Serial.println("frameID");
Serial.println(xbbeAT.getframeID() ,HEX); //AT reply gives you frameID
Serial.println("Atcommand");
const char* ATcommand = xbeeAT.getATcommand(); //AT reply gives you frameID
for (int i= 0; i < 2; i++) {
Serial.println(ATcommand[i],HEX);
}
Serial.println("status");
Serial.println(xbeeAT.getstatus() ,HEX); //AT reply status 0 = OK 1 = Error 2 = Invalid Command 3 = Invalid Parameter
Serial.println("info");
byte* DATA= getAutoReceivedData(); //gets the data and puts it into a array that can be accessed by the returned pointer
for (int i= 0; i < (xbeeAT.getDataLength() ); i++) { //returns the length of the data (in BYTES) sent
Serial.println(DATA[i],HEX);
}
Serial.println("checksum ");
Serial.println(xbeeAT.getchecksum() ,HEX); //gives you the checksum
Serial.println("END"); } 
<code>
 
 
 
====XbeeSendRseries1 Library:====
 
 
**XbeeSendRseries1 Functions:**
 
<code C++>
xbeeSRso()
//constructor
boolean sendData64(byte* data, int _dataLength, long* _destination)
//sends data using the long address
boolean sendData16(byte* data, int _dataLength, int _localAdress)
//sends data using local address
boolean getDataAuto(int _timeOut=500)
//gets the reply data access it with getAutoReceivedData()
 
//Utility functions
//Return functions
int getPacketLength()
// length of the packet
byte getApiIdentifier()
// the api identifier
long getSendersHighAddress()
// sentfrom high address
long getSendersLowAddress()
// sentfrom low address
int getSenderslocalAdress()
// local address it was sent from
byte getRSSI ()
// RSSI signalStrength
byte getoptions()
// get the options: 1 address broadcast returned, 2 PAN broadcast
byte* getAutoReceivedData()
// the data in
int getDataLength()
// the length of incoming data
byte getchecksum()
// the checksum 

XbeeSendRseries1 Function Descriptions:

boolean sendData64(byte* data, int _dataLength, long* _destination)

Used to send data using the 64 byte address the arguments are, in order → a pointer to a byte list that holds the data such as:

char myData[]={'H','I'};

a int that tells the length of the data in bytes such as:

int dataLength=2;

and a pointer to a long list that holds the address such as:

long destination[]={0x0013a200,0x4052DB3D};

Returns true with a successful sending of the data.

So all together this would send data using the 64 byte address and would look like this.

xbeeSRso xbee;
char myData[]={'H','I'};
int dataLength 2;
long destination[]={0x0013a200,0x4052DB3D};
 
void loop(){
xbee.sendData64(myData,2,destination);
}
boolean sendData16(byte* data, int _dataLength, int _localAdress)

Used to send data using the 16 byte Local address the arguments are, in order → a pointer to a byte list that holds the data such as:

char myData[]={'H','I'};

a int that tells the length of the data in bytes such as:

int dataLength 2;

and a pointer to a long list that holds the address such as:

int destination = 200;

Returns true with a successful sending of the data.

So all together this would send data using the local address and would look like this.

xbeeSRso xbee;
char myData[]={'H','I'};
int dataLength 2;
int destination = 'YOU';
 
void loop(){
xbee.sendData64(myData,2,destination);
}
boolean getDataAuto(int _timeOut=500)

Used to receive and parse API data frame responses. Automatically allocates room in memory for the reply. The argument is (default 500 mills) → the timeout for waiting for valid data from the xbee as a int such as:

int waitingMillis 1000;

Returns true with a successful parsing of the data.

So you would call this function to listen for incoming messages. After you parse the reply with this function you have access to all the return information using the other utility functions and would look like this.

xbeeSRst xbee; void loop(){
if (Serial.avalible()>0){ // if we have data parse it
xbee.getDataAuto(); // then look at it
Serial.println("packetLength");
Serial.println(xbee.getPacketLength(),HEX); //returns the length of the API packet
Serial.println("apiIdentifier");
Serial.println(xbee.getApiIdentifier() ,HEX); //gets the API identifier
Serial.println("HighAddress ");
Serial.println(xbee.getSendersHighAddress()); // sentfrom high address,HEX);
Serial.println("LowAddress ");
Serial.println(xbee.getSendersLowAddress()); // sentfrom low address
Serial.println("localAdress ");
Serial.println(xbee.getSenderslocalAdress()); // sentfrom low address
Serial.println(" getRSSI");
Serial.println(xbee.getRSSI()); // gets the signal strength
Serial.println("status");
Serial.println(xbeeAT.getoptions() ,HEX); // get the options: 1 address broadcast returned, 2 PAN broadcast
Serial.println("info");
byte* DATA= getAutoReceivedData(); //gets the data and puts it into a array that can be accessed by the returned pointer
for (int i= 0; i < (xbeeAT.getDataLength() ); i++) { //returns the length of the data (in BYTES) sent
Serial.println(DATA[i],HEX);
}
Serial.println("checksum ");
Serial.println(xbeeAT.getchecksum() ,HEX); //gives you the checksum
Serial.println("END");
}
}
boolean getData(byte * _receivedData, int _timeOut=500)

Used to receive and parse API data frame responses. Uses a pre specified array(memory allocation) the argument are → a pointer to a byte that has enough room for all the data that will be received such as:

byte myData[30];

and the timeout for waiting for valid data from the xbee (default 500 mills) as a int such as:

int waitingMillis 1000;

Returns true with a successful parsing of the data.

So you would call this function to listen for incoming messages. After you parse the reply with this function you have access to all the return information using the other utility functions and would look like this.

xbeeSRst xbee;
byte myData[30]; void loop(){
if (Serial.avalible()>0){ // if we have data parse it
xbee.getDataAuto(myData); // then look at it
Serial.println("packetLength");
Serial.println(xbee.getPacketLength(),HEX); //returns the length of the API packet
Serial.println("apiIdentifier");
Serial.println(xbee.getApiIdentifier() ,HEX); //gets the API identifier
Serial.println("HighAddress ");
Serial.println(xbee.getSendersHighAddress()); // sentfrom high address,HEX);
Serial.println("LowAddress ");
Serial.println(xbee.getSendersLowAddress()); // sentfrom low address
Serial.println("localAdress ");
Serial.println(xbee.getSenderslocalAdress()); // sentfrom low address
Serial.println(" getRSSI");
Serial.println(xbee.getRSSI()); // gets the signal strength
Serial.println("status");
Serial.println(xbeeAT.getoptions() ,HEX); // get the options: 1 address broadcast returned, 2 PAN broadcast
Serial.println("info");
for (int i= 0; i < (xbeeAT.getDataLength() ); i++) { //returns the length of the data (in BYTES) sent
Serial.println(myData[i],HEX);
}
Serial.println("checksum ");
Serial.println(xbeeAT.getchecksum() ,HEX); //gives you the checksum
Serial.println("END");
}
}

XbeeATseries 2 Library:

This library allows you to send AT commands locally and remotely on series2 xbees.

XbeeATseries 2 functions:

xbeeATst()
//constructor
 
boolean sendAtCommand(long* _destination, char* _ATcommand, int _localAdress=0xFFFE )
//sends AT commands to the remote xbee
boolean sendAtCommandWithOptions (long* _destination, char* _ATcommand, char* _AToptions, int _optionsize, int _localAdress=0xFFFE )
//sends AT commands to the remote xbee with options
boolean getATCommandData(int _timeOut=500)
//waits for AT reply packet gets AT reply and fills receivedData
boolean sendLocalAtCommandWithOptions (char* _ATcommand, char* _AToptions, int _optionsize)
//sends AT commands to the local xbee with options
boolean sendLocalAtCommand(char* _ATcommand)
//sends AT commands to the local xbee
boolean getLocalATCommandData(int _timeOut= 500)
//waits for AT reply packet gets AT reply and fills receivedData
 
//Utility functions
//Information about the parsed input API packet.
int getPacketLength()
// length of the packet
byte getApiIdentifier()
// the api identifier
long getSendersHighAddress()
// sentfrom high address
long getSendersLowAddress()
// sentfrom low address
int getSenderslocalAdress()
// local address it was sent from
byte getOptions()
// get the options: 1 means packet was acknowledged, returned 2 broadcast
byte* getAutoReceivedData()
// the data in
int getDataLength()
// the length of incoming data
byte getchecksum()
// the checksum
//AT SPECIFIC RETURNS
byte getframeID()
// AT response gives you frameID
const char* getATcommand()
// AT response what AT
byte getstatus()
// AT response status 0 = OK 1 = Error 2 = Invalid Command 3 = Invalid Parameter

XbeeATseries 2 Function Descriptions:

boolean sendAtCommand(long* _destination, char* _ATcommand, int _localAdress=0xFFFE )

Used to send remote AT commands without options the arguments are, in order → a pointer to a long list that holds the address such as:

long destination[]={0x0013a200,0x4052DB3D};

a pointer to a char list that holds the AT command such as:

char myCommand[]={'D','L'};

a int that gives the short address if you want to use it (most of the time just leave it blank and it defaults to the 64 byte address) such as:

int _localAdress=0xDEAF

Returns true with a successful sending of the data.

So all together this would send the AT command to read the low part of the destination address on the xbee and would look like this.

xbeeATso xbeeAT;
char myCommand[]={'D','L'};
long destination[]={0x0013a200,0x4052DB3D};
void loop(){
 
xbeeAT.sendAtCommand(destination, myCommand);
}
boolean sendAtCommandWithOptions (long* _destination, char* _ATcommand, char* _AToptions,int _optionsize, int _localAdress=0xFFFE )

Used to send remote AT commands to other xbees with options the arguments are, in order → a pointer to a long list that holds the address such as:

long destination[]={0x0013a200,0x4052DB3D};

a pointer to a char list that holds the AT command such as:

char myCommand[]={'D','O'}

a pointer to a char list that holds the AT options such as:

char myOption[]={0x04};

the number of bytes in the options as a int such as:

int myOptionSize=1;

and a int that gives the short address if you want to use it (most of the time just leave it blank and it defaults to the 64 byte address) such as:

int _localAdress=0xDEAF

Returns true with a successful sending of the data.

So all together this would send the AT command remotely to turn on pin 20 on the xbee and would look like this:

xbeeATst xbeeAT;
char myCommand[]={'D','O'};
char myOption[]={0x04};
int myOptionSize 1;
long destination[]={0x0013a200,0x4052DB3D}; void loop(){
 
xbeeAT.sendAtCommandWithOptions (destination, myCommand, myOption,1);
//or you could just say
xbeeAT.sendAtCommandWithOptions (destination,"DO", myOption,1);
}
boolean getLocalATCommandData(int _timeOut= 500)

Used to receive and parse AT command responses the argument is (default 500 mills) → the timeout for waiting for valid data from the xbee as a int such as:

int waitingMillis 1000;

Returns true with a successful parsing of the data.

So you would call this function after making a AT request. After you parse the reply with this function you have access to all the return information using the other utility functions and would look like this.

xbeeATst xbeeAT; char myCommand[]={'D','L'};
long destination[]={0x0013a200,0x4052DB3D};
void loop(){
 
xbeeAT.sendAtCommand(destination, myCommand);
delay(1000); // give some time to reply
xbeeAT.getLocalATCommandData(); // receive and parse the data
 
// then look at it
Serial.println("packetLength");
Serial.println(xbeeAT.getPacketLength(),HEX); //returns the length of the API packet
Serial.println("apiIdentifier");
Serial.println(xbeeAT.getApiIdentifier() ,HEX); //gets the API identifier
Serial.println("frameID");
Serial.println(xbbeAT.getframeID() ,HEX); //AT reply gives you frameID
 
Serial.println("localAddress");
Serial.println(xbeeAT.getSenderslocalAdress(),HEX);
Serial.println("Address");
Serial.println(xbeeAT.getSendersHighAddress(),HEX);
Serial.println(xbeeAT.getSendersLowAddress(),HEX);
 
Serial.println("Atcommand");
const char* ATcommand =xbeeAT.getATcommand(); //AT reply gives you frameID
for (int i= 0; i < 2; i++) {
Serial.println(ATcommand[i],HEX);
}
Serial.println("status");
Serial.println(xbeeAT.getstatus() ,HEX); //AT reply status 0 = OK 1 = Error 2 = Invalid Command 3 = Invalid Parameter
Serial.println("info");
byte* DATA= getAutoReceivedData(); //gets the data and puts it into a array that can be accessed by the returned pointer
for (int i= 0; i < (xbeeAT.getDataLength() ); i++) { //returns the length of the data (in BYTES) sent
Serial.println(DATA[i],HEX);
}
Serial.println("checksum ");
Serial.println(xbeeAT.getchecksum() ,HEX); //gives you the checksum
Serial.println("END");
 
}

XbeeIOdataparser Library:

This library allows you to parse received IO data so you can access the digital and analog pin values. You can use it in conjunction with any of the data received in the other libraries.

xbeeIOdataparser Functions:
xbeeIOdataParser()
//constructor
void getSensorReadings (byte* _data)
//Takes received data and parses into below vars.
 
//Return stuff
int gethowManyAna()
//gives number of analog channels ( if !0 then read with-> getanaValues())
int gethowManyDigital()
//gives number of digital channels ( if !0 then read with-> getDigitals())
const boolean* getDigitals()
//bitfeild of digital channels D0 is lowest bit
const long* getanaValues()
//bit field of analog channels ANA0 is lowest bit

XbeeIOdataparser Function Descriptions:

void getSensorReadings (byte* _data)

Used to parse received IO data the argument is → the received data as a pointer to byte such as:

byte * myData;

So you would call this function after calling one of the getData functions and pass it in the return value from that function. After you parse the reply with this function you have access to all the return information using the other utility functions and would look like this.

xbeeSRst xbee; // for receiving data
xbeeIOdataParser parser; // used to parse data
byte * myData;
void loop(){
 
if (Serial.avalible()>0){ // if we have data parse it byte * myData = xbee.getDataAuto;
parser.getSensorReadings(myData);
 
//or simply
parser.getSensorReadings(xbee.getDataAuto);
}
}

Once you have the data you can use the utility functions to retrieve the info.

DIGITAL FUNCTIONS:

int gethowManyDigital()

used to give the number of digital channels.

const boolean* getDigitals()

bitfeild of digital channels D0 is lowest bit used to give the values of the digital channels,

They can be used together to check then retrieve the values like this→

read by saying:

if (parser.gethowManyDigital){
boolean *digitalsChannel = parser.getDigitals();
boolean myReading = parser.digitalsChannel[0]; //would read DIO0
}
2 Digital Channel Mask
‚bit 0 = AD0/DIO0
‚bit 1 = AD1/DIO1
‚bit 2 = AD2/DIO2
‚bit 3 = AD3/DIO3
‚bit 4 = DIO4
‚bit 5 = ASSOC/DIO5
‚bit 6 = RTS/DIO6
‚bit 7 = CTS/GPIO7
‚bit 8 = N/A
‚bit 9 = N/A
‚bit 10 = RSSI/DIO10
‚bit 11 = PWM/DIO11
‚bit 12 = CD/DIO12

ANALOG FUNCTIONS:

int gethowManyAna()

used to give the number of analog channels.

const long* getanaValues()

bitfeild of analog channels ANA0 is lowest bit used to give the values of the analog channels,

They can be used together to check then retrieve the values like this→

read by saying:

if (parser.gethowManyAna()){
long *analo gChannel= parser.getanaValues();
long myReading = parser.analogChannel[0] //would get first enabled analog channel
}
1 Analog Channel Mask
‚bit 0 = AD0/DIO0
‚bit 1 = AD1/DIO1
‚bit 2 = AD2/DIO2
‚bit 3 = AD3/DIO3
‚bit 7 = Supply Voltage

Analog samples are returned as 10-bit values. The analog reading is scaled such that 0x0000 represents 0V, and 0x3FF = 1.2V. (The analog inputs on the module cannot read more than 1.2V.) Analog samples are returned in order starting with AIN0 and finishing with AIN3, and the supply voltage. Only enabled analog input channels return data as shown in the figure below. To convert the A/D reading to mV, do the following:

AD(mV) = (A/D reading * 1200mV) / 1024
Navigation
Print/export
Toolbox