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:

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

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

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.

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.

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