Library to easily communicate with XBee modules.

Dependencies:   DigiLogger

Dependents:   WaterLogger XbeeGateway XBee_Cooker ProjetReceiver ... more

Handling modem status changes

The XBee radio modem passes through several different status states. While initializing the library it will be 'Reset'; then, in a ZigBee network, it will become 'Joined' to a network and eventually 'Disassociated' from it.

The user can optionally register a function callback to get notifications of these modem status changes.

Here are the steps to receive modem status changes from your XBee device:

  1. Create an XBee object.
  2. Register the desired function callback. This function will be called by the library when a modem status change is received.
  3. Initialize the XBee.
  4. Periodically ask the XBee library to process received frames (this includes modem status frames).

Create an XBee object

Create an XBee object of the desired variant:

ZigBee

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
     [...]
      
     XBeeZB xbee = XBeeZB(RADIO_TX, RADIO_RX, RADIO_RESET);
      
     [...]
}

Register desired receive function callback

The user has to provide the desired function to be called when specific frames are received.
For every protocol, there is a single receive callback for both unicast and broadcast messages. However, depending on the XBee variant the callback function has a different prototype, as they take different RemoteXBee objects.

ZigBee

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
/** Callback function, invoked at modem status reception */
static void modem_status_cb(AtCmdFrame::ModemStatus status)
{
    log_serial->printf("\r\nModem Status: 0x%x\r\n", status);
}
 
int main()
{
    [...]
     
    /* Register callbacks */
    xbee.register_modem_status_cb(&modem_status_cb);
     
    [...]
}

Initialize the XBee

Next, initialize the XBee. That means calling to the init() method (see Initializing modules) and optionally any method required to put the device in the desired network.

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
int main()
{
    [...]
     
    xbee.init();
}

Information

The XBee library will always call the modem status callback (if registered) once after the init() method is executed, reporting the modem status state after initialization process.

Periodically ask the XBee library to process received frames

The process_rx_frames() method must be called periodically by the user so the XBee library delivers the frames to the corresponding registered callbacks.

Help

See more info on Frame Receive Process

Make sure you call this method periodically:

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
    [...]
     
    while (true) {
        xbee.process_rx_frames();
        wait_ms(100);
        printf(".");
    }
     
    [...]
}

ModemStatus enum

The modem status callback function is the same for all supported modules. It takes a 'AtCmdFrame::ModemStatus' enum as argument. Here we describe the enumeration possible values, although some of them only apply to one sort of module.

Information

XBee802 and XBeeDM modules don't have 'JoinedNW' / 'Disassociated' status.

statusDescription
HwResetHardware reset
WdResetWatchdog timer reset
JoinedNWJoined network (ZigBee routers and end devices)
DisassociatedDisassociated (ZigBee)
SyncLostSynchronization Lost
CoordRealignCoordinator realignment (ZigBee)
CoordStartedCoordinator started (ZigBee)
NwSecKeyUpdatedNetwork security key was updated (ZigBee)
NwWokeUpNwWokeUp
NwToSleepNwToSleep
VccExceededVccExceeded
ModConfChangeJoinInProgModem configuration changed while join in progress (ZigBee)

Reading the association status

There is a method to check the module's association status. The get_assoc_status() method returns an enumerated type depending on the protocol used specifying the status. It is useful for debugging network failures.

    XBeeZB::AssocStatus assoc_status = xbee.get_assoc_status();
    log_serial->printf("Association status is %02X\r\n", assoc_status);

The is_joined() method

XBeeZB modules offer a method that can be called at any moment to know whether the device is joined to a ZigBee network. This method is NOT available for XBee802 or XBeeDM modules as those networks have no concept of being joined or not, (except when doing Power Management).
This method is typically used after initialization of a XBeeZB module, to wait until the module joins to the network before attempting any remote operation:

    log_serial->printf("Waiting for device to join the network: ");
    while (!xbee.is_joined()) {
        wait_ms(1000);
        log_serial->printf(".");
    }
    log_serial->printf("OK\r\n");

Examples

Here is a ready to use example:

For ZigBee modules:

Import programXBeeZB_modem_status

ZigBee Modem Status example for mbed XBeeLib By Digi