Module Examples

The Anaren AIR-ZNP software includes over 30 software examples that can be used to learn how to operate the AIR A2530 ZigBee modules. The AIR-ZNP software runs on both the TI MSP-430 and the Stellaris LaunchPad development kits, combined with Anaren's A2530 BoosterPack Kit.

This tutorial will walk you through the various Zigbee Module (ZM) examples. This tutorial assumes that you are familiar with programming in C and have all the hardware needed.

The examples support the following environments: They will likely work with other compilers with a minimum of change. Use of intrinsics has been kept to a minimum.
 * Texas Instruments MSP430 16-bit microcontroller, using IAR Embedded Workbench running on the MSP-430 LaunchPad development kit.
 * Texas Instruments Stellaris 32-bit ARM microcontroller, using Code Composer Studio running on the Stellaris LaunchPad development kit.

TheKnown bugs and workarounds page describes any issues found with the released software. In addition, there is a Downloads page where the latest releases and beta software can be downloaded.

AIR-ZNP Software Introduction
The Zigbee Boosterpack includes a plethora of examples to help you get up and running quickly. These examples are modeled after the UNIX philosphy of making small, building blocks of code which can be easily incorporated into a larger application. The examples in this document are optimized for ease of use. As such, there is most likely a faster way to do everything, but we wanted to ensure that the examples are easy to understand. That being said, please send us any recommended improvements to [mailto:air@anaren.com air@anaren.com].

The examples are grouped into four main categories, organized for simple to complex.

A. Hardware Interface Examples
Each Module Development Board has various peripherals on it. This group of examples demonstrates how to use these peripherals. While they don't do much on their own, these examples serve as building blocks to incorporate into your program to build functionality. This includes exercising the basic hardware on the board. These were written first to test the drivers for each peripheral.
 * Button Interrupt
 * Hello World
 * I2C Test
 * Read Color Sensor
 * Read Supply Voltage
 * Read IR Temperature Sensor
 * Timer Interrupt
 * Read EEPROM

B. Module Interface Examples
These examples will demonstrate how to communicate with the Module. For more information on the code, see the HTML code documentation.

It is highly recommended that you look at the code in an IDE so that you can easily navigate through the different files. Most compilers make navigation easier by allowing you to view the definition of a method or call stack. In IAR you can view the definition of a method by right-clicking on the name of a method (for example sendMessage) and selecting "Go to Definition of sendMessage".


 * Reset Module
 * Get Version
 * Get MAC Address
 * Get Random
 * Write Nonvolatile Memory
 * Read Nonvolatile Memory
 * Write Digital IO
 * Read Digital IO
 * Measure Module Current
 * RF Tester

C. Communications Examples
These examples demonstrates how to establish communications between two or more devices. It is highly recommended that you get the previous sets of examples up and running before attempting these.

In a Zigbee network there are three types of devices: These examples show how to configure a device to be a router or end device, and send data to the coordinator. Each device type is a separate project in the IDE. You will need one development board per device. Compile and load the Coordinator onto one target board, and the router on a different development board. Be sure that you don't load both images onto the same board! The best way to keep them separate is to plug in two devices via USB, and label one with a post-it note or similar as "Coordinator" and the other as "Router". Then while developing, always load the appropriate example onto each device. You can do this in IAR in Project Options : FET Debugger and select which Debugger interface to use for the project (e.g. HID0003:COM10 the coordinator and HID0005:COM11 for the router). Be sure to keep track which is which. The COM number for a device will change even if you change the USB port for the same device, so it will be easier if you use the same port for the same device type. This is more difficult in CCS, as the debugger will grab the first board it can find.
 * Coordinator, which handles network creation
 * Router, which can forward messages from one device to another
 * End Device, which doesn't forward messages.

