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

Last updated: Apr 02, 2024

Filed Under

GatewaysRFRF Dev kits

Recently Viewed

No recently viewed articles

Did you find this article helpful?