ZigBee 3.0 Stack User Guide

Table of Contents

• Preface
  • Organization of this manual
  • Conventions
  • Acronyms and abbreviations
  • Related documents
  • Support resources
  • Trademarks
  • Chip compatibility
• ZigBee overview
  • ZigBee features
  • ZigBee 3.0
  • ZigBee network nodes
  • ZigBee PRO network topology
  • Ideal applications for ZigBee
  • Wireless radio frequency operation
  • Battery-powered components
  • Easy installation and configuration
  • Highly reliable operation
  • Secure operating environment
    • Access control lists
    • Key-based encryption
    • Frame counters
  • Co-existence and interoperability
  • Device types and clusters
    • Clusters
    • Device types
• ZigBee PRO architecture and operation
  • Architectural overview
  • Network level concepts
    • ZigBee nodes
      • Coordinator
      • Router
      • End Device
    • Network topology
    • Neighbor tables
    • Network addressing
    • Network identity
  • Network creation
    • Starting a Network (Coordinator)
      • Set EPID and Coordinator address
      • Select radio channel
      • Set the PAN ID of the network
      • Receive join requests from other devices
    • Joining a network (Routers and End Devices)
      • Search for network
      • Select parent
      • Request joining
      • Receive response
      • Learn network IDs
  • Application level concepts
    • Multiple applications and endpoints
    • Descriptors
      • Simple descriptor
      • Node descriptor
      • Node power descriptor
    • Application profiles
    • Device types
    • Clusters and attributes
    • Discovery
      • Device discovery
      • Service discovery
    • ZigBee Device Objects (ZDO)
  • Network routing
    • Message addressing and propagation
    • Route discovery
    • ‘Many-to-one’ routing
  • Network communications
    • Service discovery
    • Binding
  • Detailed architecture
    • Software levels
      • Application (APL) Layer
      • Network (NWK) layer
      • Physical/Data link layers
• ZigBee Stack Software
  • Software overview
    • ZigBee PRO APIs
    • JCU APIs
  • Summary of API functionality
• Application development overview
  • Development environment and resources
    • Development platform
      • MCUXpresso
    • ZigBee 3.0 SDK
  • Zigbee application support resources
  • Development phases
• Application coding with ZigBee PRO APIs
  • Forming and joining a network
    • Starting the Coordinator
      • Setting the radio channel for the network
      • Setting the Extended PAN ID for the network
      • Accepting join requests from other devices (if enabled)
    • Starting Routers and End Devices
      • Searches for a network to join
      • Selects a network to join
      • Submits a join request to network
      • Records the network’s EPID for application use
      • Router accepts join requests from other devices (if enabled)
    • Pre-determined parents
  • Discovering the network
    • Obtaining network properties
    • Finding compatible endpoints
    • Obtaining and maintaining node addresses
      • Obtaining IEEE address
      • Obtaining network address
    • Obtaining node properties
      • Node descriptor
      • Power descriptor
      • Simple descriptor
      • User Descriptor
      • Complex descriptor
      • Active endpoints
      • Primary discovery cache
      • Servers
    • Maintaining a primary discovery cache
    • Discovering Routes
  • Managing group addresses
  • Binding
    • Setting up bind request server
      • Simultaneous requests
      • Time interval
    • Binding endpoints
    • Unbinding endpoints
    • Accessing binding tables
  • Transferring data
    • Sending data
      • Unicast
      • Broadcast
      • Group multicast
      • Bound transfer
      • Inter-PAN transfer
    • Receiving data
    • Polling for Data
    • Security in data transfers
  • Leaving and rejoining the network
    • Leaving the network
    • Rejoining the network
  • Return codes and extended error handling
  • Implementing ZigBee security
    • Security levels
    • Security key types
    • Setting up ZigBee security
      • Network-level security set-up
      • Application-level security set-up
    • Security key modification
      • Network key modification
      • Application link key modification
  • Using support software features
    • Message queues
      • General queue management
      • Standard stack queues
    • Software timers
      • Setting up timers
      • Operating timers
    • Critical sections and Mutual Exclusion (Mutex)
      • Implementing a critical section
      • Implementing a Mutex
  • Advanced features
    • End device aging
      • Timeout period
      • Keep-alive packets
    • Distributed security networks
    • Filtering packets on LQI Value/Link cost
      • Link cost
      • Packet filtering in operation
      • Packet filtering configuration
    • Device permissions
