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
af.h File Reference

public methods for af.c More...

`#include "application_configuration.h"`
`#include "module_errors.h"`
`#include <stdint.h>`

## Macros
#define | AF_MAC_ACK 0x00
#define | AF_APS_ACK 0x10
#define | AF_INCOMING_MESSAGE_CLUSTER_LSB_FIELD (SRSP_PAYLOAD_START+2)
#define | AF_INCOMING_MESSAGE_CLUSTER_MSB_FIELD (SRSP_PAYLOAD_START+3)
#define | AF_INCOMING_MESSAGE_CLUSTER() (CONVERT_TO_INT(zmBuf[AF_INCOMING_MESSAGE_CLUSTER_LSB_FIELD], zmBuf[AF_INCOMING_MESSAGE_CLUSTER_MSB_FIELD]))
#define | AF_INCOMING_MESSAGE_SHORT_ADDRESS_LSB_FIELD (SRSP_PAYLOAD_START+4)
#define | AF_INCOMING_MESSAGE_SHORT_ADDRESS_MSB_FIELD (SRSP_PAYLOAD_START+5)
#define | AF_INCOMING_MESSAGE_SHORT_ADDRESS() (CONVERT_TO_INT(zmBuf[AF_INCOMING_MESSAGE_SHORT_ADDRESS_LSB_FIELD], zmBuf[AF_INCOMING_MESSAGE_SHORT_ADDRESS_MSB_FIELD]))
#define | AF_INCOMING_MESSAGE_LQI_FIELD (SRSP_PAYLOAD_START+9)
#define | AF_INCOMING_MESSAGE_PAYLOAD_LEN_FIELD (SRSP_PAYLOAD_START+16)
#define | AF_INCOMING_MESSAGE_PAYLOAD_START_FIELD (SRSP_PAYLOAD_START+17)
#define | IS_AF_INCOMING_MESSAGE() (CONVERT_TO_INT(zmBuf[SRSP_CMD_LSB_FIELD], zmBuf[SRSP_CMD_MSB_FIELD]) == AF_INCOMING_MSG)
#define | AF_INCOMING_MESSAGE_PAYLOAD_LEN (zmBuf[AF_INCOMING_MESSAGE_PAYLOAD_LEN_FIELD])
#define | AF_INCOMING_MESSAGE_EXT_CLUSTER_LSB_FIELD (SRSP_PAYLOAD_START+2)
#define | AF_INCOMING_MESSAGE_EXT_CLUSTER_MSB_FIELD (SRSP_PAYLOAD_START+3)
#define | AF_INCOMING_MESSAGE_EXT_CLUSTER() (CONVERT_TO_INT(zmBuf[AF_INCOMING_MESSAGE_EXT_CLUSTER_LSB_FIELD], zmBuf[AF_INCOMING_MESSAGE_EXT_CLUSTER_MSB_FIELD]))
#define | AF_INCOMING_MESSAGE_EXT_ADDRESSING_MODE_FIELD (SRSP_PAYLOAD_START+4)
#define | AF_INCOMING_MESSAGE_EXT_SHORT_ADDRESS_LSB_FIELD (SRSP_PAYLOAD_START+5)
#define | AF_INCOMING_MESSAGE_EXT_SHORT_ADDRESS_MSB_FIELD (SRSP_PAYLOAD_START+6)
#define | AF_INCOMING_MESSAGE_EXT_SHORT_ADDRESS() (CONVERT_TO_INT(zmBuf[AF_INCOMING_MESSAGE_EXT_SHORT_ADDRESS_LSB_FIELD], zmBuf[AF_INCOMING_MESSAGE_EXT_SHORT_ADDRESS_MSB_FIELD]))
#define | AF_INCOMING_MESSAGE_EXT_ADDRESS_START_FIELD (SRSP_PAYLOAD_START+5)
#define | AF_INCOMING_MESSAGE_EXT_LQI_FIELD (SRSP_PAYLOAD_START+18)
#define | AF_INCOMING_MESSAGE_EXT_TIMESTAMP_START_FIELD (SRSP_PAYLOAD_START+20)
#define | AF_INCOMING_MESSAGE_EXT_PAYLOAD_LEN_LSB_FIELD (SRSP_PAYLOAD_START+25)
#define | AF_INCOMING_MESSAGE_EXT_PAYLOAD_LEN_MSB_FIELD (SRSP_PAYLOAD_START+26)
#define | AF_INCOMING_MESSAGE_EXT_PAYLOAD_START_FIELD (SRSP_PAYLOAD_START+27)
#define | AF_INCOMING_MESSAGE_EXT_LENGTH() (CONVERT_TO_INT(zmBuf[AF_INCOMING_MESSAGE_EXT_PAYLOAD_LEN_LSB_FIELD], zmBuf[AF_INCOMING_MESSAGE_EXT_PAYLOAD_LEN_MSB_FIELD]))
#define | IS_AF_INCOMING_MESSAGE_EXT() (CONVERT_TO_INT(zmBuf[SRSP_CMD_LSB_FIELD], zmBuf[SRSP_CMD_MSB_FIELD]) == AF_INCOMING_MSG_EXT)
#define | AF_DATA_RETRIEVE_SRSP_STATUS_FIELD (SRSP_PAYLOAD_START)
#define | AF_DATA_RETRIEVE_SRSP_LENGTH_FIELD (SRSP_PAYLOAD_START+1)
#define | AF_DATA_RETRIEVE_SRSP_PAYLOAD_START_FIELD (SRSP_PAYLOAD_START+2)
#define | AF_DATA_CONFIRM_STATUS_FIELD (SRSP_PAYLOAD_START)
#define | AF_DATA_CONFIRM_ENDPOINT_FIELD (SRSP_PAYLOAD_START+1)
#define | AF_DATA_CONFIRM_TRANS_ID_FIELD (SRSP_PAYLOAD_START+2)
#define | AF_DATA_CONFIRM_STATUS (zmBuf[AF_DATA_CONFIRM_STATUS_FIELD])
#define | AF_DATA_CONFIRM_TRANS_ID (zmBuf[AF_DATA_CONFIRM_TRANS_ID_FIELD])
#define | DESTINATION_ADDRESS_MODE_SHORT 2
#define | DESTINATION_ADDRESS_MODE_LONG 3
#define | INTRA_PAN 0
#define | AF_DATA_REQUEST_MAX_PAYLOAD_LENGTH MAXIMUM_PAYLOAD_LENGTH
#define | AF_DATA_REQUEST_EXT_MAX_PAYLOAD_LENGTH 230
#define | MAXIMUM_AF_DATA_RETRIEVE_PAYLOAD_LENGTH 248
#define | AF_DATA_REQUEST_EXT_MAX_TOTAL_PAYLOAD_LENGTH 600

