Zigbee Module Examples

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions | Variables
module.c File Reference

Interface to the Zigbee Module. More...

`#include "module.h"`
`#include <string.h>`
`#include "../HAL/hal.h"`
`#include "../Common/utilities.h"`
`#include "zm_phy.h"`
`#include "module_errors.h"`
`#include <stddef.h>`
`#include <stdint.h>`

## Macros
#define | METHOD_MODULE_RESET 0x0100
#define | MODULE_RESET_INITIAL_DELAY_MS 400
#define | METHOD_SYS_VERSION 0x0200
#define | SYS_VERSION_PAYLOAD_LEN 0
#define | METHOD_SYS_RANDOM 0x0300
#define | SYS_RANDOM_PAYLOAD_LEN 0
#define | METHOD_SYS_SET_TX_POWER 0x1100
#define | SYS_SET_TX_POWER_PAYLOAD_LEN 1
#define | ZB_WRITE_CONFIGURATION_LEN 2
#define | METHOD_SET_PAN_ID 0x0400
#define | METHOD_SET_CHANNEL 0x0500
#define | METHOD_SET_CHANNEL_MASK 0x0600
#define | METHOD_GET_DEVICE_INFO 0x0700
#define | ZB_GET_DEVICE_INFO_PAYLOAD_LEN 1
#define | METHOD_SYS_NV_READ 0x0800
#define | SYS_NV_READ_PAYLOAD_LEN 3
#define | METHOD_SYS_NV_WRITE 0x0900
#define | SYS_NV_WRITE_PAYLOAD_LEN 4
#define | METHOD_SYS_GPIO 0x0A00
#define | SYS_GPIO_PAYLOAD_LEN 2
#define | METHOD_SET_RF_TEST_MODE 0x0B00
#define | ZCD_NV_RF_TEST_MODE_LEN 4
#define | METHOD_SET_STARTUP_OPTIONS 0x0C00
#define | METHOD_SET_ZIGBEE_DEVICE_TYPE 0x0D00
#define | METHOD_SET_CALLBACKS 0x0E00
#define | METHOD_WAIT_FOR_MESSAGE 0x0F00
#define | WFM_POLL_INTERVAL_MS 100
#define | METHOD_GET_CONFIGURATION_PARAMETER 0x1000
#define | LENGTH_OF_LARGEST_CONFIG_PARAMETER 17
#define | ZB_READ_CONFIGURATION_PAYLOAD_LEN 1
#define | ZB_READ_CONFIGURATION_STATUS_FIELD SRSP_PAYLOAD_START
#define | METHOD_SET_SECURITY_MODE 0x1200
#define | METHOD_SET_SECURITY_KEY 0x1300
#define | METHOD_SET_POLL_RATE 0x1400

## Functions
void | moduleInit ()
moduleResult_t | moduleReset ()
void | displaySysResetInd ()
char * | getResetReason (uint8_t reason)
moduleResult_t | sysVersion ()
void | displaySysVersion ()
moduleResult_t | sysRandom ()
moduleResult_t | sysSetTxPower (uint8_t txPowerSetting, uint8_t *actualTxPowerSetting)
moduleResult_t | zbWriteConfiguration (uint8_t zcd, uint8_t zcdLength, uint8_t *data)
moduleResult_t | setPanId (uint16_t panId)
moduleResult_t | setChannel (uint8_t channel)
moduleResult_t | setChannelMask (uint32_t channelMask)
moduleResult_t | zbGetDeviceInfo (uint8_t dip)
uint8_t | getNvItemSize (uint8_t nvItem)
moduleResult_t | sysNvRead (uint8_t nvItem)
moduleResult_t | sysNvWrite (uint8_t nvItem, uint8_t *data)
moduleResult_t | sysGpio (uint8_t operation, uint8_t value)
moduleResult_t | setRfTestMode (uint8_t mode, uint8_t channel, uint8_t txPower, uint8_t txTone)
char * | getRfTestModeName (uint8_t mode)
moduleResult_t | setStartupOptions (uint8_t option)
char * | getDeviceTypeName (uint8_t deviceType)
moduleResult_t | setZigbeeDeviceType (uint8_t deviceType)
moduleResult_t | setCallbacks (uint8_t cb)
moduleResult_t | waitForMessage (uint16_t messageType, uint8_t timeoutSecs)
moduleResult_t | getConfigurationParameter (uint8_t configId)
moduleResult_t | displayNetworkConfigurationParameters ()
char * | getDeviceStateName (uint8_t state)
moduleResult_t | displayDeviceInformation ()
moduleResult_t | displayBasicDeviceInformation ()
void | displayZmBuf ()
char * | getSecurityModeName (uint8_t securityMode)
moduleResult_t | setSecurityMode (uint8_t securityMode)
moduleResult_t | setSecurityKey (uint8_t *key)
moduleResult_t | setPollRate (uint16_t pollRate)

