Digi International Inc. / XBeeLib

Library to easily communicate with XBee modules.

Dependencies:   DigiLogger

Dependents:   WaterLogger XbeeGateway XBee_Cooker ProjetReceiver ... more

Sending data to another module

Table of Contents

  1. Create an XBee object
  2. Initialize the XBee
  3. Send data to remote device(s)
  4. Return values
  5. Examples

The data transmission operation sends data from your local (attached) XBee device to a remote device on the network. Data is sent in API frames, but the mbed XBee Library abstracts the process so you only have to care about the node you want to send data to and the data itself.
You can send data either using a unicast or broadcast transmission. Unicast transmissions route data from one source device to one destination device, whereas broadcast transmissions are sent to all devices in the network.
These are the steps to send data to a remote XBee device:

  1. Create an XBee object.
  2. Initialize the XBee.
  3. Send data to remote device(s).

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

Initialize the XBee

Now initialize the XBee. That means calling 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();
}

Send data to remote device(s)

These type of operations can be either synchronous or asynchronous. Synchronous means the methods will wait until the transmit status response is received or the default timeout is reached. See Synchronous Operations Timeout. The 'syncr' parameter (last parameter in all methods) is optional and defaults to true.

Sending data to all devices in the network

To send a message to all the devices in the network (a broadcast message) it is enough to call the following method, common for all XBee variants:

XBee classMethodDescription
XBeeZB XBee802 XBeeDMTxStatus send_data_broadcast(const uint8_t *const data, uint16_t len, bool syncr = true);Send data to all the devices in the network. This function only takes a pointer to the data and its length

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
int main()
{
    [...]
     
    const uint8_t data[] = "Hello, XBees!";
    const uint16_t data_len = sizeof data / sizeof data[0] - 1;
    
    TxStatus txStatus = xbee.send_data_broadcast(data, data_len);
    if (txStatus != TxStatusSuccess) {
        printf("send_data_broadcast() failed with error %d\n", (int)txStatus);
    }
}

Sending data to a specific device in the network

Unicast transmissions are sent from one source device to another destination device. There are several ways to send data depending on the module protocol. The destination device could be an immediate neighbor of the source, or it could be several hops away (ZigBee and DigiMesh only).

XBee classMethodDescription
XBeeZBTxStatus send_data_to_coordinator(const uint8_t *data, uint16_t len, bool syncr = true);Send data to the coordinator only. This function only takes a pointer to the data and its length
XBeeZB XBee802 XBeeDMTxStatus send_data(RemoteXBee& remote, const uint8_t *data, uint16_t len, bool syncr = true);Send data to a RemoteXBee object. This object must have been created or retrieved through a node discovery or data reception
XBeeZB XBeeDMTxStatus send_data(RemoteXBee& remote, uint8_t source_ep, uint8_t dest_ep, uint16_t cluster_id, uint16_t profile_id, const uint8_t *data, uint16_t len, bool syncr = true);Send an explicit frame to a RemoteXBee object. This object must have been created or retrieved through a node discovery or data reception. This is an advanced method to address a remote device's specific end-points, cluster IDs and profiles. It takes parameters for the source and destination end-points, the cluster ID and such cluster's profile ID.
All other methods implicitly use Source and Destination end-points to be 0xE8, the Cluster ID to be 0x11 and the Profile ID 0xC10

XBee802

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
int main()
{
    [...]
     
    const uint8_t data[] = "Hello, XBees!";
    const uint16_t data_len = sizeof data / sizeof data[0] - 1;
    const uint16_t addr16 = 0x01;
    RemoteXBee802 remoteDevice = RemoteXBee802(addr16);
 
    TxStatus txStatus = xbee.send_data(remoteDevice, data, data_len);
    if (txStatus != TxStatusSuccess) {
        printf("send_data() failed with error %d\n", (int)txStatus);
         
        [...]
    }
     
    [...]
}

XBeeZB

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
int main()
{
    [...]
     
    const uint8_t data[] = "Hello, XBees!";
    const uint16_t data_len = sizeof data / sizeof data[0] - 1;
 
    RemoteXBeeZB remoteDevice = RemoteXBeeZB(0x0013A200AABBCCDD);
 
    TxStatus txStatus = xbee.send_data(remoteDevice, data, data_len);
    if (txStatus != TxStatusSuccess) {
        printf("send_data() failed with error %d\n", (int)txStatus);
         
        [...]
    }
     
    [...]
}

XBeeDM

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
int main()
{
    [...]
     
    const uint8_t data[] = "Hello, XBees!";
    const uint16_t data_len = sizeof data / sizeof data[0] - 1;
 
    RemoteXBeeDM remoteDevice = RemoteXBeeDM(0x0013A200AABBCCDD);
 
    TxStatus txStatus = xbee.send_data(remoteDevice, data, data_len);
    if (txStatus != TxStatusSuccess) {
        printf("send_data() failed with error %d\n", (int)txStatus);
         
        [...]
    }
     
    [...]
}

Return values

Al the sending methods return a TxStatus with the following meaning:

ValueCause
TxStatusSuccessTransmission completed successfully
TxStatusAckFail MackAcknowledge failure
TxStatusCCAFailCCA failure
TxStatusInvDestEPInvalid destination endpoint
TxStatusNwAckFailNetwork ACK failure
TxStatusNotJoinNwModule is not joined to a network
TxStatusSelfAddrSelf-addressed
TxStatusAddrNotFoundAddress not found in network
TxStatusRouteNotFoundRoute not found
TxStatusBroadSrcFail2HeardBroadcast source failed to hear a neighbor relay the message
TxStatusInvBindTableIdxInvalid binding table index
TxStatusResourceErrorResource error (lack of free buffers, timers, etc.)
TxStatusAttBroadcWithAPSAttempted broadcast with APS transmission
TxStatusAttUnicWithAPSEE0Attempted unicast with APS transmission, but EE=0
TxStatusResourceError2Resource error (lack of free buffers, timers, etc.)
TxStatusInternalErrorResource error (lack of free buffers, timers, etc.)
TxStatusPayloadTooLargeData Payload too large
TxStatusIndirectMsgUnReqIndirect message unrequested (DigiMesh P2MP)
TxStatusInvAddrRemoteXBee object has an invalid address
TxStatusTimeoutTimeout to wait for response expired

Examples

Here is a ready to use example:

For ZigBee modules:

Import programXBeeZB_Send_Data

ZigBee Send Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

For 802.15.4 modules:

Import programXBee802_Send_Data

802.15.4 Send Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

For DigiMesh modules:

Import programXBeeDM_Send_Data

DigiMesh Send Data example for mbed XBeeLib By Digi

Last commit 29 Jul 2016 by Digi International Inc.

All wikipages