Library to easily communicate with XBee modules.

Dependencies:   DigiLogger

Dependents:   WaterLogger XbeeGateway XBee_Cooker ProjetReceiver ... more

Configuring local and remote modules

Using the XBee mbed library you will be able to configure the parameters of local and remote devices as well as execute some other commands, for example, writing your configuration changes.

Information

The values set on the different parameters are not persistent through subsequent resets unless you store those changes in the device.

This types of operations are blocking. This means the methods will wait until the transmit status response is received or the default timeout is reached. See Synchronous Operations Timeout

Networking parameters

The following methods allow an easier configuration of network parameters in XBee modules.

Common

MethodDescriptionWrapped parameter
set_node_identifier(char * node_id)Sets the Node Identifier so the node is easily identified in the PAN IDNI
get_node_identifier(const char * node_id)Reads the Node Identifier. Parameter should point to a buffer with room for at least 21 bytesNI
enable_network_encryption(bool enable)Enable or disable the network encryptionEE
set_network_encryption_key(const uint8_t * const key, const uint16_t length)Sets the network Trust Center link keyKY
get_hw_versionGets Hardware versionHV
get_fw_versionGets Firmware versionVR

ZigBee

MethodDescriptionWrapped parameter
get_network_address(uint16_t * addr)Reads node current network addressMY
set_panid(uint64_t panid)Configures the module to connect to a specific PAN ID or to the first one if set to 0ID
get_configured_panid(uint64_t * panid)Reads the configured PAN ID of the module, as set by set_panid()ID
get_operating_panid(uint64_t * panid)Reads the PAN ID in which the node is operating. Useful to determine if a node has connected explicitly or because configured PAN ID is 0OP
set_channel_mask(uint16_t chmask)Configures the channel mask in which the module will scan for the PAN ID (router or end device) or start the network (coordinator). It should be set to the minimum available set of channels of all nodes in the networkSC
get_channel_mask(uint16_t * chmask)Reads the current channel maskSC
set_encryption_key(const uint8_t * const key, const uint16_t length)Sets the network encryption key.NK
set_encryption_options(const uint8_t options)Sets the network encryption options. Options can be a logic OR between XBEE_ZB_ENC_OPT_SEND_KEY_ON_JOIN and XBEE_ZB_ENC_OPT_USE_TRUST_CENTEREO

Warning

It is not recommended to configure the network key in your final application as this serial communication would not be encrypted and could be analyzed to obtain the key.

In routers, during development it might be useful to force a check that the network coordinator is present.

MethodDescription
check_for_coordinator_at_start(bool enable)Enable or disable the channel verification. See "JV" parameter in module reference manual.

802.15.4

MethodDescriptionWrapped parameter
get_network_address(uint16_t * addr)Reads node current network addressMY
set_panid(uint16_t panid)Configures the module to connect to a specific PAN IDID
get_panid(uint64_t * panid)Reads the configured PAN ID of the moduleID
set_channel(uint8_t channel)Configures the channel in which the PAN ID is operating, should be the same in all nodes in the networkCH
get_channel(uint8_t * channel)Reads the current operating channelCH
set_network_address(uint16_t addr)Sets the network address of the nodeMY

DigiMesh

MethodDescriptionWrapped parameter
set_network_id(uint16_t network_id)Configures the module to connect to a specific NETWORK IDID
get_network_id(uint64_t * network_id)Reads the configured NETWORK ID of the moduleID
set_channel(uint8_t channel)Configures the channel in which the NETWORK ID is operating, should be the same in all nodes in the networkCH
get_channel(uint8_t * channel)Reads the current operating channelCH

Get and set arbitrary parameters

If you want to get or set a parameter for which there is no custom method already in the library, you can use either of these two methods for getting and setting any AT parameter.

Getting a parameter from the local device

You can get the value of any parameter of an XBee device using the get_param() methods provided by every XBee object. There are two methods, one for generic parameters that uses a uint32_t variable to read 1, 2 and 4 bytes length parameters, and a method that takes a pointer to a uint8_t buffer of arbitrary length to get longer parameters. This later method should be used very rarely, as all the variable length parameters are get through a proper wrapper (i.e.: get_node_identifier() and get_operating_panid() methods).

