6. Using the ZigBee Features

RabbitCore RCM4500W
User's Manual

6. Using the ZigBee Features

6.1 Introduction to the ZigBee Protocol

The ZigBee 1.0 specification was ratified on December 14, 2004, and covers high-level communication protocols for small, low-power digital modems based on the IEEE 802.15.4 standard for wireless personal area networks (WPANs). The RCM4510W ZigBee modem operates in the 2.4 GHz industrial, scientific, and medical (ISM) radio band in most jurisdictions worldwide.

The ZigBee protocol is ideal for embedded-system applications that are characterized by low data rates and low power consumption. A network of devices using the ZigBee protocol works via a self-organizing mesh network that can be used for industrial control, embedded sensors, data collection, smoke and intruder warning, and building automation. The power consumption of the individual device could be met for a year or longer using the originally installed battery.

A ZigBee device can be set up in one of three ways.

As a coordinator: The coordinator serves as the root of the network tree. Each network can only have one coordinator. The coordinator stores information about the network and provides the repository for security keys.

As a router. Routers pass data from other devices.

As an end device. End devices contain just enough functionality to talk to their parent node (either the coordinator or a router), and cannot relay data from other devices.

The ZigBee modem included with the RCM4510W presently supports using the RCM4510W RabbitCore module in a mesh network. RCM4510W modules are loaded with firmware at the factory to serve as routers or end devices; coordinator firmware is included in the Dynamic C installation along with a sample program to allow you to download the coordinator firmware.

The firmware used with the ZigBee modems on the RCM4510W modules is based on the API command set.

Figure 12.

Mesh Network

An Introduction to ZigBee provides background information on the ZigBee protocol, and is available on the CD and on our Web site.

6.2 ZigBee Sample Programs

In order to run the sample programs discussed in this chapter and elsewhere in this manual,

Your module must be plugged into the Prototyping Board as described in Chapter 2, "Getting Started."

Dynamic C must be installed and running on your PC.

The programming cable must connect the programming header on the module to your PC.

Power must be applied to the module through the Prototyping Board.

The Digi® XBee USB used as the ZigBee coordinator must be connected to an available USB port on your PC if you are exercising the ZigBee protocol, or you need a second RCM4510W module if so instructed.

Refer to Chapter 2, "Getting Started," if you need further information on these steps.

To run a sample program, open it with the File menu (if it is not still open), then compile and run it by pressing F9.

Each sample program has comments that describe the purpose and function of the program. Follow the instructions at the beginning of the sample program.

The sample programs in the Dynamic C SAMPLES\RCM4500W and SAMPLES\ZigBee folders illustrate the use of the ZigBee function calls.

6.2.1 Setting up Sample Programs

The sample programs are set up so that the RCM4510W module you are using is a ZigBee end device, router, or coordinator. Uncomment the line corresponding to the role the RCM4510W will have once it is running the sample program. The default in the sample programs is for the RCM4510W module to be an end device.
//#define ZIGBEE_COORDINATOR
//#define ZIGBEE_ROUTER
#define ZIGBEE_ENDDEV
There are several macros that may be changed to facilitate your setup. The macros can be included as part of the program code, or they may be put into the Program Options "Defines" on the "Defines" tab in the Options > Program Options menu.
Channel mask — defaults to 0x1FFE, i.e., all 16 possible channels via the macro in the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_API.LIB library.
NOTE Remember that the firmware loaded to the ZigBee modem is different depending on whether the RCM4510 W is an end device/router (default) or a coordinator. See Appendix D, "Additional Configuration Instructions," for information on how to download firmware to the RCM4510W module to set it up as a coordinator or to resume its original configuration as an end device/router..
#define DEFAULT_CHANNELS ZB_DEFAULT_CHANNELS
PAN ID — the network ID. Defaults to 0x0234 via the macro in the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_API.LIB library. Change the PAN ID if you are developing simultaneously with more than one ZigBee coordinator.
#define DEFAULT_PANID 0x0234
Node ID — the ID of your particular node via the macro in the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_API.LIB library. Each node should have a unique identifier.
#define NODEID_STR "RabbitZigBee"
Define a function that returns a node ID as a static string, and #define ZB_CONSTRUCT_NODE_ID to the name of the function.
#define ZB_CONSTRUCT_NODE_ID myNodeID
Uncomment the following line from the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_API.LIB library for more output information about tick execution times.
#define ZB_VERBOSE
Define the general message handler for messages that do not have endpoints or other addressing means specified. The general message handler callback function prototype must be as follows.
int functionName (char *data);
Perform a function lookup (<Ctrl-H>) on ZB_GENERAL_MESSAGE_HANDLER for more information.
#define ZB_GENERAL_MESSAGE_HANDLER myMsgHandler
This sample program from the Dynamic C SAMPLES\RCM4500W folder exercises the ZigBee modem on the RCM4510W.

API_TEST.C—This sample program demonstrates the capabilities of the RCM4510W RabbitCore module with a ZigBee modem. To run this sample program, you will need either the Digi® XBee USB as a ZigBee coordinator (included with the RCM4510W Development Kit), or you will need at least one other RCM4510W running as a coordinator.

The Dynamic C STDIO window will open to display a menu to access the RCM4510W features. The "Radio status change" line at the bottom indicates whether the RCM4510W module is joined or unjoined to a ZigBee network.