• ZigBee Device Objects (ZDO) API
  • ZDO API functions
    • Network deployment functions
      • Function page
      • ZPS_eAplZdoStartStack
      • ZPS_vDefaultStack
      • ZPS_eAplZdoGetDeviceType
      • ZPS_eAplZdoDiscoverNetworks
      • ZPS_eAplZdoJoinNetwork
      • ZPS_eAplZdoRejoinNetwork
      • ZPS_eAplZdoDirectJoinNetwork
      • ZPS_eAplZdoOrphanRejoinNetwork
      • ZPS_eAplZdoPermitJoining
      • ZPS_u16AplZdoGetNetworkPanId
      • ZPS_u64AplZdoGetNetworkExtendedPanId
      • ZPS_u8AplZdoGetRadioChannel
      • ZPS_eAplZdoBind
      • ZPS_eAplZdoUnbind
      • ZPS_eAplZdoBindGroup
      • ZPS_eAplZdoUnbindGroup
      • ZPS_ePurgeBindTable
      • ZPS_eAplZdoPoll
      • ZPS_eAplZdoLeaveNetwork
      • ZPS_vNwkNibSetLeaveAllowed
      • ZPS_vNwkNibSetLeaveRejoin
      • ZPS_vSetTablesClearOnLeaveWithoutRejoin
      • ZPS_vNtSetUsedStatus
      • ZPS_vNwkSendNwkStatusCommand
      • ZPS_eAplZdoRegisterZdoLeaveActionCallback
    • Security functions
      • Function page
      • ZPS_vAplSecSetInitialSecurityState
      • ZPS_eAplZdoTransportNwkKey
      • ZPS_eAplZdoSwitchKeyReq
      • ZPS_eAplZdoRequestKeyReq
      • ZPS_eAplZdoAddReplaceLinkKey
      • ZPS_eAplZdoAddReplaceInstallCodes
      • ZPS_eAplZdoRemoveLinkKey
      • ZPS_eAplZdoRemoveDeviceReq
      • ZPS_eAplZdoSetDevicePermission
      • ZPS_bAplZdoTrustCenterSetDevicePermissions
      • ZPS_bAplZdoTrustCenterGetDevicePermissions
      • ZPS_bAplZdoTrustCenterRemoveDevice
      • ZPS_vTcInitFlash
      • ZPS_vSetTCLockDownOverride
      • ZPS_psGetActiveKey
      • ZPS_vTCSetCallback
    • Addressing functions
      • Function page
      • ZPS_u16AplZdoGetNwkAddr
      • ZPS_u64AplZdoGetIeeeAddr
      • ZPS_eAplZdoAddAddrMapEntry
      • ZPS_vPurgeAddressMap
      • ZPS_u16AplZdoLookupAddr
      • ZPS_u64AplZdoLookupIeeeAddr
      • ZPS_u64NwkNibGetMappedIeeeAddr
      • ZPS_u64GetFlashMappedIeeeAddress
      • ZPS_bNwkFindAddIeeeAddr
      • ZPS_vSetOverrideLocalIeeeAddr
      • ZPS_eAplZdoGroupEndpointAdd
      • ZPS_eAplZdoGroupEndpointRemove
      • ZPS_eAplZdoGroupAllEndpointRemove
    • Routing functions
      • Function page
      • ZPS_eAplZdoRouteRequest
      • ZPS_eAplZdoManyToOneRouteRequest
    • Object Handle functions
      • Function page
      • ZPS_pvAplZdoGetAplHandle
      • ZPS_pvAplZdoGetMacHandle
      • ZPS_pvAplZdoGetNwkHandle
      • ZPS_psNwkNibGetHandle
      • ZPS_psAplAibGetAib
      • ZPS_psAplZdoGetNib
      • ZPS_u64NwkNibGetEpid
    • Optional Cluster function
      • Function page
      • ZPS_eAplZdoRegisterZdoFilterCallback
  • ZDO enumerations
    • Security keys (ZPS_teZdoNwkKeyState)
    • Device types (ZPS_teZdoDeviceType)
    • Device permissions (ZPS_teDevicePermissions)