## Variables
uint8_t | zmBuf [ZIGBEE_MODULE_BUFFER_SIZE]

## Detailed Description

Interface to the Zigbee Module.

This file contains library methods as well as error checking and return values.

Requires one physical interface to be defined, e.g. ZM_PHY_SPI.

Note:
  To output SPI transmit information, define MODULE_INTERFACE_VERBOSE. It is recommended to define this on a per-project basis. In IAR, this can be done in Project Options : C/C++ compiler : Preprocessor In the defined symbols box, add: MODULE_INTERFACE_VERBOSE

Rev:
  1642

Author:
  dsmith

Date:
  2012-10-31 11:17:04 -0700 (Wed, 31 Oct 2012)

# Support

Please refer to the wiki at www.anaren.com/air-wiki-zigbee for more information. Additional support is available via email at the following addresses:

- Questions on how to use the product: AIR@a.nosp@m.nare.nosp@m.n.com
- Feature requests, comments, and improvements: featu.nosp@m.rere.nosp@m.quest.nosp@m.s@te.nosp@m.slaco.nosp@m.ntro.nosp@m.ls.co.nosp@m.m
- Consulting engagements: sales.nosp@m.@tes.nosp@m.lacon.nosp@m.trol.nosp@m.s.com

# License

Copyright (c) 2012 Tesla Controls. All rights reserved. This Software may only be used with an Anaren A2530E24AZ1, A2530E24CZ1, A2530R24AZ1, or A2530R24CZ1 module. Redistribution and use in source and binary forms, with or without modification, are subject to the Software License Agreement in the file "anaren_eula.txt"

YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL ANAREN MICROWAVE OR TESLA CONTROLS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSE INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.

## Function Documentation

moduleResult_t displayBasicDeviceInformation | ( |  | ) |

A minimalized version of displayDeviceInformation() for use on memory-constrained devices.

See also:
  displayDeviceInformation() for description of fields.

moduleResult_t displayDeviceInformation | ( |  | ) |

Displays the radio's device Information Properties. Device Information Properties include:

- Device State indicates whether the radio is on a network or not, and what type of device it is. This is a handy thing to check if things aren't operating correctly. If the device is starting as a coordinator, you'll see states of 01, 08, 08, then 09 once it has fully started.
- MAC Address (aka IEEE Address) is a globally unique serial number for this IC.
- Device Short Address is a network address assigned by the coordinator, similar to an IP Address in DHCP. The Coordinator always has a Short Address of 0.
- Parent MAC Address is the IEEE Address of this device's "parent", i.e. which device was used to join the network. For a router, once joined this parent MAC address is irrelevant. This DIP will NOT be updated if the network reforms. For an end-device then this parent MAC address will always specify which router the end-device is joined to.
- Channel is which frequency channel the device is operating on.
- PAN ID (Personal Area Network Identifier) of the network is a unique number shared for all devices on the same network.
- Extended PAN ID of the network is the coordinator's MAC Address.