Each menu command exercises certain ZigBee modem functionality as shown below.

r — Radio Module Functions
A — Read ZigBee modem analog input (0–3)
D — Set/Read ZigBee modem digital I/O (0–9)
R — Reset ZigBee modem
c — Command mnemonic
z — Put this RCM4510W to sleep
ESC — Return to Main Menu

t — Radio Transmit Functions
e — Send string via string endpoint
p — Start/stop pinging another node
s — Send a string to another node
ESC — Return to Main Menu

l — List Discovered Nodes
Lists ZigBee device nodes discovered

The command function (c) is used to send AT commands to the modem such as CH (channel) or VR (version) to display the ZigBee channel number or the firmware version in the Dynamic C STDIO window.

The remaining ZigBee sample programs in the Dynamic C SAMPLES\ZigBee folder illustrate the use of the ZigBee function calls.

AT_INTERACTIVE.C—This sample program shows how to use AT commands associated with the ZigBee modem.

The program will print out a list of AT commands in the Dynamic C STDIO window. You may type in either "ATxx" or just the "xx" part of the command.

· Use just the AT command to read any of the values.

· Use [AT]xx yyyy zz (where the y is a decimal value and z is the number of bytes that are needed to tramsit y to the ZigBee modem) to set any of the "set or read" values. (Note that this works for NI, the node identifier, as long as you enter a decimal value representing a two-character string.)

· Type "menu" to redisplay the menu of commands.

· Press F4 to exit and close the STDIO window.

AT_RUNONCE.C—This sample program uses many of the most important and useful AT commands. Several commands can either set a parameter or read it. This sample program simply reads the parameters and displays the results.

Compile and run this sample program. The program will display the results in the Dynamic C STDIO window.

ENDPOINT.C—This sample program shows how to set up and use endpoints with two RCM4510W modules. It assumes that both RCM4510W modules are set up as end devices and have the same PAN ID. You also need a third device (either the Digi® XBee USB or another RCM4510W) to serve as the coordinator.

Compile and run the sample program on both RCM4510W modules. Leave the programming cable connected to the second RCM4510W module's programming port (header J2). You will use the Dynamic C STDIO window with this RCM4510W module.

Connect the 10-pin-to-DB9 serial cable to header J4 on the first Prototyping Board with the RCM4510W module, and connect the other end to an unused serial port on your PC. Open a serial terminal emulator such as TeraTerm or Hyperterminal to connect to the serial port at 115200 baud.

The terminal emulator will be used to send messages via the second RCM4510W, and both RCM4510W modules will produce output.

Reset the first RCM4510W module connected via TeraTerm, and after it initializes it will send messages to the second RCM4510W module, also producing output from both RCM4510W modules. Do not reset the RCM4510W module connected via the programming cable as this will cause a target-communication failure. If you want to reset this RCM4510W module, try using the key sequence <ctrl-Q> <ctrl-F2> F9.

GENERALMESSAGEHANDLER.C—This sample program demonstrates the use of the general message handler with two RCM4510W modules. It assumes that both RCM4510W modules are set up as end devices and have the same PAN ID.You also need a third device (either the Digi® XBee USB or another RCM4510W) to serve as the coordinator.

Compile and run the sample program on both RCM4510W modules. Leave the programming cable connected to the second RCM4510W module's programming port (header J2). You will use the Dynamic C STDIO window with this RCM4510W module.

Connect the 10-pin-to-DB9 serial cable to header J4 on the first Prototyping Board with the RCM4510W module, and connect the other end to an unused serial port on your PC. Open a serial terminal emulator such as TeraTerm or Hyperterminal to connect to the serial port at 115200 baud.

The terminal emulator will be used to send messages via the second RCM4510W, and both RCM4510W modules will produce output.

Reset the first RCM4510W module connected via TeraTerm, and after it initializes it will send messages to the second RCM4510W module, also producing output from both RCM4510W modules. Do not reset the RCM4510W module connected via the programming cable as this will cause a target-communication failure. If you want to reset this RCM4510W module, try using the key sequence <ctrl-Q> <ctrl-F2> F9.

MSG_QUEUE.C—This sample program shows how the internal message-queueing mechanism works. The RCM4510W end device will receive messages from from the Digi® XBee USB ZigBee coordinator. The messages will be sent to the RCM4510W using the ZB_Demo1.exe ZigBee utility, which must be running as explained in Steps 3–6 of Section 2.3.2.

Compile and run this sample program on the RCM4510W RabbitCore module, then follow the messages that are displayed in the Dynamic C STDIO window.

If you encounter problems, check that the Digi® XBee USB is configured with the correct network parameters using MaxStream's X-CTU utility. See Appendix D.2 for instructions on how to set up and use this utility. Check the NI parameter for the Digi® XBee USB to which messages will be sent. This sample program sends messages to DIGI-ZIGBEE-USB as set up by the following #define line in the sample program.
#define WHO "DIGI-ZIGBEE-USB"
SEND_MSG.C—This sample program shows how to send a message from the RCM4510W module to the ZigBee coordinator or to another end device. The ZigBee Utility ZB_Demo1.exe must be running as explained in Steps 3–6 of Section 2.3.2 if you are using the Digi® XBee USB. The ZigBee utility is ready once you clicked "Select Device" after selecting the device displayed in the "Selected Device" area of the Command Window.