• Application Framework (AF) API
  • AF API functions
    • initialization functions
      • ZPS_eAplAfInit
      • ZPS_vAplAfSetMacCapability
      • ZPS_eAplAibSetApsUseExtendedPanId
      • ZPS_vExtendedStatusSetCallback
      • ZPS_bAppAddBeaconFilter
      • ZPS_eAplFormDistributedNetworkRouter
      • ZPS_eAplInitEndDeviceDistributed
      • ZPS_vAplAfEnableMcpsFilter
      • ZPS_vNwkLinkCostCallbackRegister
    • Data Transfer functions
      • ZPS_eAplAfApsdeDataReq
      • ZPS_eAplAfUnicastDataReq
      • ZPS_eAplAfUnicastIeeeDataReq
      • ZPS_eAplAfUnicastAckDataReq
      • ZPS_eAplAfUnicastIeeeAckDataReq
      • ZPS_eAplAfGroupDataReq
      • ZPS_eAplAfBroadcastDataReq
      • ZPS_eAplAfBoundDataReq
      • ZPS_eAplAfBoundAckDataReq
      • ZPS_eAplAfInterPanDataReq
      • ZPS_u8AplGetMaxPayloadSize
    • Endpoint functions
      • ZPS_vAplAfSetEndpointState
      • ZPS_eAplAfGetEndpointState
      • ZPS_eAplAfSetEndpointDiscovery
      • ZPS_eAplAfGetEndpointDiscovery
    • Descriptor functions
      • ZPS_eAplAfGetNodeDescriptor
      • ZPS_eAplAfGetNodePowerDescriptor
      • ZPS_eAplAfGetSimpleDescriptor
    • Other functions
      • ZPS_vSaveAllZpsRecords
      • ZPS_bAplAfSetEndDeviceTimeout
      • ZPS_eAplAfSendKeepAlive
  • AF structures
    • Descriptor structures
      • ZPS_tsAplAfNodeDescriptor
      • ZPS_tsAplAfNodePowerDescriptor
      • ZPS_tsAplAfSimpleDescriptor
    • Event structures
      • ZPS_tsAfEvent
      • ZPS_tuAfEventData
      • ZPS_tsAfDataIndEvent
      • ZPS_tsAfDataConfEvent
      • ZPS_tsAfDataAckEvent
      • ZPS_tsAfNwkFormationEvent
      • ZPS_tsAfNwkJoinedEvent
      • ZPS_tsAfNwkJoinFailedEvent
      • ZPS_tsAfNwkDiscoveryEvent
      • ZPS_tsAfNwkJoinIndEvent
      • ZPS_tsAfNwkLeaveIndEvent
      • ZPS_tsAfNwkLeaveConfEvent
      • ZPS_tsAfNwkStatusIndEvent
      • ZPS_tsAfNwkRouteDiscoveryConfEvent
      • ZPS_tsAfPollConfEvent
      • ZPS_tsAfNwkEdScanConfEvent
      • ZPS_tsAfErrorEvent
      • ZPS_tsAfZdoBindEvent
      • ZPS_tsAfZdoUnbindEvent
      • ZPS_tsAfZdoLinkKeyEvent
      • ZPS_tsAfBindRequestServerEvent
      • ZPS_tsAfInterPanDataIndEvent
      • ZPS_tsAfInterPanDataConfEvent
      • ZPS_tsAfTCstatusEvent
      • ZPS_tsAfZdpEvent
    • Other structures
      • ZPS_tsNwkNetworkDescr
      • ZPS_tsNwkNlmeCfmEdScan
      • ZPS_tsInterPanAddress
      • ZPS_tsAfProfileDataReq
      • tsBeaconFilterType
      • ZPS_tsAplApsKeyDescriptorEntry
      • ZPS_tsAftsStartParamsDistributed
      • ZPS_tsAfFlashInfoSet
      • ZPS_TclkDescriptorEntry
