[Part 1 reviews ZigBee data transmission along with an example that demonstrates how to initiate various data request mechanisms.]
4.2 No Common C API
Something that surprises many people new to ZigBee is the fact that there is no standard C API for it. What? How can ZigBee be a standard, if there is no standard for the API?
In the ANSI C standard, strlen() computes the length of a string in characters, and developers can count on this function being available in
the C library. In the POSIX standard, the function open() opens a device or file and returns a handle, and its counterpart, close(), closes that device or file based on the handle. The calls work the same (or nearly so) regardless of the platform.
Not so with ZigBee. The only thing that the ZigBee standard requires is correct over-the-air behavior. To the ZigBee Alliance testing houses, a platform or product is a black box, to be tested by octet sequences over-the-air. This is not unique with ZigBee. The practice is actually pretty common with networking protocols: They concentrate on the over-the-air or over-the-wire protocol, and leave improvements in the API up to the vendor.
So what does this mean to you as a developer? Once you pick a ZigBee vendor and write code for that platform, at least some code must be rewritten if you decide to switch stack vendors. To minimize that effort, be sure to separate the application code that interacts directly with the ZigBee stack (and MCU for that matter) from the rest of the program logic. If you are hiring a consulting company to do the software and firmware for you, make sure to specify this as part of the requirements.
All ZigBee stack vendors provide a way to access the standard ZigBee features. And regardless of how the feature is accessed, it will generate the same data, over-the-air.
For example, the ZigBee command APSDE-DATA.request transmits data over-the-air. This command is generated with a call to the C function AF_DataRequest() in the Freescale platform and emberSendDatagram() in the Ember platform. Both functions, although they have different parameters and names, produce exactly the same set of octets over-the-air, as shown in Figure 4.6.
Figure 4.6: A ZigBee Over-the-Air Data Frame
Unfortunately, there is no standard way in ZigBee to detect, over-the-air, which brand of ZigBee is implemented on a remote node. You might be able to guess, based on how the node performs optional behavior. For example, some stack vendors rebroadcast all three times, regardless of what the neighbors do. Others rebroadcast only if the neighbors have not.
Anything ZigBee-certified is standard, and works in an interoperable way with any other ZigBee node. If you need interoperability, make sure the stack vendor you've chosen is a ZigBee Certified Platform.
In the following few sections, I'll show you an API sampling from the four "Golden Unit" vendors: Texas Instruments, Ember, Integration Associates, and Freescale. Golden Units are the official ZigBee boards which make up the ZigBee Compliant Platform test suite, and are the nodes that every certified ZigBee stack must be tested against.
Now, let me introduce you to application development on the four Golden Unit platforms.
ZigBee contains no standard C API. The API is vendor-specific.
ZigBee does specify precise over-the-air behavior for compatibility among vendors.