Digi International Inc. / XBeeLib

Library to easily communicate with XBee modules.

Dependencies:   DigiLogger

Dependents:   WaterLogger XbeeGateway XBee_Cooker ProjetReceiver ... more

Receiving Data from other module

Table of Contents

  1. Create an XBee object
  2. Register desired receive function callback
  3. Initialize the XBee
  4. Periodically ask the XBee library to process received frames
  5. Examples

The data reception operation receives data via your local (attached) XBee device from a remote device on the network. Data is received in API frames, but the mbed XBee Library abstracts this process so you only have to manage 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 XBee 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:

ZigBee

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

802.15.4

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

DigiMesh

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
     [...]
      
     XBeeDM xbee = XBeeDM(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.
In 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 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);
     
    [...]
}

802.15.4

#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);
     
    [...]
}

Information

If the sender device does not have a 16-bit address configured, the RemoteXBee802 object created by the library will have its 16-bit address set to DR_ADDR16_UNKNOWN and its 64-bit address equal to the actual remote object's 64-bit address (SH and SL parameters).

DigiMesh

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
/** Callback function, invoked at packet reception */
static void receive_cb(const RemoteXBeeDM& 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);
     
    [...]
}

Initialize the XBee

To initialize the XBee, call 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.

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(".");
    }
     
    [...]
}

Examples

Here is a ready to use example:

For ZigBee modules:

Import programXBeeZB_Receive_Data

ZigBee Receive Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

For 802.15.4 modules:

Import programXBee802_Receive_Data

802.15.4 Receive Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

For DigiMesh modules:

Import programXBeeDM_Receive_Data

DigiMesh Receive Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

All wikipages