Z-Stack TI-RTOS API

Date

2015-02-12 12:13:13 -0800 (Thu, 12 Feb 2015)

Revision

42527

Overview

To write an application for the Texas Instruments CC2630/CC2650 Z-Stack SDK you first need to understand that the embedded system for the CC2630/CC2650 is divided into 2 seperate images.

Each image is maintained as seperate projects that are built and downloaded to the CC2630/CC2650 seperately.

The functions defined in zstackapi.h are functions that communicate with the ZStack image through ICall messages. If an immediate response, not over the air, is expected, the function will block for the response ICall message.

To setup communicate with the ZStack thread, your application should do the following initialization(simplified):

• Register one or more Zigbee Device Endpoints by calling Zstackapi_AfRegisterReq().
• Register for ZStack Callback (asynchronous) messages by calling Zstackapi_DevZDOCBReq() with the wanted callbacks. For example, if you would like to receive device state change notifications, you will have to set the has_devStateChange and devStateChange fields to true in a zstack_devZDOCBReq_t, then call Zstackapi_DevZDOCBReq().
• Write ZStack parameters by calling Zstackapi_sysConfigWriteReq() with the wanted parameters. Example parameters are channel mask, PAN ID, poll rates, timeouts, etc...
• Call Zstackapi_DevStartReq() to start the ZStack Thread's automatic joining process.

When the joining process is complete, you'll receive a zstackmsg_CmdIDs_DEV_STATE_CHANGE_IND message with a state of:

• zstack_DevState_DEV_ZB_COORD - the device started as a coordinator.
• zstack_DevState_DEV_ROUTER - the device joined as a router.
• zstack_DevState_DEV_END_DEVICE - the device joined as an end device.

You should then call zclport_getDeviceInfo(), or Zstackapi_sysNwkInfoReadReq() if your application isn't a ZCL project, to retrieve the device's joined network parameters.

You're free to do device discovery through ZDO commands (ie. Zstackapi_ZdoMatchDescReq()) and send data either through ZCL commands or by calling Zstackapi_AfDataReq() to send application proprietary messages.

Once you've registed an endpoint, your application will recieve any data message addressed to that endpoint as an AF Incoming Data Indication [zstackmsg_afIncomingMsgInd_t with a message event of zstackmsg_CmdIDs_AF_INCOMING_MSG_IND] through an ICall message.

Also, any indications or response message that you have signed up for using Zstackapi_DevZDOCBReq() will be delivered to your application as an ICall message. For example, the Device State Change message [zstackmsg_devStateChangeInd_t with a message event of zstackmsg_CmdIDs_DEV_STATE_CHANGE_IND].

ZStack API

• System Messages - Configuration and miscellaneous commands
  • Zstackapi_sysVersionReq()
  • Zstackapi_sysConfigReadReq()
  • Zstackapi_sysConfigWriteReq()
  • Zstackapi_sysSetTxPowerReq()
  • Zstackapi_sysNwkInfoReadReq()
  • Zstackapi_sysForceLinkStatusReq()
  • Zstackapi_SetNwkFrameFwdNotificationReq()
    
    
• Device Control
  The following group of APIs allow the application control the device in a Zigbee network: network discovery, device start, and control routing.
  • Zstackapi_DevStartReq()
  • Zstackapi_DevNwkDiscReq()
  • Zstackapi_DevJoinReq()
  • Zstackapi_DevZDOCBReq()
  • Zstackapi_DevNwkRouteReq()
  • Zstackapi_DevNwkCheckRouteReq()
  • Zstackapi_DevUpdateNeighborTxCostReq()
  • Zstackapi_DevForceNetworkSettingsReq()
  • Zstackapi_DevForceNetworkUpdateReq()
  • Zstackapi_DevForceMacParamsReq()
    
    
• APS Inferace
  The APS group table is a link list defined with allocated RAM in the ZStack Thread, so as groups are added to the table the amount of heap used increases. The maximum table size can be changed by adjusting APS_MAX_GROUPS in f8wConfig.cfg (ZStack Thread Image), if this value is changed the ZStack Thread image must be recompiled and the Group table will take up more space in NV.
  • Zstackapi_ApsRemoveGroupReq()
  • Zstackapi_ApsRemoveAllGroupsReq()
  • Zstackapi_ApsFindAllGroupsReq()
  • Zstackapi_ApsFindGroupReq()
  • Zstackapi_ApsAddGroupReq()
  • Zstackapi_ApsCountAllGroupsReq()
    
    
