digidotcom / xbee_ansic_library

A collection of portable ANSI C code for communicating with Digi International's XBee wireless radio modules in API mode.
207 stars 118 forks source link

Digi XBee ANSI C Library

The project is a collection of portable ANSI C code for communicating with Digi International's XBee wireless radio modules in API mode. You will typically compile/link the files directly into your application, instead of compiling them into a shared/dynamic-link library. Because of this design, most of the library configuration takes place at compile time.

This source has been contributed by Digi International under the Mozilla Public License v2.0. It is a BETA quality software release, and has gone through a limited QA cycle.

It currently supports the following platforms:

It provides an API for a host platform that communicates with an XBee radio serially. Some of the features include:

Use GitHub to report bugs, request features or contribute code to this project. Please read through this document before getting started with the code.

Requirements

Look at the README.md file in the appropriate ports/ sub-directory for information on setting up the build environment.

Documentation

You can find official documentation on the GitHub page for the project. To generate local documentation to the doc/html directory, first download and install Doxygen.

Launch Doxywizard and open Doxyfile at the root directory of the driver. Go to the "Run" tab and click the "Run doxygen" button to build the HTML documentation files. The doxygen output will produce warnings for undocumented portions of the code -- that's OK and expected.

To view the documentation, open doc/html/index.html in a web browser.

XBee Firmware

Configure your XBee radio with DigiMesh, ZigBee or Smart Energy firmware in "API" mode (with an API mode firmware or by setting ATAP=1). The samples use a default baud rate of 115200. The library is written to make use of flow control, so ATD6/ATD7 needs to be set to 1. Configure the radio with ATAO set to 1 to use extended transmit and receive frames.

ZigBee Firmware

When using ZigBee and Smart Energy firmware, keep the radio set to ATAO=1. In your application, you will need to set AO to 3 at startup in order to receive and process ZDO/ZDP requests used to discover your device's endpoints and clusters. On exit, set AO back to 1 so the radio will process those requests (and Smart Energy devices can complete Key Establishment to join a network).

xbee_cmd_simple(&my_xbee, "AO", 3);

On ZigBee networks without Key Establishment, it should be safe to keep AO set to 3.

File Descriptions

Note that frame_types.md identifies headers and source files written to support each frame type.

Headers:

Source (.c) directories:

Sample Programs

See samples/README.md for descriptions.

Adding to the Library

We welcome your contributions to this library of code, but ask that you please follow these general guidelines.

Coding Style

Portability

This driver has been designed for portability to multiple platforms, from a resource-constrained 8-bit Freescale, up to a Windows PC. As such, it's important to keep the following in mind while working with the driver:

Other Options

If you find that this library doesn't meet your needs, take a look at libxbee, "a C/C++ library to aid the use of Digi XBee radios in API mode".

For a detailed list of libraries in many languages, visit Digi's XBee Examples site.

License

This software is open-source software. Copyright Digi International, 2013.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

This software includes MPL 1.1 licensed code from the Mozilla project. See include/jslong.h and src/util/jslong.c for details.