## Functions
uint8_t | getTransactionSequenceNumber ()
moduleResult_t | afRegisterApplication (struct applicationConfiguration ac)
moduleResult_t | afRegisterGenericApplication ()
moduleResult_t | afSendData (uint8_t destinationEndpoint, uint8_t sourceEndpoint, uint16_t destinationShortAddress, uint16_t clusterId, uint8_t *data, uint8_t dataLength)
moduleResult_t | afSendDataExtended (uint8_t destinationEndpoint, uint8_t sourceEndpoint, uint8_t *destinationAddress, uint8_t destinationAddressMode, uint16_t clusterId, uint8_t *data, uint16_t dataLength)
moduleResult_t | afSendDataExtendedShort (uint8_t _destinationEndpoint, uint8_t _sourceEndpoint, uint16_t _destinationShortAddress, uint16_t _clusterId, uint8_t *_data, uint16_t _dataLength)
moduleResult_t | retrieveExtendedMessage (uint8_t *ts, uint16_t length, uint8_t *destinationPtr)
int16_t | printAfIncomingMsgHeader (uint8_t *srsp)
void | printAfIncomingMsgHeaderNames ()
moduleResult_t | afSetAckMode (uint8_t ackMode)

## Detailed Description

public methods for af.c

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 afRegisterApplication | ( | struct applicationConfiguration | ac | ) |

Configures the Module for our application. Sets which profileId, etc. we're using as well as binding information FOR EACH ENDPOINT Using the AF/ZDO interface, you can have more than one endpoint. Recommended not to exceed 10 endpoints.

Parameters:

  ac | the applicationConfiguration to register. Endpoint must NOT be zero.

Precondition:
  Module was initialized and ZCD_NV_LOGICAL_TYPE has been set (COORDINATOR/ROUTER/END_DEVICE).

Returns:
  MODULE_SUCCESS if success, else an error code

Postcondition:
  can now use afStartApplication()

Note:
  this method does not check whether the endpoint being registered has already been registered - it is up to the application to manage that.

See also:
  applicationConfiguration

moduleResult_t afRegisterGenericApplication | ( |  | ) |

    Configures the Module for a "generic" application: one endpoint, no binding or fancy stuff.

Sets which endpoint, profileId, etc. we're using as well as binding information

Returns:
  MODULE_SUCCESS if success, else an error code

See also:
  afRegisterApplication()

moduleResult_t afSendData | ( | uint8_t | destinationEndpoint,
|  | uint8_t | sourceEndpoint,
|  | uint16_t | destinationShortAddress,
|  | uint16_t | clusterId,
|  | uint8_t * | data,
|  | uint8_t | dataLength
| ) |  |

    Sends a message to another device over the Zigbee network using the AF command AF_DATA_REQUEST.