• Application Framework (AF)
  The Application Framework layer (withing the ZStack Thread) is the over-the-air data interface to the APS layer. This interface sends data out over the air (through the APS and NWK) layers. This layer is also the endpoint multiplexer for incoming data messages.
  Each device is a node in the Zigbee. Each node has a long and short address, the short address of the node is used by other nodes to send it data. Each node has 241 endpoint (0 reserved, 1-240 application assigned). Each endpoint is separately addressable; when a device sends data it must specify the destination node�s short address and the endpoint that will receive that data.
  An application must register one or more endpoints to send and receive data in a Zigbee network.
  
  • Zstackapi_AfRegisterReq()
  • Zstackapi_AfUnRegisterReq()
  • Zstackapi_AfDataReq()
  • Zstackapi_AfConfigGetReq()
  • Zstackapi_AfConfigSetReq()
    
    
• Zigbee Device Objects (ZDO)
  This section enumerates all the function calls provided by the ZDO layer that are necessary for the implementation of all commands defined in ZigBee Device Profile (ZDP).
  ZDP describes how general ZigBee Device features are implemented within ZDO. It defines Device Description and Clusters which employ command. Through the definition of messages in command structure, ZDP provides the following functionality to the ZDO and applications: Device and Service Discovery; End Device Bind, Bind and Unbind Service; and Network Management Service. Device discovery is the process for a ZigBee device to discover other ZigBee Devices. One example of device discovery is the NWK address request which is broadcast and carries the known IEEE address as data payload. The device of interest should respond and inform its NWK address. Service discovery provides the ability for a device to discover the services offered by other ZigBee devices on the PAN. It utilizes various descriptors to specify device capabilities.
  End device bind, bind and unbind services offer ZigBee devices the binding capabilities. Typically, binding is used during the installation of a network when the user needs to bind controlling devices with devices being controlled, such as switches and lights. Particularly, end device bind supports a simplified binding method where user input is utilized to identify controlling/controlled device pairs. Bind and unbind services provide the ability for creation and deletion of binding table entry that map control messages to their intended destination.
  Network management services provide the ability to retrieve management information from the devices, including network discovery results, routing table contents, link quality to neighbor nodes, and binding table contents. It also provides the ability to control the network association by disassociating devices from the PAN. Network management services are designed majorly for user or commissioning tools to manage the network.
  
  • Zstackapi_ZdoNwkAddrReq()
  • Zstackapi_ZdoIeeeAddrReq()
  • Zstackapi_ZdoNodeDescReq()
  • Zstackapi_ZdoPowerDescReq()
  • Zstackapi_ZdoSimpleDescReq()
  • Zstackapi_ZdoActiveEndpointReq()
  • Zstackapi_ZdoMatchDescReq()
  • Zstackapi_ZdoComplexDescReq()
  • Zstackapi_ZdoServerDiscReq()
  • Zstackapi_ZdoEndDeviceBindReq()
  • Zstackapi_ZdoBindReq()
  • Zstackapi_ZdoUnbindReq()
  • Zstackapi_ZdoSetBindUnbindAuthAddrReq()
  • Zstackapi_ZdoMgmtNwkDiscReq()
  • Zstackapi_ZdoMgmtLqiReq()
  • Zstackapi_ZdoMgmtRtgReq()
  • Zstackapi_ZdoMgmtBindReq()
  • Zstackapi_ZdoMgmtLeaveReq()
  • Zstackapi_ZdoMgmtDirectJoinReq()
  • Zstackapi_ZdoMgmtPermitJoinReq()
  • Zstackapi_ZdoMgmtNwkUpdateReq()
  • Zstackapi_ZdoDeviceAnnounceReq()
  • Zstackapi_ZdoUserDescSetReq()
  • Zstackapi_ZdoUserDescReq()
    
    
• Security Interface - Network and Link Key access commands
  • Zstackapi_secNwkKeyGetReq()
  • Zstackapi_secNwkKeySetReq()
  • Zstackapi_secNwkKeyUpdateReq()
  • Zstackapi_secNwkKeySwitchReq()
  • Zstackapi_secApsLinkKeyGetReq()
  • Zstackapi_secApsLinkKeySetReq()
  • Zstackapi_secApsLinkKeyRemoveReq()
  • Zstackapi_secApsRemoveReq()
    
    
