What is API (Application Programming Interface) Mode and how does it work?

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 802.15.4 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, use the ''''Assemble Packet'''' option 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.

Select the ''''Hex'''' option in the ''''Assemble Packet'''' window and enter the following hex formatted data in the X-CTU set for Radio 1''''s COM port:

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
 

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
 

To view the TX response packet, use the ''''Show Hex'''' option in the Terminal tab

9XTend Unicast Example:

 

For the 9XTend, the version of firmware you will need to install is 2x20 or above. If you do not have this version installed, you can download it from our web site using the X-CTU test and configuration software. If you are not sure how to update the firmware, please follow the steps listed at http://knowledge.digi.com/articles/Knowledge_Base_Article/How-to-update-firmware-in-modules/?q=How+to+update+firmware+in+modules&l=en_US&fs=Search&pn=1  to install the correct version.

Once the firmware is installed, set the radios to the following parameters:

Radio 1 Radio 2
DIP swithces 1, 5 and 6 up DIP switches 1, 5 and 6 up
AP = 1 AP = 0*
DT = 5001 DT = 5000
MY = 5000 MY = 5001

All other parameters are unchanged. Source and Destination Addresses were arbitrarily chosen.

*Radio 2''''s AP option can be set to either 0 (API off), 1(API without escaped characters) or 2 (with escaped characters). The receiving message will still be the same.

The radios are ready to communicate the "Hello" message using an API packet.

Select the X-CTU window you have selected as Radio 1 and click on the Terminal tab.

Select the ''''Hex'''' option in the ''''Assemble Packet'''' window and enter the following hex formatted data:

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
 

The 9XTend radio with the address of 5001 (Radio 2) will receive the "Hello" data packet and will be displayed in the Terminal tab of its corresponding X-CTU. The transmit response on Radio 1''''s packet will now look like:

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. The XCTU can be downloaded here:
http://www.digi.com/products/xbee-rf-solutions/xctu-software/xctu#productsupport-utilities
 
Last updated: Aug 23, 2018

Filed Under

GatewaysRFRF Dev kits

Recently Viewed

No recently viewed articles

Did you find this article helpful?