The first two sets of examples are designed to be basic building blocks to demonstrate how to do the most basic communications between two or more devices: Once you get those examples up and running, you might want to do a little bit of experimentation: Now that you got two devices talking to each other, try these additional sets of examples:
 * Basic Communications - AFZDO This demonstrates how to communicate between a coordinator, router, and end device using the AFZDO interface.
 * Basic Communications - Simple API This demonstrates how to communicate between a coordinator and router using the Simple API.
 * 1) With the network running, remove power from the coordinator. You will see the router report an error when it attempts to send a message since the coordinator is gone. In more complex examples we configure the Router to automatically restart, but it is handy to see this behavior so you are aware of it.
 * 2) Start the coordinator running using your compiler's debugger, and once it is communicating correctly (displaying messages received from the router), stop the processor. You'll notice something interesting - the router keeps on sending messages successfully to the coordinator without an error. That shows the strength of the Module architecture: the application processor and Zigbee network processor are separate, so one can continue even if the other device has an error. In this case, the Module will continue being a part of the Zigbee network (routing data, coordinating, etc.) even if the application processor has a problem. (Note: in production code you should use a watchdog timer to catch any unexpected hangs in application processor code)
 * 3) Mix and Match: start a AFZDO Coordinator and a Simple API router, and watch them communicate, and vice-versa.
 * 4) Sniffing: With the coordinator running, start the packet sniffer and then start the router. You can see the link establishment messages on the packet sniffer. Packet Sniffing
 * Secure Communications - this shows how to encrypt communications using Zigbee Security.
 * Fragmentation Example This demonstrates how to send large messages from a router to a coordinator, and auto reconstruction of large messages
 * Packet Error Rate Tester This demonstrates rapid communications between two nodes.

Simple API vs. AFZDO
There are two software interfaces to the Module: the Simple Application Programming Interface (aka Simple API) or the Application Framework(AF)/Zigbee Device Objects(ZDO) Interface (aka AFZDO). They are just different sets of commands to the Module; there is no difference "over the air" between messages sent from a Simple API application vs. an application that uses the AFZDO interface. The two examples are compatible; you can create a coordinator using the Simple API and a router with AFZDO and they will communicate successfully. The Simple API is less code to write, but the AFZDO has more features. Both will allow you to create networks, apply security, etc. Most of the examples use AFZDO.

D. Simple Applications Examples
This is a simple example of how to use the Module in an application. It is recommended that you familiarize yourself with the examples in order. In other words, don't jump into the Simple Applications until you have a reasonable amount of confidence with the previous examples. Please note that these examples will not compile with the code-size restricted version of IAR as they are too large.

In this group there is also the Network Explorer. This is a convenient utility that allows you to send and receive messages on a network from a command line interface. Network Explorer is the only example that is not Zigbee Device Specific; upon startup the application will prompt the user for the type of device you want to be (Coordinator, Router, or End Device).
 * Simple Applications Examples
 * Network Explorer

These examples are available as pre-built binary files. This allows you to load them onto the MSP430 LaunchPad or the Stellaris LaunchPad without requiring a compiler. For more information on how to load these into the LaunchPad, refer to:
 * Loading Binary Files into MSP430
 * Loading Binary Files into Stellaris

File Organization
The files are organized into the following directories:
 * HAL - Hardware Access Layer, containing a file for basic interfacing to the hardware. You will want to modify the file in here when changing hardware. For more information see Changing Module Hardware
 * ZM - The Module libraries, can be reused in multiple projects
 * ZM Examples - The actual examples
 * IAR - contains all the IAR workspace and project files for the examples
 * CCS - contains all the Code Composer Studio configuration files for the examples, and Stellaris includes.
 * Common - basic utilities reused throughout the projects

When using the Module in your own project I recommend adding another directory at this level containing your project-specific files. For example, if your project was named "FooBar" then the top-level directory would contain HAL, ZM, Common, and FooBar. This makes it easy to share the Module libraries across multiple projects.

You'll also notice that each IAR project has the includes defined in Project Options. These definitions ($PROJ_DIR$/something etc) are there to make the examples portable since IAR by default uses absolute paths. Otherwise when you opened the examples you would get an error if your file structure did not exactly match the author's file structure.

