Digi XBee® 3 ZigBee® RF Module User Guide Revision history—90001539 Revision Date Description G April 2020 Added centralized trust center backups. Added the BK, BP, CX, R?, US, RK, and KB commands. Added OTA upgrades. Added Open Join Window indication. H May 2020 Revised all API frame descriptions. Added ZDO cluster commands and information. J September Added a note to D8. Updated OTA firmware/file system upgrades. 2020 Updated Considerations for older firmware versions. K April 2021 Updated ZDO clusters to indicate XBee support. L July 2021 Added safety instructions. Trademarks and copyright Digi, Digi International, and the Digi logo are trademarks or registered trademarks in the United States and other countries worldwide. All other trademarks mentioned in this document are the property of their respective owners. © 2020 Digi International Inc. All rights reserved. Disclaimers Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International. Digi provides this document “as is,” without warranty of any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or merchantability for a particular purpose. Digi may make improvements and/or changes in this manual or in the product(s) and/or the program(s) described in this manual at any time. Warranty To view product warranty information, go to the following website: www.digi.com/howtobuy/terms Customer support Gather support information: Before contacting Digi technical support for help, gather the following information: Product name and model Product serial number (s) Firmware version Operating system/browser (if applicable) Logs (from time of reported issue) Digi XBee® 3 Zigbee® RF Module 2 Trace (if possible) Description of issue Steps to reproduce Contact Digi technical support: Digi offers multiple technical support plans and service packages. Contact us at +1 952.912.3444 or visit us at www.digi.com/support. Feedback To provide feedback on this document, email your comments to [email protected] Include the document title and part number (Digi XBee® 3 Zigbee® RF Module, 90001539 L) in the subject line of your email. Digi XBee® 3 Zigbee® RF Module 3 Contents Digi XBee® 3 Zigbee® RF Module Applicable firmware and hardware 18 Change the firmware protocol 18 Regulatory information 18 Safety instructions 18 XBee modules 18 Get started Configure the XBee 3 Zigbee RF Module Configure the device using XCTU 21 Custom defaults 21 Set custom defaults 21 Restore factory defaults 21 Limitations 21 Custom configuration: Create a new factory default 21 Set a custom configuration 22 Clear all custom configuration on a device 22 XBee bootloader 22 Send a firmware image 22 Software libraries 23 XBee Network Assistant 23 XBee Multi Programmer 24 Update the firmware over-the-air Add the device to XCTU 26 Update to the latest firmware 26 Get started with MicroPython About MicroPython 28 MicroPython on the XBee 3 Zigbee RF Module 28 Use XCTU to enter the MicroPython environment 28 Use the MicroPython Terminal in XCTU 29 MicroPython examples 29 Example: hello world 29 Digi XBee® 3 Zigbee® RF Module 4 Example: enter MicroPython paste mode 29 Example: use the time module 30 Example: AT commands using MicroPython 30 MicroPython networking and communication examples 31 Zigbee networks with MicroPython 31 Example: forming and joining a Zigbee network using MicroPython 32 Example: network Discovery using MicroPython 33 Examples: transmitting data 34 Receiving data 35 Example: communication between two XBee 3 Zigbee modules 36 Exit MicroPython mode 39 Other terminal programs 39 Tera Term for Windows 39 Use picocom in Linux 40 Micropython help () 41 Secure access Secure Sessions 44 Configure the secure session password for a device 44 Start a secure session 44 End a secure session 45 Secured remote AT commands 45 Secure a node against unauthorized remote configuration 45 Remotely configure a node that has been secured 46 Send data to a secured remote node 47 End a session from a server 47 Secure Session API frames 48 Secure transmission failures 48 Data Frames - 0x10 and 0x11 frames 49 Remote AT Commands- 0x17 frames 49 File system Overview of the file system 51 Directory structure 51 Paths 51 Limitations 51 XCTU interface 52 Get started with BLE Enable BLE on the XBee 3 Zigbee RF Module 54 Enable BLE and configure the BLE password 54 Get the Digi XBee Mobile phone application 55 Connect with BLE and configure your XBee 3 device 56 BLE reference BLE advertising behavior and services 58 Device Information Service 58 XBee API BLE Service 58 API Request characteristic 58 Digi XBee® 3 Zigbee® RF Module 5 API Response characteristic 59 Serial communication Serial interface 61 UART data flow 61 Serial data 61 Serial buffers 62 Serial receive buffer 62 Serial transmit buffer 63 UART flow control 63 CTS flow control 63 RTS flow control 63 Break control 63 I2C 64 SPI operation SPI communications 66 Full duplex operation 67 Low power operation 67 Select the SPI port 68 Force UART operation 69 Modes Transparent operating mode 71 Serial-to-RF packetization 71 API operating mode 71 Command mode 71 Enter Command mode 72 Troubleshooting 72 Send AT commands 72 Response to AT commands 73 Apply command changes 73 Make command changes permanent 73 Exit Command mode 74 Idle mode 74 Transmit mode 74 Receive mode 75 Sleep mode 75 Zigbee networks The Zigbee specification 77 Zigbee stack layers 77 Zigbee networking concepts 78 Device types 78 PAN ID 80 Operating channels 80 Zigbee application layers: in depth 81 Application Support Sublayer (APS) 81 Application profiles 81 Digi XBee® 3 Zigbee® RF Module 6 Zigbee coordinator operation 83 Form a network 83 Security policy 83 Channel selection 83 PAN ID selection 83 Persistent data 83 Coordinator startup 84 Permit joining 85 Reset the coordinator 85 Leave a network 86 Replace a coordinator (security disabled only) 86 Example: start a coordinator 87 Example: replace a coordinator (security disabled) 87 Router operation 88 Discover Zigbee networks 88 Join a network 88 Authentication 88 Persistent data 88 Router joining 89 Router network connectivity 90 End device operation 92 Discover Zigbee networks 92 Join a network 93 Parent child relationship 93 End device capacity 93 Authentication 93 Persistent data 94 Orphan scans 94 End device joining 94 Parent connectivity 95 Reset the end device 95 Channel scanning 95 Manage multiple Zigbee networks 96 Filter PAN ID 96 Configure security keys 96 Prevent unwanted devices from joining 96 Application messaging framework 97 Transmission, addressing, and routing Addressing 99 64-bit device addresses 99 16-bit device addresses 99 Application layer addressing 99 Data transmission 99 Broadcast transmissions 99 Unicast transmissions 100 Address resolution 100 Address table 101 Group table 102 Binding transmissions 102 Multicast transmissions 102 Address resolution 102 Address resolution 102 Binding table 103 Digi XBee® 3 Zigbee® RF Module 7 Fragmentation 103 Data transmission examples 103 Send a packet in Transparent mode 103 Send data in API mode 104 API frame examples 105 RF packet routing 105 Link status transmission 106 AODV mesh routing 107 Many-to-One routing 110 High/Low RAM Concentrator mode 110 Source routing 110 Encrypted transmissions 115 Maximum RF payload size 115 Throughput 117 ZDO transmissions 117 Send a ZDO command 118 Receiving ZDO command and responses 118 Support ZDOs with the XBee API 122 Support the ZDP with the XBee API 122 ZDO clusters 123 API example 1 139 API example 2 140 API example 3 141 API example 4 142 API example 5 143 API example 6 144 API Example 7 145 Transmission timeouts 146 Unicast timeout 147 Extended timeout 147 Transmission examples 148 Zigbee security Security overview 151 Network key 151 Link key 151 Preconfigured link key - moderate security 152 Well-known default link key - low security 152 Install code derived link key - high security 152 Join window 152 Key management 153 Centralized security 153 Distributed security 154 Device registration 154 Centralized trust center 154 Distributed trust center 155 Example: Form a secure network 155 Example: Join a secure network using a preconfigured link key 156 Example: Register a joining node without a preconfigured link key 156 Example: Register a joining node using an install code 157 Example: Deregister a previously registered device 158 Registration scenario 158 Digi XBee® 3 Zigbee® RF Module 8 Centralized trust center backup Create the backup file 161 New networks 161 Existing networks 161 Store the file 161 Recover a Centralized Trust Center 161 Best practices 162 Network commissioning and diagnostics 163 Place devices 163 Device discovery 164 Commissioning pushbutton and associate LED 165 Binding 168 Group Table API 172 Manage End Devices End device operation 183 Parent operation 183 End Device poll timeouts 184 End Device child table 184 Packet buffer usage 184 Non-Parent device operation 185 End Device configuration 185 Pin sleep 186 Cyclic sleep 188 Recommended sleep current measurements 194 Achieve the lowest sleep current 194 Compensate for switching time 194 Internal pin pull-ups 194 Transmit RF data 195 Receiving RF data 195 I/O sampling 195 Wake end devices with the Commissioning Pushbutton 195 Parent verification 195 Rejoining 196 Router/Coordinator configuration 196 RF packet buffering timeout 196 Child poll timeout 197 Adaptive polling 197 Transmission timeout 197 Short sleep periods 197 Extended sleep periods 197 Sleep examples 198 Example 1: Configure a device to sleep for 20 seconds, but set SN such that the On/sleep line will remain de-asserted for up to 1 minute. 198 Example 2: Configure an end device to sleep for 20 seconds, send 4 I/O samples in 2 seconds, and return to sleep. 198 Example 3: configure a device for extended sleep: to sleep for 4 minutes.