For those of you who may have gone down the XBee API path before and became confused, I'm asking you to relax now. Yes, the use of API packets can be
a little complicated, but it doesn't have to be if we keep
things simple. Simplicity is elegance, and a lot less stressful
anyway! And -- as always -- proceed slowly. I'm still
exploring XBee features, and tend to build small
experimental programs that I can borrow code from later.
We'll do that here.
The advantages of using API mode are many. In
command mode, for example, we have to send “+++” and
then wait about a second for the XBee to reply. Once in
command mode, we can ask for a value, but we can't wait
around too long or else the XBee will drop out.
If we wanted to know the XBee's 16-bit device
address, we would send “ATMY” followed by a carriage
return. This process is best for humans using a terminal.
When we're connected with a processor, though, it makes
sense to have a more direct connection like API packets.
What’s in the Packet?
The equivalent API packet for “ATMY” looks like this:
7E 00 04 08 01 4D 59 50
These bytes are sent to the XBee through a standard
serial object. Note that we're actually sending the same
number of bytes (eight), but we don't have to wait to get
into command mode or worry about dropping out. Let's
analyze the packet:
7E API Header
00 04 Bytes in Payload
08 Frame Type (AT)
01 Frame ID
4D 59 “MY”
All API packets begin with $7E. The two bytes that
follow hold the length of the payload (everything between
length and checksum). The first byte of the payload length
will always be zero because user data is limited to 100
bytes. Also note that XBee packets store values Big Endian,
so the first byte of the length is the MSB (most significant
bit). After the frame type comes a frame ID; this must be
non-zero to get a response. Next is the two-byte AT string,
followed by the checksum.
I can feel the panic already. “How am I going to build
those packets?” Good news! You don't have to. Digi
provides an application called XCTU for configuring XBee
modules, and within its tool set is a frame generator. If you
haven’t used XBees and worked with XCTU, you'll want to
give yourself an hour or so to become acquainted.
There are several great tutorials on the Internet.
SparkFun has a particularly good intro to XBees and using
XC TU. It's also a great refresher for those of us with some
Another advantage to API mode is that we can
specify the address of a device (within our channel and
PAN ID) that is to receive the message. XBee supports 64-
and 16-bit addressing; I use the latter to keep things
simple. Using 16-bit addressing, we can send a message to
an individual device or to all devices within the channel
and PAN using the address $FFFF.
In my projects, I tend only to need AT commands to
configure the radio, and TX type 1 (to 16-bit address)
commands to communicate with nodes in the system.
There is a special case that we'll discuss later where I was
able to communicate with a stand-alone XBee (i.e., no
external processor connected) with what is called a
Remote AT command.
Here's what typical transmit packets in my projects
XBee Beyond the Basics
Using XBee radios is a simple and fun way
to add wireless communications to our
projects. Nearly all of us start with
“transparent” mode. If you've never used
XBees, this mode allows us to configure
two radios to connect directly to each
other; we get a wireless link that behaves
like any other serial connection. It's quick,
it's easy, and it works really well.
Transparent mode is great for point-to-point
communications, but not so great when we
want to do point-to-multi-point; for
example, in a command-and-control
network. By using the API (application
programming interface) connection mode
— which involves specifically formatted
packets — we get a lot more flexibility.
■ BY JON MCPHALEN THE SPIN ZONE
ADVENTURES IN PROPELLER PROGRAMMING
42 November 2017