Intro

XBeeApi provides a high-level API-based mechanism for communicating with XBee devices, abstracting the specifics of the communication with the XBee itself. This page is intended to provide an overview of the API and how it may be used.

This work is based on the test setup described here

Examples

Transmit Quick Start

The following code is a minimal example of how to transmit data using XBeeApi. It assumes that the XBee is already configured to be in API mode 2 & omits all forms of error checking.

    /* The data to be transmitted */
    const uint8_t tx_data[] = { 'H', 'E', 'L', 'L', 'O' };

    /* Object to represent the XBee itself */
    XBeeDevice xbeeDevice( PTA2, PTA1, NC, NC ); // tx, rx
    /* Object to access the configuration API */
    XBeeApiCmdAtBlocking atIf( &xbeeDevice );
    /* Data frame for transmission */
    XBeeApiTxFrame frame( &xbeeDevice );

    /* Set up the 802.15.4 network type */
    xbeeSetNetworkTypeP2P( &atIf, 100, 14 );

    /* Message is going to be broadcast to all nodes */
    frame.setDestAddrBroadcast();
    /* Set up the payload for the message */
    frame.setDataPtr( tx_data, sizeof( tx_data ) );

    /* Send the message */
    xbeeDevice.sendFrame( &frame );    

Example 1

XBeeDevice xbeeDevice( PTA2, PTA1, NC, NC ); // tx, rx

Instantiate an XBee device, specifying the pins used for serial TX & RX and if applicable, flow-control pins too.

XBeeApiCmdAt atCmdIf;

Set up an "AT"-style command interface to the XBee

if( ! ( xbeeDevice.registerDecoder( &atCmdIf ) ))
{
    /* Couldn't register the decoder - that's a pretty fundamental failure */
}

Register the "AT"-style command interface as a decoder with the device. We need to do this so that responses to the AT commands can be decoded.

if( XBeeDevice::XBEEDEVICE_OK != xbeeDevice.setUpApi() )
{
    /* Couldn't get the XBee into API mode for some reason - again, pretty fundamental and likely to prevent 
       further communication */
}

Set up the XBee to use the "API" style interface. This method necessarily needs to know some details of how the XBee is set up (it should work "as-is" for an out-of-the-box XBee), and this information is currently set up in the XBeeApi config file.

atCmdIf.setChannel( 0x0d );

Request that the XBee change channel.

while(( ! atCmdIf.getChannel( &channel )) || ( channel != 0x0D )) 
{
    wait(1);
}

When the XBee has confirmed that the channel has changed, getChannel() will return the new value. Note that the snipped above doesn't deal with a variety of failure cases and would result in an infinite loop in the case that (for example) some communication issue with the XBee prevented a successful message exchange.

Structure

Base

The base class structure (i.e those implementing the raw data exchange between the mbed program and the XBee) is show below:

• XBeeDevice - Used to instantiate an object which represents the XBee itself. The class encapsulates a Serial-type object which is used to actually exchange raw data with the device.
• XBeeApiFrame - A virtual class to represent a frame to be sent to the XBee. The SendFrame() method on the XBeeDevice is used to transmit the frame to the device.
• XBeeApiFrameDecoder - A virtual class used to instantiate objects which can decode data from the XBee. XBeeApiFrameDecoder implementing classes must be registered with an XBeeDevice so that when data is received they can be notified.

XBeeDevice

This class implements the "heavy lifting" of the communication above the base serial layer - it takes care of escaping data, calculation & verification of checksums, etc.

XBeeApiFrame

This class provides a layer of abstraction between the data that needs to be sent to the XBee and how that data is represented on the serial line.

XBeeApiFrameDecoder

By allowing multiple decoders to be registered, XBeeDevice acts as a switch which allows the data received from the XBee to be sent to the most appropriate decoding point. For example, the XBeeApiCmdAt class implements this interface and is able to decode responses to "AT"-style commands used to read and write attributes of the XBee (e.g. channel, baud rate, etc). In order to implement a class which can decode wireless data packets received by the XBee, an application need only implement a class which supports the XBeeApiFrameDecoder interface and register it with the XBeeDevice. XBeeApiCmdAt will continue to receive and decode responses to "AT"-style commands while the new class can receive the wireless data packets.

Helper Classes

XBeeCmdAt

This class supports the reading and writing of attributes relating to the XBee and communication, for example the wireless channel, source address, retry count, etc. Due to the fact that the communication is asynchronous, most functions are supported by a pair of methods:

• requestXXX() - Make a request to the XBee to set or retrieve a parameter
• getXXX() - Read the data previously requested via the requestXXX() method. The method will indicate if the data is not yet available.

XBeeCmdAtBlocking

For convenience, a blocking version of XBeeCmdAt is included. This supports the same getXXX() commands as the XBeeCmdAt class, but in the case that the data is not available will block until it is.