If device is not connected to a network then the Short Address fields will be 0xFEFF, the Parent MAC Address and channel will be 0, and the Extended PAN ID will be this device's MAC Address.

moduleResult_t displayNetworkConfigurationParameters | ( |  | ) |

Utility method to display stored network configuration parameters. These are the configuration parameters stored in NV memory and are used to initialize the Module.

Note:
  These are just what is used on startup - this does not mean that the module is currently using these settings. Use displayDeviceInformation() to see current values used.

void displaySysResetInd | ( |  | ) |

Displays the contents of a SYS_RESET_IND message. These are returned from the module after a hard or soft reset.

Precondition:
  zmBuf contains a valid SYS_RESET_IND message.

void displaySysVersion | ( |  | ) |

Displays a SYS_VERSION message. These are returned from the module after a call to sysVersion().

Precondition:
  zmBuf contains a valid SYS_VERSION message

void displayZmBuf | ( |  | ) |

Utility method to display the entire contents of the Module Buffer, zmBuf. Not normally used in driver or examples but useful for debugging Module communications.

moduleResult_t getConfigurationParameter | ( | uint8_t | configId | ) |

Retrieves the given configuration parameter from the Module.

Parameters:

  configId | the configuration parameter to retrieve. See section "Z-Stack Common Definitions" in module.h for a list of valid config parameters. Not checked for validity.

Postcondition:
  zmBuf contains the specified parameter, starting at ZB_READ_CONFIGURATION_START_OF_VALUE_FIELD

Note:
  Does not verify configId is a valid configId
  Does not verify length returned in the SRSP matches what the length should be for that configId.

char* getDeviceStateName | ( | uint8_t | state | ) |

Retrieves the name of the device state in a human-readable format.

Parameters:

  state | The integer value for the ZDO state

Returns:
  the name of the ZDO state, or "Unknown" if not known.

char* getDeviceTypeName | ( | uint8_t | deviceType | ) |

Retrieves the name of the device type in a human-readable format, e.g. Coordinator, Router, or End Device.

Parameters:

  deviceType | the type of device

Returns:
  The name of the deviceType

uint8_t getNvItemSize | ( | uint8_t | nvItem | ) |

Retrieves the size of the selected Non-Volatile (NV) memory item. NV Items 1 through 4 are 2 bytes each; 5 and 6 are 16 bytes each. NV Items 8 & 9 are used internally by the module.

Parameters:

  nvItem | which Non-Volatile memory item to get the size of. Must be 1-6 inclusive.

Returns:
  The size of the given nvItem

char* getResetReason | ( | uint8_t | reason | ) |

Utility method for displaying the reset reason from a SYS_RESET_IND message.

Parameters:

  reason | the reset reason

Returns:
  A string containing the name of the reset reason, or "Unknown" if it is not known.

char* getRfTestModeName | ( | uint8_t | mode | ) |

Utility method for displaying the name of the RF Test Mode

Parameters:

  mode | the RF Test Mode

Returns:
  A string containing the name of the test mode, or "Unknown" if it is not known.

char* getSecurityModeName | ( | uint8_t | securityMode | ) |

Utility method for displaying the name of the security mode

Parameters:

  securityMode | the securityMode we want to know the name of

Returns:
  the name of the securityMode, or "Unknown" if it is not known.

void moduleInit | ( |  | ) |

Initializes the module's physical interface, either SPI or UART, depending on which phy file is included.

moduleResult_t moduleReset | ( |  | ) |

Resets the Module using hardware and retrieves the SYS_RESET_IND message. This method is used to restart the Module's internal state machine and apply changes to startup options, zigbee device type, etc.

Postcondition:
  zmBuf contains the version structure, starting at MODULE_RESET_RESULT_START_FIELD

See also:
  Interface Specification for order of fields