• ZigBee Device Profile (ZDP) API
  • ZDP API functions
    • Address discovery functions
      • ZPS_eAplZdpNwkAddrRequest
      • ZPS_eAplZdpIEEEAddrRequest
      • ZPS_eAplZdpDeviceAnnceRequest
    • Service Discovery functions
      • ZPS_eAplZdpNodeDescRequest
      • ZPS_eAplZdpPowerDescRequest
      • ZPS_eAplZdpSimpleDescRequest
      • ZPS_eAplZdpExtendedSimpleDescRequest
      • ZPS_eAplZdpComplexDescRequest
      • ZPS_eAplZdpUserDescRequest
      • ZPS_eAplZdpMatchDescRequest
      • ZPS_eAplZdpActiveEpRequest
      • ZPS_eAplZdpExtendedActiveEpRequest
      • ZPS_eAplZdpUserDescSetRequest
      • ZPS_eAplZdpSystemServerDiscoveryRequest
      • ZPS_eAplZdpDiscoveryCacheRequest
      • ZPS_eAplZdpDiscoveryStoreRequest
      • ZPS_eAplZdpNodeDescStoreRequest
      • ZPS_eAplZdpPowerDescStoreRequest
      • ZPS_eAplZdpSimpleDescStoreRequest
      • ZPS_eAplZdpActiveEpStoreRequest
      • ZPS_eAplZdpFindNodeCacheRequest
      • ZPS_eAplZdpRemoveNodeCacheRequest
    • Binding functions
      • ZPS_eAplZdpEndDeviceBindRequest
      • ZPS_eAplZdpBindUnbindRequest
      • ZPS_eAplZdpBindRegisterRequest
      • ZPS_eAplZdpReplaceDeviceRequest
      • ZPS_eAplZdpStoreBkupBindEntryRequest
      • ZPS_eAplZdpRemoveBkupBindEntryRequest
      • ZPS_eAplZdpBackupBindTableRequest
      • ZPS_eAplZdpRecoverBindTableRequest
      • ZPS_eAplZdpBackupSourceBindRequest
      • ZPS_eAplZdpRecoverSourceBindRequest
      • ZPS_eAplAibRemoveBindTableEntryForMacAddress
    • Network Management Services functions
      • ZPS_eAplZdpMgmtNwkDiscRequest
      • ZPS_eAplZdpMgmtLqiRequest
      • ZPS_eAplZdpMgmtRtgRequest
      • ZPS_eAplZdpMgmtBindRequest
      • ZPS_eAplZdpMgmtLeaveRequest
      • ZPS_eAplZdpMgmtDirectJoinRequest
      • ZPS_eAplZdpMgmtPermitJoiningRequest
      • ZPS_eAplZdpMgmtCacheRequest
      • ZPS_eAplZdpMgmtNwkUpdateRequest
      • ZPS_eAplZdpParentAnnceReq
    • Response Data Extraction Function
      • Function Page
      • ZPS_bAplZdpUnpackResponse
  • ZDP structures
    • Descriptor structures
      • ZPS_tsAplZdpNodeDescriptor
      • ZPS_tsAplZdpNodePowerDescriptor
      • ZPS_tsAplZdpSimpleDescType
    • ZDP Request structures
      • ZPS_tsAplZdpNwkAddrReq
      • ZPS_tsAplZdpIEEEAddrReq
      • ZPS_tsAplZdpDeviceAnnceReq
      • ZPS_tsAplZdpNodeDescReq
      • ZPS_tsAplZdpPowerDescReq
      • ZPS_tsAplZdpSimpleDescReq
      • ZPS_tsAplZdpExtendedSimpleDescReq
      • ZPS_tsAplZdpComplexDescReq
      • ZPS_tsAplZdpUserDescReq
      • ZPS_tsAplZdpMatchDescReq
      • ZPS_tsAplZdpActiveEpReq
      • ZPS_tsAplZdpExtendedActiveEpReq
      • ZPS_tsAplZdpUserDescSet
      • ZPS_tsAplZdpSystemServerDiscoveryReq
      • ZPS_tsAplZdpDiscoveryCacheReq
      • ZPS_tsAplZdpDiscoveryStoreReq
      • ZPS_tsAplZdpNodeDescStoreReq
      • ZPS_tsAplZdpPowerDescStoreReq
      • ZPS_tsAplZdpSimpleDescStoreReq
      • ZPS_tsAplZdpActiveEpStoreReq
      • ZPS_tsAplZdpFindNodeCacheReq
      • ZPS_tsAplZdpRemoveNodeCacheReq
      • ZPS_tsAplZdpEndDeviceBindReq
      • ZPS_tsAplZdpBindUnbindReq
      • ZPS_tsAplZdpBindRegisterReq
      • ZPS_tsAplZdpReplaceDeviceReq
      • ZPS_tsAplZdpStoreBkupBindEntryReq
      • ZPS_tsAplZdpRemoveBkupBindEntryReq
      • ZPS_tsAplZdpBackupBindTableReq
      • ZPS_tsAplZdpRecoverBindTableReq
      • ZPS_tsAplZdpBackupSourceBindReq
      • ZPS_tsAplZdpRecoverSourceBindReq
      • ZPS_tsAplZdpMgmtNwkDiscReq
      • ZPS_tsAplZdpMgmtLqiReq
      • ZPS_tsAplZdpMgmtRtgReq
      • ZPS_tsAplZdpMgmtBindReq
      • ZPS_tsAplZdpMgmtLeaveReq
      • ZPS_tsAplZdpMgmtDirectJoinReq
      • ZPS_tsAplZdpMgmtPermitJoiningReq
      • ZPS_tsAplZdpMgmtCacheReq
      • ZPS_tsAplZdpMgmtNwkUpdateReq
      • ZPS_tsAplZdpParentAnnceReq
    • ZDP response structures
      • ZPS_tsAplZdpNwkAddrRsp
      • ZPS_tsAplZdpIeeeAddrRsp
      • ZPS_tsAplZdpNodeDescRsp
      • ZPS_tsAplZdpPowerDescRsp
      • ZPS_tsAplZdpSimpleDescRsp
      • ZPS_tsAplZdpExtendedSimpleDescRsp
      • ZPS_tsAplZdpComplexDescRsp
      • ZPS_tsAplZdpUserDescRsp
      • ZPS_tsAplZdpMatchDescRsp
      • ZPS_tsAplZdpActiveEpRsp
      • ZPS_tsAplZdpExtendedActiveEpRsp
      • ZPS_tsAplZdpUserDescConf
      • ZPS_tsAplZdpSystemServerDiscoveryRsp
      • ZPS_tsAplZdpDiscoveryCacheRsp
      • ZPS_tsAplZdpDiscoveryStoreRsp
      • ZPS_tsAplZdpNodeDescStoreRsp
      • ZPS_tsAplZdpPowerDescStoreRsp
      • ZPS_tsAplZdpSimpleDescStoreRsp
      • ZPS_tsAplZdpActiveEpStoreRsp
      • ZPS_tsAplZdpFindNodeCacheRsp
      • ZPS_tsAplZdpRemoveNodeCacheRsp
      • ZPS_tsAplZdpEndDeviceBindRsp
      • ZPS_tsAplZdpBindRsp
      • ZPS_tsAplZdpUnbindRsp
      • ZPS_tsAplZdpBindRegisterRsp
      • ZPS_tsAplZdpReplaceDeviceRsp
      • ZPS_tsAplZdpStoreBkupBindEntryRsp
      • ZPS_tsAplZdpRemoveBkupBindEntryRsp
      • ZPS_tsAplZdpBackupBindTableRsp
      • ZPS_tsAplZdpRecoverBindTableRsp
      • ZPS_tsAplZdpBackupSourceBindRsp
      • ZPS_tsAplZdpRecoverSourceBindRsp
      • ZPS_tsAplZdpMgmtNwkDiscRsp
      • ZPS_tsAplZdpMgmtLqiRsp
      • ZPS_tsAplZdpMgmtRtgRsp
      • ZPS_tsAplZdpMgmtBindRsp
      • ZPS_tsAplZdpMgmtLeaveRsp
      • ZPS_tsAplZdpMgmtDirectJoinRsp
      • ZPS_tsAplZdpMgmtPermitJoiningRsp
      • ZPS_tsAplZdpMgmtCacheRsp
      • ZPS_tsAplZdpMgmtNwkUpdateNotify
      • ZPS_tsAplZdpParentAnnceRsp
  • Broadcast addresses