Compile and run the sample program on the RCM4510W module. After compiling the program, the Dynamic C STDIO window will open to display the node associated with the ZigBee coordinator. You will be prompted to enter a message and press a key to send the packet. You can see the packet in the Command Window of the the ZigBee utility.

SLEEPMODE.C—This sample program shows how to place the RCM4510W module in the "sleep" mode where most power is removed from the RCM4510W module. Power is restored once a message is received or after a specified time interval. This sample program demonstrates waking after a specified time interval.

Compile and run the sample program on the RCM4510W module. Once the sample program is running, remove the programming cable from the RCM4510 module and connect the 10-pin-to-DB9 serial cable to header J4 on the Prototyping Board; connect the other end of the serial cable to an unused serial port on your PC. Open a serial terminal emulator such as TeraTerm or Hyperterminal to connect to the serial port at 115200 baud.

Press the reset button on the Prototyping Board. After some initialization (joining the network, node discovery), you will be prompted to enter a "sleep" time in milliseconds, and then to press any key to actually call the zb_Rabbit_poweroff() function. There will be a delay of a few seconds before the RCM4510W module powers off. When the RCM4510W module powers back up, it will run the code from the beginning.

NOTE This sample program does not demonstrate the saving state. State information may be saved in battery-backed RAM the RCM4510W module is placed in the sleep mode.

SLEEPMODE2.C—This sample program shows how to place the RCM4510W module in the "sleep" mode where most power is removed from the RCM4510W module. Power is restored once a message is received or after a specified time interval. This sample program demonstrates waking after a specified time interval.

Compile and run the sample program on the RCM4510W module. Once the sample program is running, remove the programming cable from the RCM4510 module and connect the 10-pin-to-DB9 serial cable to header J4 on the Prototyping Board; connect the other end of the serial cable to an unused serial port on your PC. Open a serial terminal emulator such as TeraTerm or Hyperterminal to connect to the serial port at 115200 baud.

Press the reset button on the Prototyping Board. After some initialization (joining the network, node discovery), you will be prompted to enter a "sleep" time in milliseconds, and then to press any key to actually call the zb_Rabbit_poweroff() function. There will be a delay of a few seconds before the RCM4510W module powers off. When the RCM4510W module powers back up, it will run the code from the beginning.

NOTE This sample program does not demonstrate the saving state. State information may be saved in battery-backed RAM the RCM4510W module is placed in the sleep mode.

UCOS_SEND_MSG.C—This sample program shows how to send a message from the RCM4510W module to the ZigBee coordinator. This sample program is similar to SEND_MSG.C, but it demonstrates the use of µCOS-II.

The ZigBee Utility ZB_Demo1.exe must be running as explained in Steps 3–6 of Section 2.3.2 if you are using the Digi® XBee USB. The ZigBee utility is ready once you clicked "Select Device" after selecting the device displayed in the "Selected Device" area of the Command Window.

Compile and run the sample program on the RCM4510W module. After compiling the program, the Dynamic C STDIO window will open to display the node associated with the ZigBee coordinator. You will be prompted to enter a message and press a key to send the packet. You can see the packet in the Command Window of the the ZigBee utility.

If you encounter problems, check that the Digi® XBee USB is configured with the correct network parameters using MaxStream's X-CTU utility. See Appendix D.2 for instructions on how to set up and use this utility. Check the NI parameter for the Digi® XBee USB to which messages will be sent. This sample program sends messages to DIGI-ZIGBEE-USB as set up by the following #define line in the sample program.
#define WHO "DIGI-ZIGBEE-USB"
6.3 Using the Sleep Mode

The RCM4510W RabbitCore module has two components that are involved when the sleep mode i9s invoked — the ZigBee modem and the Rabbit 4000 microprocessor.

End devices, unlike coordinators and routers, can enter a low-power sleep mode. This sleep mode is controlled by the ZigBee modem, and fully powers down the Rabbit 4000 microprocessor for significant savings in power use.

The sleep mode can only be initiated while the RCM4510W is in the Run Mode (see Section 4.3.1 for more information on the Program Mode and the Run Mode).

Once the ZigBee modem on the RCM4510W is operating in the sleep mode, it will periodically wake up and poll its parent router or coordinator to determine whether there is an incoming message. If one is found, the message will be received and the Rabbit 4000 microprocessor will be restarted. Otherwise the ZigBee modem will return to sleep. Depending on how the sleep mode is configured, the ZigBee modem may also restart the Rabbit 4000 microprocessor after a timeout has passed even if no message is received.

The sleep mode is controlled by the ZigBee modem with a set of user-configurable parameters. Although a parameter can be set with an AT command, the recommended procedure is to only initiate the sleep mode using either the zb_Rabbit_poweroff() or the zb_Rabbit_Sleep() function call.

The most important parameters are ST, SP, and SN. Together they control the duration of sleep and wake times.

ST is measured in milliseconds, and controls the amount of time the ZigBee modem, and consequently the Rabbit microprocessor, will stay awake waiting for RF or serial data before going to sleep. If any data are received, the ST counter will be reset. The Rabbit 4000 microprocessor needs approximately two seconds to boot and reinitialize the ZigBee modem, so the value of ST must be at least 2000.

SP is measured in 0.01 second intervals and controls the length of sleep for the ZigBee modem. The ZigBee modem will operate in a low-power mode for the time specified in SP, and then wake up briefly to poll its parent for a message. Depending on the value of SN, the ZigBee modem may then either return to sleep or wake up the Rabbit 4000 microprocessor. There are several important considerations for SP.