moduleResult_t setCallbacks | ( | uint8_t | cb | ) |

Enable/Disabless callbacks on the Module.

Parameters:

  cb | must be either CALLBACKS_ENABLED or CALLBACKS_DISABLED. If not one of these values then the error INVALID_PARAMETER will be returned.

See also:
  section ZCD_NV_ZDO_DIRECT_CB in Module Interface Specification

moduleResult_t setChannel | ( | uint8_t | channel | ) |

Configures the Module to only join the specified channel. Simple wrapper method for setChannelMask if only one channel is desired. Overwrites the current channel mask.

Parameters:

  channel | must be 11..25, inclusive. If set to 0 then Module will scan ALL CHANNELS. If channel is not 11..25 or 0 then the error INVALID_PARAMETER will be returned.

Note:
  If channel or channel mask is NOT set then Module will use channel 11 only.
  Channel 26 can only be used if INCLUDE_CHANNEL_26 in module.h is defined.

See also:
  setChannelMask()

moduleResult_t setChannelMask | ( | uint32_t | channelMask | ) |

Configures which RF channels the Module may use to join a network. The module will only use the channels specified in the channel mask. Functionality depends on whether the device is a Coordinator or Router/End Device:

- Coordinator The Module will only create a network on one of the channels that matches the mask. When the coordinator starts up, it scans all the channels in its channel mask and picks the channel with the least noise. The coordinator will stay on the same channel until it is reset.
- Router or End Device The Module will only search on channels that match the channel mask. The more channels in the channel mask, the longer startup will take since the device has to scan each channel.

Parameters:

  channelMask | bitmap of which channels to use. If channelMask = ANY_CHANNEL then the radio will join a network on any channel. Must be between MIN_CHANNEL_MASK and MAX_CHANNEL_MASK, or ANY_CHANNEL.

Note:
  The default channel after a CLEAR_CONFIG is channel 11, or (MSB first) 0x00000800, or binary 1000|0000|0000
  For example, to allow only channels 11, 14, and 15, then set channel mask 0x980, binary 1001|1000|0000
  if using a packet sniffer, be sure to change the channel on the packet sniffer too or else you won't see any packets.
  Channel 26 cannot be used on modules with a range extender due to FCC limits on radiated power. If you would like to use channel 26, then #define INCLUDE_CHANNEL_26 in module.h

moduleResult_t setPanId | ( | uint16_t | panId | ) |

Configures the Module to only join a network with the given panId. If panId = ANY_PAN (the default) then the module will join any network.

Parameters:

  panId | the PANID to join, or ANY_PAN to join any PAN

Note:
  be sure you know what you're doing if you're restricting your network to a specific PANID. In normal operation this command should not be used, or else you may end up with two networks with the same PANID, which is bad.

moduleResult_t setPollRate | ( | uint16_t | pollRate | ) |

Sets the ZCD_NV_POLL_RATE, which is used by end devices and controls how often an end device polls its associated router for new data. The default is 2000 (2 seconds). Higher poll rates will increase latency but reduce average power consumption. If poll rate is set too high for the amount of data coming to the end device then packets may be dropped. If this parameter is set to zero, the device will not automatically wake up to poll for data. Instead, an external trigger or an internal event (for example, via a software timer event) can be used to wake up the device.

Parameters:

  pollRate | how often (in mSec) to poll; must be between 0 to 65000, inclusive.

Note:
  for measuring sleep current consumption of an End Device, set pollRate to zero to turn off polling. This will stop the module from polling and make measurements easier.
  This setting is only valid for End Devices

moduleResult_t setRfTestMode | ( | uint8_t | mode,
|  | uint8_t | channel,
|  | uint8_t | txPower,
|  | uint8_t | txTone
| ) |  |

Configures the Module to output RF test tone. Send a system reset command after this command to enable. Must do a hard reset of Module to stop test tone.