• Base Device Behavior Interface - Commissioning procedures specified by Zigbee BDB Specification
  • Zstackapi_bdbStartCommissioningReq()
  • Zstackapi_bdbSetIdentifyActiveEndpointReq()
  • Zstackapi_bdbGetIdentifyActiveEndpointReq()
  • Zstackapi_bdbStopInitiatorFindingBindingReq()
  • Zstackapi_bdbGetZCLFrameCounterReq()
  • Zstackapi_bdbResetLocalActionReq()
  • Zstackapi_bdbSetAttributesReq()
  • Zstackapi_bdbGetAttributesReq()
  • Zstackapi_bdbGetFBInitiatorStatusReq()
  • Zstackapi_bdbGenerateInstallCodeCRCReq()
  • Zstackapi_bdbRepAddAttrCfgRecordDefaultToListReq()
  • Zstackapi_bdbRepChangedAttrValueReq()
  • Zstackapi_bdbAddInstallCodeReq()
  • Zstackapi_bdbTouchLinkTargetEnableCommissioningReq()
  • Zstackapi_bdbTouchLinkTargetDisableCommissioningReq()
  • Zstackapi_bdbTouchLinkTargetGetTimerReq()
  • Zstackapi_bdbSetActiveCentralizedLinkKeyReq()
  • Zstackapi_bdbCBKETCLinkKeyExchangeAttemptReq()
  • Zstackapi_bdbNwkDescFreeReq()
  • Zstackapi_bdbTouchlinkSetAllowStealingReq()
  • Zstackapi_bdbTouchlinkGetAllowStealingReq()
  • Zstackapi_bdbZedAttemptRecoverNwkReq()

ZStack Indications (callbacks)

The following messages will be delivered to your application through an ICall message after you register at least one endpoint with Zstackapi_AfRegisterReq(), you must call Zstackapi_freeIndMsg() to free the message when you are done processing:

• zstackmsg_CmdIDs_AF_DATA_CONFIRM_IND - zstackmsg_afDataConfirmInd_t
• zstackmsg_CmdIDs_AF_INCOMING_MSG_IND - zstackmsg_afIncomingMsgInd_t

The following messages will be delivered to your application through an ICall message after you request them by setting the correct fields (has and flag) to 'true' in zstack_devZDOCBReq_t and calling Zstackapi_DevZDOCBReq(), you must call Zstackapi_freeIndMsg() to free the message when you are done processing:

• zstackmsg_CmdIDs_ZDO_DEVICE_ANNOUNCE - zstackmsg_zdoDeviceAnnounceReq_t
• zstackmsg_CmdIDs_ZDO_NWK_ADDR_RSP - zstackmsg_zdoNwkAddrRspInd_t
• zstackmsg_CmdIDs_ZDO_IEEE_ADDR_RSP - zstackmsg_zdoIeeeAddrRspInd_t
• zstackmsg_CmdIDs_ZDO_NODE_DESC_RSP - zstackmsg_zdoNodeDescRspInd_t
• zstackmsg_CmdIDs_ZDO_POWER_DESC_RSP - zstackmsg_zdoPowerDescRspInd_t
• zstackmsg_CmdIDs_ZDO_SIMPLE_DESC_RSP - zstackmsg_zdoSimpleDescRspInd_t
• zstackmsg_CmdIDs_ZDO_ACTIVE_EP_RSP - zstackmsg_zdoActiveEndpointsRspInd_t
• zstackmsg_CmdIDs_ZDO_MATCH_DESC_RSP - zstackmsg_zdoMatchDescRspInd_t
• zstackmsg_CmdIDs_ZDO_USER_DESC_RSP - zstackmsg_zdoUserDescRspInd_t
• zstackmsg_CmdIDs_ZDO_SERVER_DISC_RSP - zstackmsg_zdoServerDiscoveryRspInd_t
• zstackmsg_CmdIDs_ZDO_END_DEVICE_BIND_RSP - zstackmsg_zdoEndDeviceBindRspInd_t
• zstackmsg_CmdIDs_ZDO_BIND_RSP - zstackmsg_zdoBindRspInd_t
• zstackmsg_CmdIDs_ZDO_UNBIND_RSP - zstackmsg_zdoUnbindRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_NWK_DISC_RSP - zstackmsg_zdoMgmtNwkDiscRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_LQI_RSP - zstackmsg_zdoMgmtLqiRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_RTG_RSP - zstackmsg_zdoMgmtRtgRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_BIND_RSP - zstackmsg_zdoMgmtBindRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_LEAVE_RSP - zstackmsg_zdoMgmtLeaveRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_DIRECT_JOIN_RSP - zstackmsg_zdoMgmtDirectJoinRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_PERMIT_JOIN_RSP - zstackmsg_zdoMgmtPermitJoinRspInd_t
• zstackmsg_CmdIDs_ZDO_MGMT_NWK_UPDATE_NOTIFY - zstackmsg_zdoMgmtNwkUpdateNotifyInd_t
• zstackmsg_CmdIDs_ZDO_SRC_RTG_IND - zstackmsg_zdoSrcRtgInd_t
• zstackmsg_CmdIDs_ZDO_CONCENTRATOR_IND - zstackmsg_zdoCncntrtrInd_t
• zstackmsg_CmdIDs_ZDO_NWK_DISC_CNF - zstackmsg_zdoNwkDiscCnf_t
• zstackmsg_CmdIDs_ZDO_BEACON_NOTIFY_IND - zstackmsg_zdoBeaconNotifyInd_t
• zstackmsg_CmdIDs_ZDO_JOIN_CNF - zstackmsg_zdoJoinConf_t
• zstackmsg_CmdIDs_ZDO_LEAVE_CNF - zstackmsg_zdoLeaveCnf_t
• zstackmsg_CmdIDs_ZDO_LEAVE_IND - zstackmsg_zdoLeaveInd_t
• zstackmsg_CmdIDs_AF_REFLECT_ERROR_IND - zstackmsg_afReflectErrorInd_t
• zstackmsg_CmdIDs_DEV_STATE_CHANGE_IND - zstackmsg_devStateChangeInd_t
• zstackmsg_CmdIDs_ZDO_TC_DEVICE_IND - zstackmsg_zdoTcDeviceInd_t
• zstackmsg_CmdIDs_DEV_PERMIT_JOIN_IND - zstackmsg_devPermitJoinInd_t

