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
simple_api.c File Reference

Methods that implement the Simple Application Programming Interface (Simple API). More...

`#include "simple_api.h"`
`#include "module.h"`
`#include "application_configuration.h"`
`#include "../HAL/hal.h"`
`#include "../Common/utilities.h"`
`#include <string.h>`
`#include "module_errors.h"`
`#include "zm_phy_spi.h"`
`#include <stdint.h>`

## Macros
#define | METHOD_SAPI_REGISTER_APPLICATION 0x4100
#define | METHOD_SAPI_REGISTER_GENERIC_APPLICATION 0x4200
#define | ZB_APP_REGISTER_REQUEST_PAYLOAD_LEN 9
#define | METHOD_SAPI_START_APPLICATION 0x4300
#define | ZB_APP_START_REQUEST_PAYLOAD_LEN 0
#define | ZB_START_CONFIRM_TIMEOUT 5
#define | METHOD_SAPI_SET_JOINING_PERMISSIONS 0x4400
#define | ZB_PERMIT_JOINING_REQUEST_PAYLOAD_LEN 3
#define | METHOD_SAPI_SEND_DATA 0x4500
#define | ZB_SEND_DATA_REQUEST_PAYLOAD_LEN 8
#define | ZB_SEND_DATA_CONFIRM_TIMEOUT 5
#define | MODULE_TYPE_MASK 0x0F
#define | IS_VALID_MODULE_TYPE(x) ((x>=0x20) && (x<=0x24))
#define | METHOD_SAPI_START_MODULE 0x4600

## Functions
moduleResult_t | sapiRegisterApplication (struct applicationConfiguration ac)
moduleResult_t | sapiRegisterGenericApplication ()
moduleResult_t | sapiStartApplication ()
moduleResult_t | sapiSetJoiningPermissions (uint16_t destination, uint8_t timeout)
moduleResult_t | sapiSendData (uint16_t destinationShortAddress, uint16_t clusterId, uint8_t *data, uint8_t dataLength)
moduleResult_t | sapiStartModule (uint8_t deviceType, uint32_t channelMask, uint16_t panId)

## Variables
uint8_t | zmBuf [ZIGBEE_MODULE_BUFFER_SIZE]
uint8_t | sequenceNumber = 0

## Detailed Description

Methods that implement the Simple Application Programming Interface (Simple API).

This Simple API is an easy-to-use interface to configure, send, and receive Zigbee data. This file acts as an interface between the user's application and the Module physical interface, either SPI or UART. Refer to Wiki for more information.

Note:
  For more information, define SIMPLE_API_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: SIMPLE_API_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 sapiRegisterApplication | ( | struct applicationConfiguration | ac | ) |

    Configures the Module for our application.

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

Note:
  Simple API can only register one application.

Parameters:

  the | applicationConfiguration to register.

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

Postcondition:
  can now use sapiStartApplication()

See also:
  applicationConfiguration

moduleResult_t sapiRegisterGenericApplication | ( |  | ) |

    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

See also:
  sapiRegisterApplication()

moduleResult_t sapiSendData | ( | uint16_t | destinationShortAddress,
|  | uint16_t | clusterId,
|  | uint8_t * | data,
|  | uint8_t | dataLength
| ) |  |

    Sends a message to another device over the Zigbee network.

Note:
  On a coordinator in a trivial test setup, it takes approximately 10mSec from sending ZB_SEND_DATA_REQUEST to when we receive ZB_SEND_DATA_CONFIRM.
  `handle` is an optional user-definable reference number to match SEND_DATA_CONFIRM messages with the SEND_DATA_REQUEST message. This can be used to determine which SEND_DATA_REQUEST generated an error.
  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, change MAC_ACK to APS_ACK. The downside is that this increases network traffic.
  The `radius` is the maximum number of hops that this packet can travel through before it will be dropped. Should be set to the maximum number of hops expected in the network.
  adjust ZB_SEND_DATA_CONFIRM_TIMEOUT based on network size, number of hops, etc.

Parameters:

  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 less than MAXIMUM_PAYLOAD_LENGTH.

Precondition:
  sapiStartApplication() was a success, START_CONFIRM received without any errors.
  there is another device on the network with short address of `destinationShortAddress` and that device has successfully started its application using sapiStartApplication().

Postcondition:
  we will receive a ZB_SEND_DATA_CONFIRM if the message was successfully sent.

moduleResult_t sapiSetJoiningPermissions | ( | uint16_t | destination,
|  | uint8_t | timeout
| ) |  |

    Sets the Joining Permissions for this device or other devices.

By default, after a setStartupOptions(CLEAR_CONFIG), joining is set to allow all devices, indefinitely.

Parameters:

  destination | which short address to set joining permissions for, or ALL_ROUTERS_AND_COORDINATORS to set joining permissions for all.
  timeout | how long in seconds to allow permissions, or if set to NO_TIMEOUT then joining will be on indefinitely.

moduleResult_t sapiStartApplication | ( |  | ) |

    Starts the Zigbee stack in the Module using the settings from a previous sapiRegisterApplication().

After this start request process completes, the device is ready to send, receive, and route network traffic.

Note:
  On a coordinator in a trivial test setup, it takes approximately 300mSec between START_REQUEST and receiving START_REQUEST_SRSP and then another 200-1000mSec from when we receive START_REQUEST_SRSP to when we receive START_CONFIRM.
  Set START_CONFIRM_TIMEOUT based on size of your network.

Precondition:
  sapiRegisterApplication() was a success.

Note:
  we will receive a START_CONFIRM if everything was ok. Should always receive a start confirm for a coordinator. Will only receive a start confirm on a router if we could join a zigbee network.

moduleResult_t sapiStartModule | ( | uint8_t | deviceType,
|  | uint32_t | channelMask,
|  | uint16_t | panId
| ) |  |

    Start the Module and join a network, using the Simple API interface.

Parameters:

  deviceType | the type of device we're starting, e.g. ROUTER.
  channelMask | the channelMask we'd like to use. Parameter must be one or more channels 'OR'd together, e.g. (CHANNEL_MASK_13 | CHANNEL_MASK_17 | CHANNEL_MASK_21) for channels 13,17,21. May also be set to ANY_CHANNEL_MASK which will use all channels.
  panId | if you want to use a specific PAN_ID. Otherwise set to ANY_PAN.

Note:
  Example usage is sapiStartModule(ROUTER, CHANNEL_MASK_11 | CHANNEL_MASK_13, ANY_PAN) will start the module to be a router, using channels 11 and 13, on any PAN ID, using no binding.

See also:
  module.c for more information about each of these steps.

## Variable Documentation

uint8_t sequenceNumber = 0

Incremented for each SEND_DATA_REQUEST, wraps around to 0.

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.