- The ZigBee parent (coordinator or router) can buffer a message for only 30 seconds,so SP must be set to no more than 28 seconds.

- While SP is measured in 0.01 second intervals, it only has a 0.25 second resolution, and any value sent to the ZigBee modem is rounded automatically.

- The overhead of polling for a message was tested internally and was found to be approximately 20 ms. Thus a hypothetical sleep with SN = 100 and SP = 100 will not wake the Rabbit microprocessor until 102 seconds have elapsed (rather than the expected 100 seconds). The polling time may be sensitive to network conditions and firmware version, so you should perform your own testing if timing is critical.

SN determines how many multiples of SP the radio will sleep before waking up if no message was otherwise received.

Two additional parameters are described below for completeness.

WH determines how long the ZigBee modem will hold a message for the RCM4510W to receive. Like ST, this parameter must be set carefully to ensure no messages are lost at startup. It is currently set to 3 seconds.

SO is a conditional flag and determines whether the ZigBee modem will wake the Rabbit 4000 microprocessor if SN and SP expire, or whether both parameters are reset to resume the sleep mode immediately.

There are several important ramifications and interactions with the operation of other function calls to consider when using the sleep mode.

When the Rabbit 4000 microprocessor wakes up from sleep, both the RCM4510W and user application will fully restart. The user program will not resume from the point at which it went to sleep.

User data should be initialized prior to calling zigbee_init() to ensure that cluster functions or the default message handler process an incoming wake message correctly.

When sleep is initiated, both the ZigBee modem and the Rabbit 4000 microprocessor will remain awake for the time in ST before actually powering down the Rabbit 4000 microprocessor and entering a low-power mode. Any messages received during this time period will cause the counter to reset, and must be processed immediately or be lost.

An end device is always preparing to sleep. The default is to set ST to its maximum value, and periodically send a "stay-awake" message to the ZigBee modem. Blocking for long periods of time and failing to call zb_tick() could result in the RCM4510W going to sleep unexpectedly.

The SLEEPMODE.C and SLEEPMODE2.C sample programs in the Dynamic C SAMPLES\ZIGBEE folder and the function documentation for zb_Rabbit_poweroff() and zb_Rabbit_Sleep() provide more specific information regarding the implementation and use of the sleep mode.

6.4 Dynamic C Function Calls

6.4.1 ZigBee Modem Function Calls

The function calls described in this section are for use with the ZigBee modem features. The source code is in the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_API.LIB library if you need to modify it for your own board design.

The sample programs in the Dynamic C SAMPLES\ZigBee folder illustrate the use of the function calls.

6.4.1.1 Macros

ENDPOINT_TABLE_BEGIN

ENDPOINT_TABLE_BEGIN
ENDPOINT_TABLE_ENTRY(EP, DSC, PID, DID, FLAGS, ICCOUNT, OCCOUNT, ICL, OCL)
ENDPOINT_TABLE_ENTRY(EP, DSC, PID, DID, FLAGS, ICCOUNT, OCCOUNT, ICL, OCL)
...
ENDPOINT_TABLE_END

Description

These macros declare an endpoint table, as expected by the XBEE_API.LIB library. ENDPOINT_TABLE_ENTRY is a macro that is called to define an entry in the table. Note that entries should not be separated by commas or semicolons.

Parameters

EP
Endpoint number (1–219)

DSC
Endpoint descriptor (0–255)

PID
Profile ID (0–65535)

DID
Device ID (0–65535)

FLAGS
User-defined byte

ICCOUNT
Input cluster ID list count (0–255)

OCCOUNT
Output cluster ID list count (0–255)

ICL
Input cluster ID list (address of a RabbitClusterIDList_t)

OCL
Output cluster ID list (address of a RabbitClusterIDList_t)

ZB_GENERAL_MESSAGE_HANDLER

#define ZB_GENERAL_MESSAGE_HANDLER <functionName>

Description

Defines the general message handler for messages that do not have endpoints or other addressing means specified. The general message handler callback function prototype must be
int functionName (char *data);
where data points to the message data. To get more data about the message, call the zb_receive() function. This will give you access to any addressing information that was received.
To reply to this message directly, use the zb_reply() function call before another message arrives. To ensure that no messages arrive before you have replied, do not call zb_tick() until your reply has been sent (zb_reply() or zb_send() called).
If the message cannot be handled by the general message handler, you may return non-zero, and the zb_tick() function will indicate that a message is available. You may access the message using zb_receive() and handle it then.
Return a zero to indicate that the message has been completely processed. zb_tick() will then not indicate that a message is available.

ZB_FATAL_ERROR

#define ZB_FATAL_ERROR <function-name>

Description

The ZB_FATAL_ERROR function handles the case where the XBEE_API.LIB library is reporting that it is experiencing an error beyond its capability to handle. This will usually occur during startup if the ZigBee modem is not responding.

Parameter

A function to call to handle the fatal error. The prototype is shown below.
void <function-name>(int errorcode);
The error code is one of the defined errors in the ERRNO.LIB library. As of January, 2007, the only fatal error is EIO.

ZB_MULTI_PROFILE

#define ZB_MULTI_PROFILE

Description

