The data reception operation receives data in your local (attached) XBee device from a remote device on the network. Data is received in API frames, but the mbed XBee Library abstracts the process so you only have to care about the data itself.
You can receive either unicast or broadcast data. Unicast data are frames that have been explicitly sent to an specific XBee, whereas broadcast data are frames that have been sent to all devices in the network.
These are the steps to receive data on your XBee device:

1. Create an XBee object.
2. Register the desired function callback. This function will be called by the library when corresponding data is received.
3. Initialize the XBee.
4. Periodically ask the XBee library to process received 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);
      
     [...]
}

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
     [...]
      
     XBee802 xbee = XBee802(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 packet reception */
static void receive_cb(const RemoteXBeeZB& remote, bool broadcast, const uint8_t *const data, uint16_t len)
{
    printf("You have a message!\r\n");
}
 
int main()
{
    [...]
     
    /* Register callbacks */
    xbee.register_receive_cb(&receive_cb);
     
    [...]
}

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
/** Callback function, invoked at packet reception */
void receive_cb(const RemoteXBee802& remote, bool broadcast, const uint8_t *const data, uint16_t len)
{
    printf("You have a message!\r\n");
}
 
int main()
{
    [...]
     
    /* Register callback */
    xbee.register_receive_cb(&receive_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(".");
    }
     
    [...]
}

Examples¶

Here you have a ready to use example on how to use Receive Data:

For ZigBee modules:¶

For 802.15.4 modules:¶