Overview

To write an application for the Texas Instruments SimpleLink CC13x2 / CC26x2 Software Development Kit you first need to understand that the embedded system for the CC13x2/CC26x2 is organized as follows

The functions defined in zstackapi.h are functions that communicate with the Z-Stack image through OsalPort messaging. If an immediate response, not over the air, is expected, the function will block for the response message.

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

Register one or more Zigbee Device Endpoints by calling Zstackapi_AfRegisterReq().
Register for Z-Stack 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 Z-Stack 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 Z-Stack 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 OsalPort message.

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

Z-Stack API

System Messages - Configuration and miscellaneous commands
Device Control
The following group of APIs allow the application control the device in a Zigbee network: network discovery, device start, and control routing.
APS Inferace
The APS group table is a link list defined with allocated RAM in the Z-Stack 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 ti_zstack_config.h (Z-Stack Thread Image), if this value is changed the Z-Stack Thread image must be recompiled and the Group table will take up more space in NV.
Application Framework (AF)
The Application Framework layer (withing the Z-Stack 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 endpoints (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.
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.
Security Interface - Network and Link Key access commands
Base Device Behavior Interface - Commissioning procedures through the Zigbee BDB Specification

ZStack Indications (callbacks)

The following messages will be delivered to your application through an OsalPort 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 OsalPort 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 OsalPort 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 OsalPort 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

ZCL Modules

ZCL - All ZCL clusters IDs, common functions/typedefs
ZCL General ZCL clusters macros, typedefs, and functions for general device types
ZCL Closures ZCL cluster macros, typedefs, and functions for closure device types
ZCL Safety and Security ZCL cluster macros, typedefs, and functions for safety and security device types
ZCL Green Power Operation of the ZCL Green Power feature
ZCL Over the Air Macros, typedefs, and functions for the OTA cluster
ZCL Porting functions - Functions needed by ZCL to communication with the Z-Stack Thread.

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.