Library to easily communicate with XBee modules.

Dependencies:   DigiLogger

Dependents:   WaterLogger XbeeGateway XBee_Cooker ProjetReceiver ... more

Initializing modules

In order to make this API work, it is necessary to create objects that represent the different protocols supported by this library. Therefore, the first step is to know the protocol used by your XBees.

Different XBee radios use various different protocols. As of today, this library supports the following ones:

  • ZigBee
  • IEEE 802.15.4
  • DigiMesh

You can find more information about the different protocols here TODO.

Depending on how you communicate with your modules, the library categorizes them as:

  • Local XBee: a device serially connected to your micro-controller.
  • Remote XBee: a device that is not attached to your micro-controller but operates in the same radio network as the Local one.

Local XBee device

A local XBee object represents the XBee device that is plugged in to your mbed module. The following are the objects representing the available protocols supported by this library:

ClassDescription
XBeeZBZigBee protocol
XBee802802.15.4 protocol
XBeeDMDigiMesh protocol

On creation, the following parameters are needed:

  • tx: The TX pin of the UART that will send data to the XBee module.
  • rx: The RX pin of the UART that will receive data from the XBee module.

Example: Creating a ZigBee object

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
[...]
 
// Instantiate an XBeeZB object.
XBeeZB localDevice = XBeeZB(RADIO_TX, RADIO_RX);

The other parameters are optional:

  • reset: The pin to which the XBee's reset line is attached. Default value: NC.
  • rts: The RTS pin for the UART that will handle one part of hardware handshaking for the XBee module. Default value: NC.
  • cts: The CTS pin for the UART that will handle the other part of hardware handshaking for the XBee module. Default value: NC.
  • baud: The baudrate for the UART that will interface with the XBee module. Note that the module has to be already configured to this baud rate (ATBD parameter). Default value: 9600 bps.

Example: Creating an 802.15.4 object with a different baudrate optional parameter:

#include "XBee.h"
 
[...]
 
// Instantiate an XBee802 object with optional serial parameters.
XBee802 localDevice = XBee802(RADIO_TX, RADIO_RX, RADIO_RESET, NC, NC, 115200);

Information

Find more information on how to use RTS/CTS serial hardware flow control here


Right after the creation of an instance you must initialize the module so the relevant parameters are read and set internally (such as the 64-bit address and the firmware version). This call has no arguments and returns a RadioStatus indicating whether everything was configured properly or not.

Example: Initializing the local device

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
 
[...]
 
XBeeZB localDevice = XBeeZB(RADIO_TX, RADIO_RX);
 
// Initialize device. Read the relevant parameters.
RadioStatus radioStatus = localDevice.init();
if (radioStatus != Success) {
    printf("Initialization failed (are the TX/RX pins and the baudrate properly configured?)");
}
[...]

Remote XBee device

Remote XBee device objects represent remote nodes on the network. These devices are connected to some power source and the communication with them is done through the local device.

Information

When working with remote XBee devices, it is very important to understand that you cannot communicate directly with them; you need a local XBee device operating in the same network that will act as bridge between your serial port and the remote node.

Working with Remote devices is not the same as working with a local one. You can configure a remote device, handle its IO lines, and so on in the same way you do it with a local device. However, you cannot send data to other remote devices via a remote device in the way you can from the local device.

This is the list of remote XBee device classes:

ClassDescription
RemoteXBeeProtocol independent (Generic)
RemoteXBeeZBZigBee protocol
RemoteXBee802802.15.4 protocol
RemoteXBeeDMDigiMesh protocol

This is how you can instantiate a remote XBee device with this library:

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
 
[...]
 
uint64_tconst remaddr64 = UINT64(0x0013A200, 0xABCDEF00);
 
// Instantiate a remote XBee device object.
XBeeRemote remoteDevice64b = XBeeRemote(remaddr64);
 
// Instantiate a remote ZigBee device object.
RemoteXBeeZB remoteDevice64b = RemoteXBeeZB(remaddr64);
 
// Instantiate a remote 802.15.4 device object.
RemoteXBee802 remoteDevice64b = RemoteXBee802(remaddr64);

In order to work with a remote device, it is necessary to create a local device. You can use the local device to configure your remote device or work with its IO lines. Example: Working with remote devices

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
  
[...]
 
// Instantiate an XBeeZB object.
XBeeZB localDevice = XBeeZB(RADIO_TX, RADIO_RX);
 
// Initialize the local device.
RadioStatus radioStatus = localDevice.init();
 
uint64_t const address = UINT64(0x0013A200, 0xABCDEF00);
 
// Instantiate a remote XBee device object.
RemoteXBeeZB remoteDevice = RemoteXBeeZB(address);
 
// Prepare the message to be sent to the remote device.
char data[] = "Hello World!!";
const uint16_t data_len = strlen(data);
 
// Send data to the remote thevice
localDevice.send_data(remoteDevice, (const uint8_t *)data, data_len);

Another way to instantiate a ZigBee device

Remote XBee devices under ZigBee protocol can also be instantiated by providing the 16-bit address of the remote device as an additional parameter to the 64-bit address. Example: Instantiating an 802.15.4 module with a 16-bit address

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
  
[...]
 
uint64_t const remadd64 = UINT64(0x0013A200, 0xABCDEF00);
uint16_t const remadd16 = 0x1234;
 
// Instantiate a remote XBee device object using the 64-bit address and the 16-bit address (only possible for ZigBee).
RemoteXBeeZB remoteDevice16b = RemoteXBeeZB(remadd64, remadd16);

Another way to instantiate an 802.15.4 device

Remote XBee devices under 802.15.4 protocol can also be instantiated by providing the 16-bit address of the remote device. Example: Instantiating an 802.15.4 module with a 16-bit address

#include "XBeeLib.h"
  
using namespace XBeeLib;
  
[...]
 
uint16_t const remadd16 = 0x1234;
 
// Instantiate a remote XBee device object using the 16-bit address (only possible for 802.15.4).
RemoteXBee802 remoteDevice16b = RemoteXBee802(remadd16);