• General ZPS Resources
  • ZigBee Queue Resources
    • ZigBee queue functions
      • Function page
      • ZQ_vQueueCreate
      • ZQ_bQueueSend
      • ZQ_bQueueReceive
      • ZQ_bQueueIsEmpty
      • ZQ_u32QueueGetQueueSize
      • ZQ_u32QueueGetQueueMessageWaiting
    • ZigBee queue structures
      • tszQueue
  • ZigBee Timer resources
    • ZigBee Timer functions
      • Function page
      • ZTIMER_eInit
      • ZTIMER_eOpen
      • ZTIMER_eClose
      • ZTIMER_eStart
      • ZTIMER_eStop
      • ZTIMER_eGetState
    • ZigBee timer structures
      • ZTIMER_tsTimer
  • Critical Section and Mutex Resources
    • Critical Section and Mutex functions
      • Function page
      • ZPS_eEnterCriticalSection
      • ZPS_eExitCriticalSection
      • ZPS_u8GrabMutexLock
      • ZPS_u8ReleaseMutexLock
    • Critical Section and Mutex Structures
      • u32MicroIntStorage
• Event and Status Codes
  • Events
  • Return/Status Codes
    • ZDP codes
    • APS codes
    • NWK codes
    • MAC codes
    • Extended error codes