Parameters:

  destinationEndpoint | which endpoint to send this to.
  sourceEndpoint | which endpoint this message originated from on our device
  destinationShortAddress | the short address of the destination, or ALL_DEVICES or ALL_ROUTERS_AND_COORDINATORS to broadcast the message.
  clusterId | which cluster this message is for. User definable. Zigbee supports up to 2^16 clusters. A cluster is typically a particular command, e.g. "turn on lights" or "get temperature". If using a predefined Zigbee Alliance Application Profile then this cluster will follow the Zigbee Cluster Library.
  data | is the data to send.
  dataLength | is how many bytes of data to send. Must be nonzero and less than MAXIMUM_PAYLOAD_LENGTH.

Note:
  On a coordinator in a trivial test setup, it takes approximately 10mSec from sending AF_DATA_REQUEST to when we receive AF_DATA_CONFIRM.
  When sending data, three things happen:
  1. AF_DATA_REQUEST sent to module.
  2. Module sends back AF_DATA_REQUEST SRSP to indicate the message was received.
  3. Once message was delivered, Module sends back AF_DATA_CONFIRM. For simplicity, this library function will use a blocking wait to wait for the AF_DATA_CONFIRM. Define AF_DATA_CONFIRM_HANDLED_BY_APPLICATION if checking for AF_DATA_CONFIRM messages in the application instead of this method. Doing it in the application is faster, but requires more code.
  `transactionSequenceNumber` is an optional user-definable reference number to match AF_DATA_REQUEST messages with AF_DATA_CONFIRM messages.
  The Module will automatically require an ACK from the next device on the route when sending data. To require an ACK from the final destination, use afSetAckMode to set acknowledgment mode to AF_APS_ACK at the expense of increased network traffic.
  The `radius` is the maximum number of hops that this packet can travel through before it will be dropped and should be set to the maximum number of hops expected in the network.
  adjust AF_DATA_CONFIRM_TIMEOUT based on network size, number of hops, etc.

Precondition:
  the application was started successfully
  there is another device on the network with short address of `destinationShortAddress` and that device has successfully started its application.

Postcondition:
  We will receive a AF_DATA_REQUEST_SRSP regardless of whether the message was successfully sent or not.
  we will receive a AF_DATA_CONFIRM if the message was successfully sent.

moduleResult_t afSendDataExtended | ( | uint8_t | destinationEndpoint,
|  | uint8_t | sourceEndpoint,
|  | uint8_t * | destinationAddress,
|  | uint8_t | destinationAddressMode,
|  | uint16_t | clusterId,
|  | uint8_t * | data,
|  | uint16_t | dataLength
| ) |  |

    Sends a message using extended messaging. This is more flexible and allows for long addressing.

Parameters:

  destinationLongAddress | If using short addressing then the first two bytes are the short address, LSB first. Remaining 6 bytes are don't care. If using long addressing then this is the 8 byte MAC, and LSB first.
  destinationAddressMode | Either DESTINATION_ADDRESS_MODE_LONG or DESTINATION_ADDRESS_MODE_SHORT

See also:
  afSendData for description of remaining fields.

moduleResult_t afSendDataExtendedShort | ( | uint8_t | _destinationEndpoint,
|  | uint8_t | _sourceEndpoint,
|  | uint16_t | _destinationShortAddress,
|  | uint16_t | _clusterId,
|  | uint8_t * | _data,
|  | uint16_t | _dataLength
| ) |  |

    Simple wrapper function to send extended messages via short address.

See also:
  afSendData for description of these fields.

moduleResult_t afSetAckMode | ( | uint8_t | ackMode | ) |

    Configures the module interface for either MAC level acking or application level acking.

This setting is used in afSendData() and afSendDataExt().

uint8_t getTransactionSequenceNumber | ( |  | ) |

    Returns the current transactionSequenceNumber. This is included in afSendData, and reported in

AF_DATA_CONFIRM. Use this to match the AF_DATA_CONFIRM with calls to afSendData().

Returns:
  the current transactionSequenceNumber - this was sent with the last call to afSendData or afSendDataExt.

Note:
  this is implemented as a method for modularity; to keep other code from changing this variable.

int16_t printAfIncomingMsgHeader | ( | uint8_t * | srsp | ) |

    Displays the header information in an AF_INCOMING_MSG.

Parameters:

  srsp | a pointer to the buffer containing the message

Returns:
  0 if success, -1 if not a AF_INCOMING_MSG.

void printAfIncomingMsgHeaderNames | ( |  | ) |

Displays the names of the fields that correspond with printAfIncomingMsgHeader

moduleResult_t retrieveExtendedMessage | ( | uint8_t * | ts,
|  | uint16_t | length,
|  | uint8_t * | destinationPtr
| ) |  |

    Retrieves all bytes of an AF_INCOMING_MESSAGE_EXT using multiple calls to AF_DATA_RETRIEVE as necessary.

Precondition:
  destinationPtr points to memory large enough to contain the entire message (500B?)

Parameters:

  ts | the timestamp of the message to retrieve.
  destinationPtr | where to copy the bytes
  length | of message payload to retrieve. Must be less than AF_DATA_REQUEST_EXT_MAX_TOTAL_PAYLOAD_LENGTH.

Postcondition:
  message will be copied into destinationPtr.