The Code Composer Studio example projects were based on the StellarisWare examples for the Stellaris LaunchPad.

For size of compiled examples, see Example Compile Sizes.

Additional Resources
More detailed information that applies to all examples: For more information about Zigbee or designing Zigbee networks, look at the following:
 * IAR Project Configuration
 * Module Hardware Interface
 * Error Handling
 * Performance Tuning
 * Zigbee Development Tips
 * Firmware Build
 * Daintree white papers
 * TI E2E Forums

Documentation
The examples are commented with [Doxygen] markup. This creates javadoc-style "pretty" documentation.

To see the Doxygen-generated documentation, start by opening the .../firmware/READ_ME_FIRST.html file from the AIR-ZNP software CD. The bulk of the doxygen-generated documentation is located in the .../firmware/html/ folder on the CD.

Troubleshooting
The following are a few helpful hints if you run into trouble using the examples. Remember:
 * If you've created a new project and it builds & downloads fine but looks like nothing is happening, check the project options to be sure it's not running in the simulator. Also verify that you have selected the correct processor type.
 * When in doubt, go back to the basics: run hello_world example and reset_module example to verify that the basics are working.
 * Occasionally in any compiler you might get random build errors, especially after switching between projects. Do a clean and then rebuild all.

Bugs
Refer to the page Known bugs and workarounds for any errors in the software, and how to work around them.

Incorrect Device Set
If you see the following error when building in IAR: Building configuration: Secure Comms - Coordinator - AFZDO - MDB1 Updating build tree... ...omitting other stuff... Linking Error[e16]: Segment INTVEC (size: 0x30 align: 0x1) is too long for segment definition. At least 0x10 more bytes needed. The problem occurred while processing the segment placement command "-Z(CODE)INTVEC=FFE0-FFFF", where at the moment of placement the available memory ranges were "CODE:ffe0-ffff" Reserved ranges relevant to this placement: ffe0-ffff           INTVEC Error while running Linker Then you most likely have the processor set incorrectly. Project : Options : General Options : Device.

Function Declared Implicitly
Warning[Pe223]: function "bitBangOutput" declared implicitly \\.psf\Home\Documents\svn\hardware\fw\HAL\hal_mdb1.c 184 Then you need to add the file containing that function to the path somewhere. In other words, #include that file. In this case we would add the following line of code to hal_mdb.c:
 * 1) include "../Common/bit_bang_uart.h"

IAR Code Size Restriction
The free version of IAR for MSP430 is limited to 4kB of code. If you get this error: "Fatal Error[e89]: Too much object code produced (more than 0x1000 bytes) for this package " This means that you have exceeded the 4kB limit. The size of the CODE + CONST must be less than 4kB. You can check the size by looking at the bottom of the Linker Listing (HTML file generated by the compiler, located in the Output directory). You can either trim down your application, port your application to Code Composer (which has a 16kB limit for the free version), buy a full license of IAR, or try the 30 day evaluation edition of IAR. If changing IAR version, remember to clean your project before rebuilding. Most examples but not all can be compiled and ran with the free version of IAR.

MSP430 Debugger Issues
Some of the MSP430 development boards have a built in debugger circuit. This includes the ez430 line, LaunchPad, MSP-EXP430F5529, etc. This debugger circuit can sometimes be temperamental. It is recommended to use the MSP430 JTAG instead. Here are some tips:
 * If you don't back out of everything gracefully (e.g. you forget to disconnect the debugger before unplugging the card, etc.), then quite often you have to unplug everything and start over -- i.e. turn off IAR, turn off TeraTerm, unplug the LaunchPad, then plug in the LaunchPad, start IAR, and start TeraTerm, and set TeraTerm's serial port (even though the settings are already right).
 * Due to the debugger circuit, in TeraTerm I often have to set the Serial Port to 9600,8,N,1,N one or more times -- even though it is already set to the proper values. This seems to reset the serial interface and resolves serial interface issues.

