The XBee radio modem passes through several status. 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.

These are the steps to receive modem status changes on 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:

#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.
On 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.

#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¶

Now 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();
}

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.

So 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 both XBeeZB and XBee802 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 modules.

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 modules as in a 802.15.4 network there is no that concept of being joined or not.
This method is typically used after initialization of a XBeeZB module to wait until the module joins to the network before attempting to do 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");