This macro enables Profile ID checking in the message interpretation function for explicitly addressed messages. This check will require a received Profile ID to match an associated Endpoint Table Endpoint Descriptor Profile ID before calling the associated callback function.

ZB_CONSTRUCT_NODE_ID

#define ZB_CONSTRUCT_NODE_ID <function-name>

Description

Define this macro if you want to construct your own Node ID string at runtime. This will allow your program to construct an ID that could contain information about what the capabilities of the device connected to the modem are.
A Node ID string must be made up of printable ASCII characters, and must be no more than 20 characters long.
The function prototype must be as follows.
char *<function-name>(void);
The function must return a pointer to static data.

GET_NODE_DATA

_zb_NodeData_t *GET_NODE_DATA(int index)

Description

This macro gets the node data located at the indexed spot in the array. The macro calls a function to determine where in memory the element is because the array could extend into xmem. Repeated calls to this macro do not incur a processing penalty since the last access is remembered. Note that the node structure is used internally by the library for addressing. The data stored in the node structure must be be in network order.

Parameters

index
index into the node array

Return Value

Address of the node in root memory.

ZB_LATEST_MESSAGE

api_frame_t *ZB_LATEST_MESSAGE()

Description

This macro gives the address of the api_frame_t structure holding the last message received.

ZB_ERROR

int ZB_ERROR();

Description

This macro accesses the error code variable of the XBEE_API.LIB library for the last error encountered.

ZB_LAST_STATUS

int ZB_LAST_STATUS();

Description