Parameters:

  mode | The RF test mode; 1=Rx On, 2=UnModulated Tx, 3=Modulated Tx, 0=none
  channel | The channel to output test tone on; 11-26
  txPower | The RF output power of the CC2530. Actual module power output may be higher with PA.
  txTone | See CC2530 and CC2531 family guide, MDMTEST0 register description. Leave as 0.

Note:
  Not all fields are validated.

Todo:
  refactor with void sysNvWrite(uint8_t nvItem, uint8_t* data) ?

moduleResult_t setSecurityKey | ( | uint8_t * | key | ) |

Loads the 16 byte security key pointed to by key into the Module. Does not change security mode, you need to use setSecurityMode() too.

Note:
  if NOT using pre-configured keys then the coordinator will distribute its key to all devices.

Parameters:

  key | preConfiguredKey a 16B key to use. Must not be null.

Precondition:
  setSecurityMode() called
  key points to the 16 byte security key you want to use

moduleResult_t setSecurityMode | ( | uint8_t | securityMode | ) |

Configures the Module for the specified security mode. If securityMode is SECURITY_MODE_OFF then only ZCD_NV_SECURITY_MODE is written. Otherwise ZCD_NV_SECURITY_MODE and ZCD_NV_PRECFGKEYS_ENABLE are written.

Note:
  if NOT using pre-configured keys then the coordinator will distribute its key to all devices.

Parameters:

  securityMode | must be SECURITY_MODE_OFF, or SECURITY_MODE_PRECONFIGURED_KEYS, or SECURITY_MODE_COORD_DIST_KEYS. If none of these then an INVALID_PARAMETER error will be returned.

moduleResult_t setStartupOptions | ( | uint8_t | option | ) |

Configures startup options on the Module. These will reset various parameters back to their factory defaults. The Module supports two types of clearing state, and both are supported:

- STARTOPT_CLEAR_CONFIG restores all settings to factory defaults. Must restart the Module after using this option.
- STARTOPT_CLEAR_STATE only clears network settings (PAN ID, channel, etc.)

Parameters:

  option | which options to set. Must be zero, STARTOPT_CLEAR_CONFIG, or STARTOPT_CLEAR_STATE. If not one of these then an INVALID_PARAMETER error will be returned.

moduleResult_t setZigbeeDeviceType | ( | uint8_t | deviceType | ) |

Sets the Zigbee Device Type for the Module.

Parameters:

  deviceType | The type of Zigbee device. Must be COORDINATOR, ROUTER, or END_DEVICE

moduleResult_t sysGpio | ( | uint8_t | operation,
|  | uint8_t | value
| ) |  |

The Module has four GPIO pins, which can be configured as inputs or outputs. This command performs the specified General Purpose Input/Output (GPIO) operation.

Parameters:

  operation | which GPIO operation to do: GPIO_SET_DIRECTION, GPIO_SET_INPUT_MODE, GPIO_SET, GPIO_CLEAR, GPIO_TOGGLE, GPIO_READ
  value | the value to write to the outputs (if doing a GPIO_SET command)

Postcondition:
  zmBuf[SYS_GPIO_READ_RESULT_FIELD] contains the value returned by the Module if the operation was a GPIO_READ; indeterminate value otherwise

moduleResult_t sysNvRead | ( | uint8_t | nvItem | ) |

Retrieves the specified Non-Volatile (NV) memory item from the Module.

Precondition:
  Module was initialized.
  the nvItem was written to. If not then the NV item will contain indeterminate data.

Parameters:

  nvItem | which nvItem to write, 1 through 6 inclusive. If not one of these then INVALID_PARAMETER will be returned.

Postcondition:
  zmBuf contains the data read

Note:
  does not verify the length of the returned nvItem was what we expected

moduleResult_t sysNvWrite | ( | uint8_t | nvItem,
|  | uint8_t * | data
| ) |  |