XBee ClassMethodParameters
XBeeZB XBee802 XBeeDMAtCmdFrame::AtCmdResp get_param(const char * const param, uint32_t * const data)param: parameter to be obtained from the local radio.
data: pointer where the parameter value (up to 4 bytes) will be stored.
AtCmdFrame::AtCmdResp get_param(const char * const param, uint8_t * const data, uint16_t * const len)param: parameter to be obtained from the local radio.
data: pointer where the parameter value (len bytes) will be stored.
len: pointer where the number of bytes of the parameter value will be stored.

Example: Getting a parameter from the local XBee Device

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
    [...]  
     
    XBeeZB xbee = XBeeZB(RADIO_TX, RADIO_RX, RADIO_RESET, NC, NC, 9600);
    xbee.init();
    
    [...]
     
    AtCmdFrame::AtCmdResp cmdresp;
    uint32_t val;
     
    // Read parameter BD (Baud Rate: 9600 bps [3])
    cmdresp = xbee.get_param("BD", &val);
 
    // Print the value of the parameter if it was correctly read
    if (cmdresp == AtCmdFrame::AT_CMD_RESP_OK)
        printf("OK. Local BD=%d\r\n", val);
    else
        printf("FAILED with %d\r\n", (int) cmdresp);
}

Setting a parameter in the local device

To set a parameter that does not have its own setter method, you can use the set_param() methods provided by all the XBee device classes. There are two methods, one for generic parameters that uses a uint32_t variable to write 1, 2 and 4 bytes length parameters, and a method that takes a pointer to a uint8_t buffer of arbitrary length (including 0) to set longer parameters. This later method should be used very rarely, as all the variable length parameters are get through a proper wrapper (i.e.: set_node_identifier() and set_operating_panid() methods).

XBee ClassMethodParameters
XBeeZB XBee802 XBeeDMAtCmdFrame::AtCmdResp set_param(const char * const param, uint32_t data)param: parameter to be set.
data: parameter value to be set.
AtCmdFrame::AtCmdResp set_param(const char * const param, const uint8_t * data, uint16_t len)param: parameter to be set.
data: parameter value byte array (len bytes) to be set.
len: number of bytes of the parameter value.

Example: Setting a parameter in the local XBee Device

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
void main()
{
    [...]  
     
    XBeeZB xbee = XBeeZB(RADIO_TX, RADIO_RX, RADIO_RESET, NC, NC, 9600);
    xbee.init();
    
    [...]
     
    AtCmdFrame::AtCmdResp cmdresp;
    uint32_t val = 4; // Option 4 stands for 19200 bps
     
    // Set parameter BD (Baud Rate: 19200 bps [4])
    cmdresp = xbee.set_param("BD", val);
 
    // Print the value of the parameter if it was correctly read
    if (cmdresp == AtCmdFrame::AT_CMD_RESP_OK)
        printf("OK. Local BD=%d\r\n", val);
    else
        printf("FAILED with %d\r\n", (int) cmdresp);
}

Getting a parameter from the remote device

You can get a parameter from a remote device the same way you can do it with a local one. You just need to use the get_param() methods using the remote device object as an extra parameter (either RemoteXBeeZB or RemoteXBee802). There are two methods, one for generic parameters that uses a uint32_t variable to read 1, 2 and 4 bytes length parameters, and a method that takes a pointer to a uint8_t buffer of arbitrary length to get longer parameters. This later method should be used very rarely, as all the variable length parameters are get through a proper wrapper (i.e.: get_node_identifier() and get_operating_panid() methods).

XBee ClassMethodParameters
XBeeZB XBee802 XBeeDMAtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data)remote: remote device.
param: parameter to be obtained from the remote device.
data: pointer where the parameter value (up to 4 bytes) will be stored.
AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len)remote: remote device.
param: parameter to be obtained from the remote device.
data: pointer where the parameter value (len bytes) will be stored.
len: pointer where the number of bytes of the parameter value will be stored.

Example: Getting a parameter from the remote XBee Device

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
#define REMOTE_NODE_ADDR64_MSB      ((uint32_t)0x0013A200)
#define REMOTE_NODE_ADDR64_LSB      ((uint32_t)0xABCDEF00)
 
