API (Application Programming Interface) mode is a frame-based method for sending and receiving data to and from a radio's serial UART. The API is an alternative to the default transparent mode.
The API allows the programmer the ability to:
- Change parameters without entering command mode (XBee only)
- View RSSI and source address on a packet by packet basis (XBee only)
- Receive packet delivery confirmation on every transmitted packet
This article will cover turning a sample data packet in to an API data frame for a Unicast transmission. Even though this example will use a small text message, the example can be expanded upon to include packets up to 100 (256 bytes for XBee Zigbee (ZB)) bytes in length for the XBee or up to 2048 bytes with the 9XTend in default configuration and API enabled.
Since the 9XTend and the XBee use slightly different addressing options, two different examples for the same text message will be provided.
This example will send the ASCII string "Hello" to a radio with the destination address of 5001. Both examples will be using API mode without escaped characters (ATAP=1). Both API options within the radios became readily available to customers on firmware version 1083 for the XBee and 2020 for the 9XTend. For the ZigBee versions of the firmware, please verify you have install the API version.
XBee - 16 bit 802.15.4 Unicast Example:
Configure the radios with the following parameters:
|
Radio 1
|
Radio 2
|
|
AP = 1
|
DL = 5000
|
|
MY = 5000
|
MY = 5001
|
To compose the data packet, click on the "+" button found within the Terminal tab of the X-CTU test and configuration software.
Launch a second X-CTU screen. Verify you have selected the COM port Radio 2 is on, and click on the Terminal tab.
Going back to Radio 1 XCTU, click on the "+" button under the “Send Frames” section and click on “Create frame using “Frames Generator” tool. You can then select the Frame type 0x01 – Tx (Transmit) Request: 16-bit address and then formulate the following frame:
7E 00 0A 01 01 50 01 00 48 65 6C 6C 6F B8
|
7E
|
Start delimiter
|
|
00 0A
|
Length bytes
|
|
01
|
API identifier
|
|
01
|
API frame ID
|
|
50 01
|
Destination address low
|
|
00
|
Option byte
|
|
48 65 6C 6C 6F
|
Data packet
|
|
B8
|
Checksum
|
Once formulated, click on OK and then you can send the frame using the “Send selected frame option on the left side of the “Send Frames” section.
If the packet was successful, you will see "Hello" in the receiving modules Terminal window. You will also receive a response packet back to Radio 1 stating the packet was successful. This successful response packet will look something like this:
7E 00 03 89 01 00 75
|
7E
|
Start delimiter
|
|
00 03
|
Length bytes
|
|
89
|
API identifier
|
|
01
|
API frame ID
|
|
00
|
Status byte
|
|
75
|
Checksum
|
With this information, you can quite easily expand upon the examples provided above to include the 64 bit addressing capabilities within the XBee or send a broadcast address to all radios within range.
To find out more about the API options within either radio, please see the respective product manuals. Product manuals are located online.
The "Frames Generator" and "Frames Interpreter" under the "Tools" icon of the Digi-XCTU software utility are convenient methods for working with API frames. XCTU can be downloaded here:
http://www.digi.com/products/xbee-rf-solutions/xctu-software/xctu#productsupport-utilities