What is an “API-formatted packet”?

Question

Arduino.cc recommends this page as an introduction to XBee radios.

Physical Computing at ITP | Tutorials / Xbee Basics

You generally choose to work in either API mode and AT mode and can't use both at the same time. However the exception is that even radios running in AT mode will still produce API-formatted packets when they receive I/O information from other radios set up as standalone sensors.

It is not very clear to me what they mean by the alternative to AT mode "API mode". What is that?

I know what a packet is and I know how different protocols have different packet formats, but what is meant by "API-formatted packet"?

Answer 1

API mode frames the data in a specific format. Each frame has bytes specifically assigned as the header/data/checksum/etc. In order to use this mode you will need to parse these frames.

From a feature point of view, API mode generally allows you to do more with the module. You can access networking capabilities and IO that may not be available in transparent mode. This is similar to some GPS receivers that have a standard NMEA output, and an additional manufacturer-specific (API) output.

This product manual explains it further (pages 12 and 56-62 specifically).

I would probably stick with the AT commands unless your application requires you to use the API, since you will have to write more code to handle the API mode and it isn't as portable.

Answer 2

The XBee ‘AT mode’ is made to look like a traditional smart modem's way of operation: after connection, you transmit/receive data one byte at a time. To control the modem, you use an out-of-band method, where you escape transmit/receive mode (often using the standard <pause>+++<pause> sequence), send commands, and optionally re-enter transmit/receive mode.

In API mode, commands and data travel to the X-Bee in-band packet by packet (not byte by byte). Your microcontroller is responsible for formatting each packet of command/data, providing the correct values for payload lengths, checksums etc (I don't recall the specifics at the moment, it's been a while). It's more work, but as Tim mentioned, it allows you to do much more with the X-Bee.

What the manual means in this context is that even though you're in Hayes-emulating mode, there are cases where you may get a burst of bytes that are actually an API mode packet. In essence, if this happens (and if you need this data), you'll need to include the code to decode these packets. This is what got me using API mode in the first place: it looks more complex, but is actually simpler, especially if you're doing broadcasts (in the networking sense) etc.