void main()
{
    [...]  
     
    XBeeZB xbee = XBeeZB(RADIO_TX, RADIO_RX, RADIO_RESET, NC, NC, 9600);
    xbee.init();   
    
    [...]
     
    const RemoteXBeeZB remote_xbee = RemoteXBeeZB(UINT64(REMOTE_NODE_ADDR64_MSB, REMOTE_NODE_ADDR64_LSB));
     
    AtCmdFrame::AtCmdResp cmdresp;
    uint32_t val;
     
    // Read parameter BD (Baud Rate: 9600 bps [3])
    cmdresp = xbee.get_param(remote_xbee, "BD", &val);
 
    // Print the value of the parameter if it was correctly read
    if (cmdresp == AtCmdFrame::AT_CMD_RESP_OK)
        printf("OK. Remote BD=%d\r\n", val);
    else
        printf("FAILED with %d\r\n", (int) cmdresp);
}

Setting a parameter in the remote device

To set a parameter in the remote device that does not have its own setter method, you can use the set_param() methods passing the remote device object as an extra parameter as shown in the following table (either RemoteXBeeZB or RemoteXBee802). There are two methods, one for generic parameters that uses a uint32_t variable to write 1, 2 and 4 bytes length parameters, and a method that takes a pointer to a uint8_t buffer of arbitrary length (including 0) to set longer parameters. This later method should be used very rarely, as all the variable length parameters are get through a proper wrapper (i.e.: set_node_identifier() and set_operating_panid() methods).

XBee ClassMethodParameters
XBeeZB XBee802 XBeeDMAtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data)remote: remote device.
param: parameter to be set.
data: parameter value (up to 4 bytes) to be set.
AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data, uint16_t len)remote: remote device.
param: parameter to be set.
data: parameter value byte array (len bytes) to be set.
len: number of bytes of the parameter value.

Example: Setting a parameter in the remote XBee Device

#include "XBeeLib.h"
  
using namespace XBeeLib;
 
#define REMOTE_NODE_ADDR64_MSB      ((uint32_t)0x0013A200)
#define REMOTE_NODE_ADDR64_LSB      ((uint32_t)0xABCDEF00)
 
void main()
{
    [...]  
     
    XBeeZB xbee = XBeeZB(RADIO_TX, RADIO_RX, RADIO_RESET, NC, NC, 9600);
    xbee.init();
    
    [...]
     
    const RemoteXBeeZB remote_xbee = RemoteXBeeZB(UINT64(REMOTE_NODE_ADDR64_MSB, REMOTE_NODE_ADDR64_LSB));
     
    AtCmdFrame::AtCmdResp cmdresp;
    uint32_t val = 4; // Option 4 stands for 19200 bps
     
    // Set parameter BD (Baud Rate: 19200 bps [4])
    cmdresp = xbee.set_param(remote_xbee, "BD", val);
 
    // Print the value of the parameter if it was correctly set
    if (cmdresp == AtCmdFrame::AT_CMD_RESP_OK)
        printf("OK. Remote BD=%d\r\n", val);
    else
        printf("FAILED with %d\r\n", (int) cmdresp);
}

Write configuration changes

To preserve node configuration between power cycles and resets they can be saved into non-volatile memory. However, this operation should not be done too often as the modules only support a limited number of write cycles.

MethodDescriptionWrapped parameter
write_config()Write current configuration into non-volatile memoryWR

Return values

Al the configuration methods return a AtCmdResp with the following meaning:

ValueMeaning
AtCmdRespOkOperation Success
AtCmdRespErrorOperation Failed
AtCmdRespInvalidCmdInvalid Command
AtCmdRespInvalidParamInvalid Parameter
AtCmdRespTxFailureTransmission Failure
AtCmdRespLenMismatchLength Mismatch
AtCmdRespInvalidAddrRemoteXBee object has an invalid address
AtCmdRespTimeoutTimeout to wait for response expired

Examples

Here is a ready to use example:

For ZigBee modules:

Import programXBeeZB_AT_Commands

ZigBee AT Commands example for mbed XBeeLib By Digi

For 802.15.4 modules:

Import programXBee802_AT_Commands

802.15.4 AT Commands example for mbed XBeeLib By Digi

For DigiMesh modules:

Import programXBeeDM_AT_Commands

DigiMesh AT Commands example for mbed XBeeLib By Digi