2. API Reference

The API Reference is a Doxygen generated documentation set which is readable via Github Pages: http://exsilium.github.io/xbee-sdk-doc/

2.1 Overview

The XBee Firmware Library is an extensive and specific API provided to facilitate the development of programmable XBee applications.

Overview of XBee interfaces and functional modules

Apart from the internal modules and interfaces, the XBee Firmware Library provides also drivers for some external devices that can be connected and managed by the XBee module:

Other references to the Firmware Library:

Types

Overview of Cross-Platform, ANSI C, XBee/ZigBee Driver

The driver is broken up into multiple layers, with well-defined interfaces between each layer.

The two parts of the driver are similar to an Ethernet NIC driver and a TCP/IP networking stack. In our case, the XBee Driver handles all serial communication with and configuration of the attached XBee device, the Wireless Personal Networking layer provides generic 802.15.4 networking support (endpoints and clusters), and the ZigBee Networking Stack layer provides support for the ZigBee networking protocols.

These layers make use of a Hardware Abstraction Layer that must be created for each hardware/compiler platform.

See the Modules section for a full outline of the API layers.

WPAN Overview

Endpoint Table

The endpoint table is a complex data structure that describes all endpoints, clusters, ZCL attributes and manufacturer-specific command handlers for a given device. The structure of the table is as follows (note that not all members of each object are listed):

Each DEVICE (wpan_dev_t) corresponds to a local, serially-connected XBee module. This DEVICE has multiple ENDPOINTs.
Each ENDPOINT (wpan_endpoint_table_entry_t) has
- An ENDPOINT ID (0 to 254), PROFILE ID, DEVICE ID and DEVICE VERSION.
- Multiple CLUSTERs. The ZDP endpoint handler currently uses a switch to handle frames for each cluster, but could be updated to let the endpoint dispatcher hand frames off to each cluster's handler.
- A HANDLER to process frames for CLUSTERs without their own HANDLER, or CLUSTERs that aren't in the table.
- A pointer to an ENDPOINT STATE (wpan_ep_state_t) structure.
Each CLUSTER (wpan_cluster_table_entry_t) has
- FLAGs indicating whether it is an input or output cluster (or both), and whether packets sent to/from the cluster require APS-layer encryption.
- A HANDLER to process frames for that cluster.
- A CONTEXT pointer that is passed to the HANDLER. For a ZCL endpoint, the CONTEXT points to an ATTRIBUTE TREE.
On ZCL endpoints, each entry in the ATTRIBUTE TREE (zcl_attribute_tree_t) has
- A manufacturer ID with ZCL_MFG_NONE (0) representing the general attributes for the cluster.
- Pointers to a list of SERVER and CLIENT cluster ATTRIBUTEs.
Each ATTRIBUTE is either a BASE ATTRIBUTE (zcl_attribute_base_t) with
- A 16-bit ID.
- FLAGS indicating whether the attribute is read-only, is a full attribute (see below), has a minimum or maximum limit and is reportable.
- A ZCL TYPE.
- A pointer to the ATTRIBUTE's VALUE.
... or a FULL ATTRIBUTE (zcl_attribute_full_t) which has
- A BASE ATTRIBUTE structure (so both BASE and FULL attributes start with the same structure elements).
- Optional MINIMUM and MAXIMUM (zcl_attribute_minmax_t) values.
- A READ function (zcl_attribute_update_fn) to refresh the ATTRIBUTE's VALUE.
- A WRITE function (zcl_attribute_write_fn) to process a ZCL Write Attributes request if the attribute requires additional processing over what the standard function, zcl_decode_attribute, does.

Endpoint Dispatching

The endpoint dispatcher searches the endpoint table to find a handler for a given frame, based on its destination endpoint and cluster ID.

ZigBee Overview

ZDO/ZDP (ZigBee Device Object/Profile) Command Processing

The ZDO endpoint handler (registered to endpoint 0) walks the endpoint table to respond to requests. It needs to know about all endpoints and their input clusters and output clusters. It walks the endpoint table but stops at the context elements. Therefore, all information required by the ZDO layer must exist outside of the context elements of the endpoint table.

ZCL (ZigBee Cluster Library) Command Processing

Consider a theoretical cluster with manufacturer-specific attributes and commands for more than one manufacturer ID. The handler registered to that cluster would check the frame type and manufacturer-specific bits and hand any GENERAL/PROFILE or MANUFACTURER-SPECIFIC commands off to the ZCL General Command Handler (zcl_general_command).

ZCL General Command Handler

This handler will see frames from the endpoint dispatcher for

Clusters that aren't in the cluster table for the endpoint (invalid clusters).
Clusters that don't have their own handler (no cluster commands).

It also receives frames from clusters with handlers for cluster-specific commands that are passing on a general or manufacturer-specific command frame.

The ZCL General Command handler finds the correct attribute list from the attribute tree (general vs. manufacturer-specific, server vs. client cluster), and then

If the frame is marked CLUSTER & MANUFACTURER-SPECIFIC, it passes the frame on to the handler for that MFG ID (stored in the attribute tree).
If it is marked CLUSTER-SPECIFIC but GENERAL, it generates an error.
If it is marked PROFILE-SPECIFIC and GENERAL, it processes the frame as a general command, using the attribute list it retreived from the tree.

Summary of ZCL handlers

ZCL General Command handler registered to the endpoint to process frames for invalid clusters or clusters without cluster-specific commands (i.e., clusters with a NULL command handler).
Cluster-specific, general command handler registered to each cluster.
Cluster-specific, manufacturer-specific command handler(s) listed in the attribute tree (stored in the cluster structure's context member) under the appropriate manufacturer ID.

2.2 Modules

Here is a list of all modules:

2.3 Data Structures

Data Structures