|
API :
Abbreviation of application program interface, a set of
routines, protocols, and tools for building software
applications. A good API makes it easier to develop a
program by providing all the building blocks. A programmer
then puts the blocks together.
Most operating environments, such as MS-Windows, provide an
API so that programmers can write applications consistent
with the operating environment. Although APIs are designed
for programmers, they are ultimately good for users because
they guarantee that all programs using a common API will
have similar interfaces. This makes it easier for users to
learn new programs.
As the reason why API is used is to allow communictation
between teams and applications in order to allow separated
and distributed development the answer to question what
is API shall include everything that influences such
kind of development.
The API is everything that another team or
application can depend on:
- method and field signatures - communication
between applications is usally about calling functions and
passing data structures between each other. If there is a
change in the names of the methods, in their arguments or
in structure of exchanged data, the whole program often
does not even link well, nor it can run.
- files and their content - many applications
read various files and their content can influence their
behaviour. Imagine application relying on the other one to
read its configuration file and modifying its content
prior to invoking the application. If the format of the
file changes or the file is completely ignored, the
communication between those applications gets broken.
- environment variables - for example behaviour
of
cvs can be influenced by the variable
CVSEDITOR.
- protocols - opening a socket and being prepared
to interpret streams sent there, or putting or reading a
data to clipboard or during drag and drop again
establishes an API that others can depend on.
- behaviour - a bit harder to grip, but important
for the separation as well is the the dynamic behaviour.
How the program flow looks like - what is the order of
execution, what locks are being held during calls, in
which threads a call can happen, etc.
- L10N messages - because the localization to a
certain language is usually developed and distributed by
somebody other than the person that writes the code, yet
both of them have to use the same keys (
NbBundle.getMessage
("CTL_SomeKey")), there is inherently a contract
between the writer of the code and the translator - an API
of sorts.
The important thing with respect to distributed
development is to be aware of possible APIs - of possible
things other code can depend on. Only by identifying such
aspects of own application one can develop it in a way that
will not hurt cooperation with seperately developed
applications.
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.maxstream.net/support/knowledgebase/article.php?kb=103
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.
|