• ZigBee network parameters
  • Basic parameters
  • Profile definition parameters
  • Cluster definition parameters
  • Coordinator parameters
  • Router parameters
  • End Device parameters
  • Advanced device parameters
    • Endpoint parameters
    • Bound addressing table
    • PDU Manager
    • Group Addressing table
    • RF channels
    • MAC interface table
    • Node descriptor
    • Node Power Descriptor
    • Key Descriptor table
    • Trust Centre
  • ZDO configuration
    • Default Server
    • ZDO Client
    • Device Annce Server
    • Active Ep Server
    • Nwk Addr Server
    • IEEE Address Server
    • System Server Discovery Server
    • Permit Joining Server
    • Node Descriptor Server
    • Power Descriptor Server
    • Match Descriptor Server
    • Simple Descriptor Server
    • Mgmt Lqi Server
    • Mgmt Rtg Server
    • Mgmt Leave Server
    • Mgmt NWK Update Server
    • Bind Unbind Server
    • Extended Active Ep Server
    • Extended Simple Descriptor Server
    • End Device Bind Server
    • Parent Announcement Server
    • Management Enhanced Network Update Server
    • MIB IEEE List Server
• ZPS Configuration Editor
  • Configuration principles
  • ZPS Configuration Editor wizard
  • Overview of ZPS Configuration Editor Interface
    • Profile
    • Coordinator
    • Router
    • End Device
  • Using the ZPS Configuration Editor
    • Creating a New ZPS Configuration
    • Adding Device Types
      • To add a profile
      • To add clusters to the new profile
    • Setting Coordinator properties
      • To add a new endpoint
      • To add an APDU
      • To add input and output clusters to an endpoint
    • Setting advanced device parameters
• Appendix A: Handling stack events
• Appendix B: Application design notes
  • Fragmented data transfers
    • Enabling/disabling fragmentation
    • Configuring acknowledgments
    • Acknowledgment timeout
  • Sending data to sleeping end devices
    • Acknowledged data transmission to sleeping end device
    • Fragmented data transmission to sleeping End Device
  • Clearing stack context data before a rejoin
  • Beacon filtering guidelines
    • Network rejoin
    • Association
  • Table configuration guidelines
    • Neighbor table
    • Address Map table
    • MAC Address table
    • Routing table
    • Broadcast Transaction table
    • Route Discovery table
    • Discovery table
    • Route Record table
  • Received message queues
    • ZPS_msgMcpsDcfm
    • ZPS_msgMcpsInd
  • Noise threshold for forming a network
    • Default Behavior
    • Customizing the scan
• Appendix C: Implementation of frame counters
• Appendix D: storing applications in device flash memory
• Appendix E: Glossary of terms
• Revision history
• Note about the source code in the document