Home > Support > Knowledge Base
Knowledge Base
 
Reset Search
Search
 

 

Knowledge

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

« Go Back

Information

 
Article Number000001673
Problem Resolution

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 1Radio 2
AP = 1DL = 5000
MY = 5000MY = 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

 
7EStart delimiter
00 0ALength bytes
01API identifier
01API frame ID
50 01Destination address low
00Option byte
48 65 6C 6C 6FData packet
B8Checksum
 

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

 
7EStart delimiter
00 03Length bytes
89API identifier
01API frame ID
00Status byte
75Checksum
 

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 1Radio 2
DIP swithces 1, 5 and 6 upDIP switches 1, 5 and 6 up
AP = 1AP = 0*
DT = 5001DT = 5000
MY = 5000MY = 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

7EStart delimiter
00 0ALength bytes
01API identifier
01API frame ID
50 01Destination address low
00Option byte
48 65 6C 6C 6FData Packet
B8Checksum
 

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

 
7EStart delimiter
00 03Length bytes
89API identifier
01API frame ID
00Status byte
75Checksum
 

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 at:

XBee 802.15.4-

ftp://ftp1.digi.com/support/documentation/90000982.pdf

9XTend -

ftp://ftp1.digi.com/support/documentation/90000958_G.pdf

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
 

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255