Writes the specified Non-Volatile (NV) memory item to the Module. The contents of the selected nvItem will be overwritten from memory starting at data.

Precondition:
  Module was initialized.
  data points to the data to write into the non volatile memory item.

Parameters:

  nvItem | which nvItem to write. Items 1 through 6 are for user use; items 8 & 9 are for module internal use. If not one of these then INVALID_PARAMETER will be returned.
  data | points to the data to be written

moduleResult_t sysRandom | ( |  | ) |

Retrieves a random number from the Module using SYS_RANDOM command. The Module has a hardware random number generator that uses RF noise to derive the random number.

Postcondition:
  The random number is contained in zmBuf[SYS_RANDOM_RESULT_LSB_FIELD] and zmBuf[SYS_RANDOM_RESULT_MSB_FIELD].

Note:
  You can also use utility macro SYS_RANDOM_RESULT() to extract the random number from zmBuf.

moduleResult_t sysSetTxPower | ( | uint8_t | txPowerSetting,
|  | uint8_t * | actualTxPowerSetting
| ) |  |

Sets the Tx power of the module.

Parameters:

  txPowerSetting | the desired RF Tx setting. This modifies the CC2530's internal PA. Refer to module documentation for information about which setting corresponds to which RF output power. This will vary based on the type of module used (range extender vs. no range extender).
  actualTxPowerSetting | the actual output power setting that the module applies. It will be the same as txPowerSetting unless that value was not valid.

Postcondition:
  The module's transmit power has been set accordingly.

Warning:
  Improper use of this command may invalidate FCC/ETSI certification. Use with caution.

Since:
  Module Firmware version 2.5.1. This function will not work on 2.4.0 firmware; instead you will receive a SRSP of 0x6000 (error)

Note:
  this method modifies the Tx power of the IC. The emitted RF power will be slightly less due to matching network, balun (if not a module with range-extender), and antenna. See documentation.

moduleResult_t sysVersion | ( |  | ) |

Retrieves the Module's version information using SYS_VERSION command.

Postcondition:
  zmBuf contains the version structure, starting at SYS_VERSION_RESULT_START_FIELD

moduleResult_t waitForMessage | ( | uint16_t | messageType,
|  | uint8_t | timeoutSecs
| ) |  |

Waits for the specified type of message. Ignores any other messages received. The received message will be in zmBuf[]. If the specified type of message isn't received by timeout then a TIMEOUT error will be returned.

Parameters:

  messageType | the type of message that you are waiting for. Once this message type is received the method will return with a status of SUCCESS.
  timeoutSecs | how many seconds to wait for the desired message type

Note:
  If you need to receive messages in the meantime then return control to application instead. This is enabled by compile options in the various files. For example, in afSendData, define AF_DATA_CONFIRM_HANDLED_BY_APPLICATION.

How often to check that the module has a message

moduleResult_t zbGetDeviceInfo | ( | uint8_t | dip | ) |

Retrieves the specified Device Information Property (DIP) from the Module.

Parameters:

  dip | the device information property to retrieve

Postcondition:
  zmBuf holds the requested DIP, LSB first, starting at SRSP_DIP_VALUE_FIELD

moduleResult_t zbWriteConfiguration | ( | uint8_t | zcd,
|  | uint8_t | zcdLength,
|  | uint8_t * | data
| ) |  |

Private utility method to write configuration data to the Module

Parameters:

  zcd | the Zigbee configuration data ID
  zcdLength | the length of above
  data | an array containing the data to write.

Note:
  All ZB_WRITE_CONFIGURATION commands take approx. 3.5mSec between SREQ & SRSP; presumably to write to flash inside the Module.

## Variable Documentation

uint8_t zmBuf[ZIGBEE_MODULE_BUFFER_SIZE]

    This buffer will hold the transmitted messages and received SRSP Payload after sendMessage() was

called. If fragmentation support is not required then this can be smaller, e.g. 100B.