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
  • 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 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://www.digi.com/support/kbase/kbaseresultdetl.jsp?id=2110 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 at:

XBee 802.15.4-

http://ftp1.digi.com/support/documentation/90000982_B.pdf

9XTend -

http://ftp1.digi.com/support/documentation/90000958_A.pdf
Your M2M Expert®for Businessfor Developers
Contact Us
Phone
Email
Chat
Feedback
Newsletter SignupYouTubeGoogle+FacebookCopyright © 1996-2014 Digi International Inc. All rights reserved. Legal