This macro returns the network status of this node. See the constants defined below for values and their meanings.
#define ZB_HARDWARE_RESET    0
#define ZB_WATCHDOG_RESET    1
#define ZB_JOINED            2
#define ZB_UNJOINED          3
#define ZB_COORD_STARTED     6
In addition to these constants, the ZB_JOINING_NETWORK() macro returns TRUE(1) when ZB_LAST_STATUS() ! = ZB_JOINED.
You can use a statement like
while (ZB_JOINING_NETWORK()) {
to check if the arbitrary maximum time to join expired. If it did, process the timeout error condition.

ZB_XMIT_STATUS

int ZB_XMIT_STATUS(void);

Description

Returns the status of the last transmission sent by this software. This function call is actually a macro. Under normal operation, an application will be concerned mostly with ADDR_NOT_FOUND or ROUTE_NOT_FOUND. The first status indicates that the device in question has shut down or moved out of range. The second status indicates that some intermediate nodes that provided the route to the targeted device have shut down.

Return Value

DELIVERY_SUCCESS — 0
CCA_FAILURE — 0x02
NET_ACK_FAILURE — 0x21
NOT_JOINED — 0x22
SELF_ADDRESSED — 0x23
ADDR_NOT_FOUND — 0x24
ROUTE_NOT_FOUND — 0x25

ZB_XMIT_OVERHEAD

int ZB_XMIT_OVERHEAD(void);

Description

Returns the overhead required to send the last message. This function is actually a macro.

Return Value

NO_DISC_OVERHEAD — 0
ADDR_DISCOVERY — 0x01
ROUTE_DISCOVERY — 0x02
ADDR_AND_ROUTE — 0x03

6.4.1.2 Function Calls

resetRadio

void resetRadio (void);

Description

Resets the ZigBee modem by toggling the reset line to the modem.

Return Value

None.

zb_swapBytes

int zb_swapBytes(int *value);

Description

Swaps the bytes of a word-sized (two-byte) value into an appropriate ZigBee network-style int.

Parameter

value
address of word to change

Return Value

New value of value.

See Also
htons (host to network short), described in the Dynamic C TCP/IP User's Manual (Vol.ume 1)
zb_getATCmdResponse

int zb_getATCmdResponse(_at_cmdresp_t *buffer, int blen);

Description

Waits for a response to the current AT command.

Parameters

buffer
pointer to where to put the response.

blen
size of buffer.

Return Value

0 — success.
-ETIME — timeout.

Side Effects

_zb_error may be set to -ZBERR_FRAMEID_MISMATCH to indicate that a frame id did not match

zb_sendATCmd

int zb_sendATCmd(char *_cmdstr, char *data, int dlen);

Description

Sends an AT command to the ZigBee modem. Do not wait for a response. This function call is useful when a command is expected to take too long to respond
(>_ZB_MAXSTREAM_TIMEOUT milliseconds).

Parameters

cmdstr
pointer to string of command text.

data
pointer to command parameters.

dlen
length of command parameters.

Return Value

0 — success.
-EIO — serial I/O error.
-ENOSPC — output buffer is full.
-ZBERR_TX_LOCKED — radio transmissions are currently blocked, for example, when node discovery is running. Wait until the condition such as node discovery is over.

zb_API_ATCmdResponse

int zb_API_ATCmdResponse(char *_cmdstr, void *data, int dlen,
_at_cmdresp_t *resp)

Description

Sends an API AT command and waits for the response.

Parameters

cmdstr
pointer to string of command text. We expect "ATcc", so we skip the first two bytes for API format commands.

data
pointer to address of data to send.

dlen
length of data to send.

resp
pointer to address of AT response buffer.

Return Value

0 — success.
-ZBERR_AT_CMD_RESP_STATUS — ZigBee modem returned failure
-ETIME — timeout.
-EIO — serial I/O error.
-ENOSPC — output buffer full.
-ZBERR_TX_LOCKED — radio transmissions are currently blocked, for example, when node discovery is running..

zigbee_init

int zigbee_init(void);

Description

Initializes the Rabbit ZigBee protocol and some global variables.

Return Value

0 — success.
¹0 — error. See _zb_error for an explanation of the error codes.

zb_Rabbit_poweroff

int zb_Rabbit_poweroff(_zb_power_control_t *zbp);

Description

Sends the wake-up parameters to the ZigBee modem and instructs it to power down the non-modem RCM4510W circuits.

Parameter

zbp
pointer to the address of the wake-up parameter structure.

Return Value

0 — success (power will turn off soon).
-EINVAL — invalid parameters.
-EOPNOTSUPP — operation not supported (on routers or coordinators) or function was called while in programming mode.

Power Control Data Structures and Constants

#define MAXSTREAM_ANA_CHANNELS 8 // eight analog channels
#define ZB_WAKE_RADIO 0
#define ZB_WAKE_DIO 1
#define ZB_WAKE_AIO 2
#define ZB_WAKE_TIME 4
#define ZB_WAKE_VALID_MASK 4 // wake on I/O not ready yet.
#define ZB_MAX_SP_TIME 2800 // 1/100 seconds for radio to sleep
#define ZB_COORD_MAX_SP_TIME 2800 // 1/100 seconds for radio to sleep
#define ZB_MAX_ST_TIME 2000 // 2 seconds for radio to wait for a
// message after waking up, before going back to sleep.

typedef struct{
char wakeFlag;
int digIOMask;
char anaChannelMask;
int anaChannelLevels[MAXSTREAM_ANA_CHANNELS];
long time_in_ms;
int radio_duty;
} _zb_power_control_t;

The maximum powerdown time that the ZigBee modem can be set up for is 28 seconds (2800 × 0.01 seconds) with a resolution of 0.25 seconds, and the maximum time to wait for a message before powering down again is 2 seconds (2000 × 0.001 seconds).

The parameters in the structure can be set up with the following options.

wakeFlag

0x04 — wake also on timer expired

digIOMask

Reserved for future use

anaChannelMask

Reserved for future use

anaChannelLevels [MAXSTREAM_ANA_ CHANNELS]

Reserved for future use

time_in_ms

How long (in milliseconds).the non-modem RCM4510W circuits will be powered down. The actual time in milliseconds is calculated as follows.

(int)(radio_duty * (time_in_ms / radio_duty))

radio_duty

Powerdown time in multiples of 0.01 seconds. The maximum value for the radio_duty cycle is 28 seconds (0x0AF0).

Since the ZigBee modem controls the powerdown period, the basic powerdown period is limited to the maximum powerdown time of 28 seconds. The time_in_ms parameter allows you to place the RCM4510W in a powered down mode for an integral multiple of the powerdown time the ZigBee modem is set for. For example, if the radio_duty cycle is 28 seconds, the RCM4510W could be set to power down for 56 seconds, 84 seconds, etc.

The accuracy of the counter used in the ZigBee modem is limited, and there is an overhead of approximately 20 ms for each radio_duty cycle as the parent router or coordinator is polled for messages. Testing should be performed for time-sensitive applications to ensure suitable operation.

zb_Rabbit_Sleep

int zb_Rabbit_Sleep(st, sp, sn);

Description

Sets the parameters that control the sleep mode using the default MaxStream parameters.

Parameters

st
time before sleep in milliseconds — this timer controls for how long the Rabbit 4000 microprocessor will stay awake. The minimum value below is the time that it takes the RCM4510W to become fully operational. If ST is set to a value smaller than 2000, the Rabbit 4000 microprocessor will be go back to sleep before it has the chance to run its code.

The minimum value for ST is 2000 (0x07D0)

The maximum value for ST is 65534 (0xFFFE)

sp
cyclic sleep period in 0.01 second increments — controls for how long the Rabbit 4000 microprocessor will remain asleep.

The minimum value for SP is 0.32 seconds (0x0020)

The maximum value for SP is 28.00 seconds (0x0AF0)

sn
sleep time extender — used in cases where we want the Rabbit 4000 microprocessor to stay asleep for periods longer than the sp time.

If sn > 1, then the Rabbit microprocessor will remain asleep for a period of sn * sp. The radio will still wake up briefly every time sp expires and it will poll its parent router or coordinator for messages. If there is a message waiting, the ZigBee modem will wake up the Rabbit microprocessor and forward the message. If there is no message, the ZigBee modem goes to sleep again for another sp period.

The minimum value for SN is 1

The maximum value for SN is 0x7FFF

Return Value

0 — success (power will turn off after the ST timer expires).
-EINVAL — invalid parameters.
-EOPNOTSUPP — operation not supported (on routers or coordinators) or function was called while in programming mode.

zb_tick

int zb_tick(void);

Description

Drives the communications between the Rabbit 4000 and the ZigBee modem. Performs a service discovery once every minute to see whether any new nodes have joined the network.

Return Value

ZB_NOMESSAGE 0 — no messages received.
ZB_MESSAGE 1 — a message has arrived.
ZB_RADIO_STAT 2 — modem status change.
ZB_MSG_STAT 3 — message transmission status available.
various codes <0 — an error has occurred.

zb_send

int zb_send(zb_sendAddress_t *addr);

Description

Sends a message to other ZigBee modems. The addressing modes may be combined to direct messages more completely.

Parameters

addr
pointer to the address data structure. Use one or more of the following addressing modes for transmission:

_ZB_ADDRDIRECT — addr points to the 64-bit (8-byte) MAC address of the destination. A MAC address of 0xFFFF indicates a broadcast message.

_ZB_ADDRENDPOINT — provide a remote endpoint number to send the message to and the local sending endpoint. All nodes with this endpoint will receive the message unless other addressing modes are included.

_ZB_ADDRCLUSTER — provide a ClusterID plus a Profile ID. The message will be sent to all devices that implement the specified ClusterID/Profile ID if other addressing modes are not included.

_ZB_ADDRNETWORK — provide a 16-bit network address.

Return Value

0 — Queued – the message has been sent to the modem for transmission.
-EINVAL — bad parameters.
-ENOSPC — cannot give message to serial port.
-ENONET — modem has not joined a network.

zb_receive

api_frame_t *zb_receive(char *data, int *len);

Description

This function should be called when the zb_tick() function call indicates that a message is waiting to be handled.The parameter to this routine will be the address of the buffer that will accept the new message. The buffer should be _API_MAXRECV long to ensure there is sufficient space to receive the data. The function call returns the address of the beginning of the entire message (a pointer to an api_frame_t). If the function returns NULL, there was no message. The current message will be held until the next message arrives. Note that no new messages will arrive until zb_tick() is called.

Parameters

data
pointer to buffer to receive data. Send NULL to only get the address of the api_frame_t.

len
pointer to buffer to receive data length. Send NULL to only get the address of the api_frame_t.

Return Value

NULL — no message was received.
¹ NULL — address of current message.

zb_reply

int zb_reply (char *reply, int len);

Description

Sends a reply to the last message received. This function call uses the address of the last message's sender as the addressee of the reply. The reply will be sent using explicit addressing.

Parameters

reply
pointer to message to send.

len
length of message.

Return Value

0 — Queued – the message has been sent to the modem for transmission.
-EINVAL — bad parameters.
-ENOSPC — cannot give message to serial port.

zb_missed_messages

int zb_missed_messages (void);

Description

Returns the number of messages missed since the last time zb_receive() was called.

Return Value

Count of missed messages

zb_MakeEndpointClusterAddr

zb_sendAddress_t *zb_MakeEndpointClusterAddr (int node, int srcEP, int destEP, int clusterID, zb_sendAddress_t *addr);

Description

Fills in the address structure for sending to zb_send().

Parameters

node
which node to send look up from the node table. Sending -1 indicates a broadcast address

srcEP
source (sending) endpoint.

destEP
destination endpoint.

clusterID
destination Cluster ID.

addr
pointer to buffer to put the address data into.

Return Value

A pointer to the address buffer.
A NULL return value means that either the node value is out of range or a valid node entry was not found.

zb_MakeIEEENetworkAddr

zb_sendAddress_T *zb_MakeIEEENetworkAddr(int node,
zb_sendAddress_t *buffer)

Description

Creates an address for the zb_send() routine consisting of the IEEE 8-byte MAC address and the 2-byte network address.

Parameters

node
index to the node lookup table.

buffer
pointer to where to put the address data.

Return Value

A pointer to the address data.
A NULL return value means that either the node value is out of range or a valid node entry was not found.

6.4.2 ZigBee Firmware Download Function Calls

The function calls described in this section are used to download the ZigBee modem firmware. Ordinarily, the firmware could be downloaded directly to the ZigBee modem via MaxStream's X-CTU utility. These function calls allow this to happen directly through the Rabbit 4000 microprocessor so that the embedded control system built around the RCM4510W RabbitCore module does not have to be taken apart. The source code is in the Dynamic C LIB\Rabbit4000\ZigBee\XBEE_BOOT.LIB library if you need to modify it for your own board design.

wait_serial_B_char

char wait_serial_B_char (void);

Description

This function call reads Serial Port B continuously. If a valid character is read, it returns the character.

Return Value

The character read.

zb_start_bootloader

void zb_start_bootloader(void);

Description

Processes the hardware signaling needed to operate the ZigBee modem in the bootload mode.

Return Value

None.

6.4.3 XModem Function Calls

The function calls described in this section support the XModem protocol used with the ZigBee modem. The source code is in the Dynamic C LIB\Rabbit4000\ZigBee\XMODEM.LIB library if you need to modify it for your own board design.

send_XModem

int send_XModem(int packetSize, char *(*fileread)());

Description

Sends data via the XModem protocol.

Parameters

packetSize
1024 or 128. Any other size will cause this function to return an error.

fileread
pointer to a function call that returns the data to write. This function call returns a pointer to the data buffer to write, or NULL to signify EOF. All data buffers must have a length of 128 bytes or 1024 bytes, even if the buffer is the last record.

The fileread() function prototype must look like as follows.

char *fileread(int recordNumber, int recordSize);

where recordNumber is the record offset into the data, and recordSize is either 128 or 1024.

Return Value

0 — success.
-EINVAL — invalid baud rate specified or invalid packet size specified.
-ETIMEDOUT — timed out sending data.

X_timedSendChar

int X_timedSendChar(char c);

Description

Sends a single character out the serial port, waiting X_PACKET_TIMEOUT milliseconds for space in the output buffer to be available.

Parameter

c
the character to send.

Return Value

0 — success.
-ETIMEDOUT — no space in buffer to send character.

X_GetCheckValue

int X_GetCheckValue(int useCRC, int packetSize, char *datapacket);

Description

Calculates the check value for the given packet.

Parameters

useCRC
type of check to calculate:
1 = CRC,
0 = checksum.

packetSize
how many bytes to check.

datapacket
pointer to where the data are.

Return Value

Check value word.

receive_XModem

int receive_XModem(char * (*getBuffer)(), int (*writeData)());

Description

Receives data via the XModem protocol. This function call will send a C as a start character to indicate that CRC is the desired check value. If no response comes after three seconds, the start character is sent up to two more times. If there is still no response, the start character is changed to NAK, and the check value will be a checksum. If no response is received two more retries will be made.

Parameters

getBuffer()
pointer to a function call to get memory for a new packet. The function call must return a pointer to a memory location so that receive_XModem() has a place to put a new packet. If the getBuffer() function call returns NULL, the file transfer will be cancelled.

getBuffer() must be declared as

char * getBuffer (int length);

where length is the amount of memory needed for the new packet.

writeData()
pointer to a function call to process a received packet. The function call must accept the address of the new packet and its length. If the packet processing is successful, the function call should return zero, otherwise a non-zero return value will cause the file transfer to be cancelled.

writeData() must be declared as follows.

int writeData (char *data, int length);

Return Value

0 — success.
-ETIMEDOUT — timeout error.
-ECONNREFUSED — transfer cancelled.

6.5 Where Do I Go From Here?

NOTE If you purchased your RCM4510W through a distributor or through a Rabbit Semiconductor partner, contact the distributor or partner first for technical support.

If there are any problems at this point:

Use the Dynamic C Help menu to get further assistance with Dynamic C.

Check the Rabbit Semiconductor Technical Bulletin Board and forums at
www.rabbit.com/support/bb/ and at www.rabbitcom/forums/.

Use the Technical Support e-mail form at www.rabbit.com/support/.

If the sample programs ran fine, you are now ready to go on.

An Introduction to ZigBee provides background information on the ZigBee protocol, and is available on the CD and on our Web site.

Maxtream's XBee™ Series 2 OEM RF Modules provides complete information for the ZigBee modem used on the RCM4510W RabbitCore modules, provides background information on the ZigBee protocol, and is available at www.maxstream.net/products/xbee-series-2/product-manual_XBee_Series2_OEM_RF-Modules_ZigBee.pdf.

r — Radio Module Functions	A — Read ZigBee modem analog input (0–3) D — Set/Read ZigBee modem digital I/O (0–9) R — Reset ZigBee modem c — Command mnemonic z — Put this RCM4510W to sleep ESC — Return to Main Menu
t — Radio Transmit Functions	e — Send string via string endpoint p — Start/stop pinging another node s — Send a string to another node ESC — Return to Main Menu
l — List Discovered Nodes	Lists ZigBee device nodes discovered

Rabbit Semiconductor
www.rabbit.com

Power Control Data Structures and Constants #define MAXSTREAM_ANA_CHANNELS 8 // eight analog channels #define ZB_WAKE_RADIO 0 #define ZB_WAKE_DIO 1 #define ZB_WAKE_AIO 2 #define ZB_WAKE_TIME 4 #define ZB_WAKE_VALID_MASK 4 // wake on I/O not ready yet. #define ZB_MAX_SP_TIME 2800 // 1/100 seconds for radio to sleep #define ZB_COORD_MAX_SP_TIME 2800 // 1/100 seconds for radio to sleep #define ZB_MAX_ST_TIME 2000 // 2 seconds for radio to wait for a // message after waking up, before going back to sleep. typedef struct{ char wakeFlag; int digIOMask; char anaChannelMask; int anaChannelLevels[MAXSTREAM_ANA_CHANNELS]; long time_in_ms; int radio_duty; } _zb_power_control_t;
The maximum powerdown time that the ZigBee modem can be set up for is 28 seconds (2800 × 0.01 seconds) with a resolution of 0.25 seconds, and the maximum time to wait for a message before powering down again is 2 seconds (2000 × 0.001 seconds).
The parameters in the structure can be set up with the following options.
`wakeFlag`	0x04 — wake also on timer expired
`digIOMask`	Reserved for future use
`anaChannelMask`	Reserved for future use
`anaChannelLevels [MAXSTREAM_ANA_ CHANNELS]`	Reserved for future use
`time_in_ms`	How long (in milliseconds).the non-modem RCM4510W circuits will be powered down. The actual time in milliseconds is calculated as follows. *(int)(radio_duty (time_in_ms / radio_duty))**
`radio_duty`	Powerdown time in multiples of 0.01 seconds. The maximum value for the `radio_duty` cycle is 28 seconds (0x0AF0).
Since the ZigBee modem controls the powerdown period, the basic powerdown period is limited to the maximum powerdown time of 28 seconds. The `time_in_ms` parameter allows you to place the RCM4510W in a powered down mode for an integral multiple of the powerdown time the ZigBee modem is set for. For example, if the `radio_duty` cycle is 28 seconds, the RCM4510W could be set to power down for 56 seconds, 84 seconds, etc. The accuracy of the counter used in the ZigBee modem is limited, and there is an overhead of approximately 20 ms for each `radio_duty` cycle as the parent router or coordinator is polled for messages. Testing should be performed for time-sensitive applications to ensure suitable operation.