The following messages will be delivered to your application through an ICall message after a request to perform any BDB commissioning process, for instance, Zstackapi_bdbStartCommissioningReq calls will trigger zstackmsg_CmdIDs_BDB_NOTIFICATION on the requested commissioning methods, you must call Zstackapi_freeIndMsg() to free the message when you are done processing:

• zstackmsg_CmdIDs_BDB_NOTIFICATION - zstackmsg_bdbNotificationInd_t
• zstackmsg_CmdIDs_BDB_IDENTIFY_TIME_CB - zstackmsg_bdbIdentifyTimeoutInd_t
• zstackmsg_CmdIDs_BDB_BIND_NOTIFICATION_CB - zstackmsg_bdbBindNotificationInd_t
• zstackmsg_CmdIDs_BDB_CBKE_TC_LINK_KEY_EXCHANGE_IND - zstack_bdbCBKETCLinkKeyExchangeAttemptReq_t
• zstackmsg_CmdIDs_BDB_FILTER_NWK_DESCRIPTOR_IND - zstackmsg_bdbFilterNwkDescriptorInd_t
• zstackmsg_CmdIDs_BDB_TOUCHLINK_TARGET_ENABLE_IND - zstackmsg_bdbTouchLinkTargetEnableInd_t

The following messages will be delivered to your application through an ICall message when GP messages are process by the stack and must be process by Green Power Proxy or sink application side, which by default are already handled by example apps to the respective green power application. you must call Zstackapi_freeIndMsg() to free the message when you are done processing:

• zstackmsg_CmdIDs_GP_DATA_IND - zstackmsg_gpDataInd_t
• zstackmsg_CmdIDs_GP_SECURITY_REQ - zstackmsg_gpSecReq_t
• zstackmsg_CmdIDs_GP_CHECK_ANNCE - zstackmsg_gpCheckAnnounce_t
• zstackmsg_CmdIDs_SYS_NWK_FRAME_FWD_NOTIFICATION - zstackmsg_nwkFrameFwdNotification_t
• 
  
  
  
  

Application Helper Modules

• Utilities - Middleware Timer/Clock and integer-to-string functions.
• ZCL Porting functions - Functions needed by ZCL to communication with the ZStack Thread.
• LED Support - Middleware to control the development board LEDs.
• LCD Support - Middleware to control the development board LCD.
• Key Press Support - Middleware to setup and receive key press indications.

---

Copyright 2014 - 2015 Texas Instruments Incorporated. All rights reserved.

IMPORTANT: Your use of this Software is limited to those specific rights granted under the terms of a software license agreement between the user who downloaded the software, his/her employer (which must be your employer) and Texas Instruments Incorporated (the "License"). You may not use this Software unless you agree to abide by the terms of the License. The License limits your use, and you acknowledge, that the Software may not be modified, copied or distributed unless embedded on a Texas Instruments microcontroller or used solely and exclusively in conjunction with a Texas Instruments radio frequency transceiver, which is integrated into your product. Other than for the foregoing purpose, you may not use, reproduce, copy, prepare derivative works of, modify, distribute, perform, display or sell this Software and/or its documentation for any purpose.

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 TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES 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.

Should you have any questions regarding your right to use this Software, contact Texas Instruments Incorporated at www.TI.com.