XBee3® Zigbee® RF Module User Guide Revision history—90001539 Revision Date Description A October 2017 Initial release. B January 2018 Added the XBee3 through-hole form factor information. C March 2018 Added the Get started with MicroPython section. 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. © 2017 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 Send comments Documentation feedback: To provide feedback on this document, send your comments to [email protected]. Customer support Digi Technical Support: Digi offers multiple technical support plans and service packages to help our customers get the most out of their Digi product. For information on Technical Support plans and pricing, contact us at +1 952.912.3444 or visit us at www.digi.com/support. XBee3® Zigbee® RF Module User Guide 2 Contents XBee3® Zigbee® RF Module User Guide Applicable firmware and hardware 13 Module support Configure the device using XCTU 15 Customize XBee Zigbee firmware 15 XBee bootloader 15 Send a firmware image 15 Software libraries 16 Update the firmware over-the-air Add the device to XCTU 18 Update to the latest firmware 18 Get started with MicroPython About MicroPython 20 MicroPython on the XBee3 Zigbee RF Module 20 Use XCTU to enter the MicroPython environment 20 Use the MicroPython Terminal in XCTU 21 MicroPython examples 21 Example: hello world 21 Example: enter MicroPython paste mode 21 Example: using the time module 22 Example: AT commands using MicroPython 22 MicroPython networking and communication examples 23 Zigbee networks with MicroPython 23 Example: forming and joining a Zigbee network using MicroPython 24 Example: network Discovery using MicroPython 25 Examples: transmitting data 26 Receiving data 27 Example: communication between two XBee3 Zigbee modules 29 Exit MicroPython mode 31 Other terminal programs 31 Tera Term for Windows 31 Use picocom in Linux 33 XBee3® Zigbee® RF Module User Guide 3 Operation Serial interface 36 UART data flow 36 Serial data 36 Serial buffers 37 Serial receive buffer 37 Serial transmit buffer 37 UART flow control 38 CTS flow control 38 RTS flow control 38 Break control 38 Modes Transparent operating mode 40 Serial-to-RF packetization 40 API operating mode 40 Compare Transparent and API operation 40 Command mode 41 Enter Command mode 41 Send AT commands 42 Apply command changes 43 Exit Command mode 43 Idle mode 43 Transmit mode 43 Receive mode 44 Sleep mode 44 Zigbee networks About the Zigbee specification 46 Zigbee stack layers 46 Zigbee networking concepts 47 Device types 47 PAN ID 49 Operating channels 50 Zigbee application layers: in depth 50 Application Support Sublayer (APS) 50 Application profiles 50 Zigbee coordinator operation 52 Form a network 52 Security policy 52 Channel selection 52 PAN ID selection 52 Persistent data 52 Coordinator startup 53 Permit joining 54 Reset the coordinator 54 Leave a network 55 Replace a coordinator (security disabled only) 55 Example: start a coordinator 56 Example: replace a coordinator (security disabled) 56 Router operation 57 XBee3® Zigbee® RF Module User Guide 4 Discover Zigbee networks 57 Join a network 57 Persistent data 57 Zigbee router joining 58 Router network connectivity 59 End device operation 61 Discover Zigbee networks 61 Join a network 62 End device capacity 62 Persistent data 62 Orphan scans 63 End device joining 63 Parent connectivity 64 Reset the end device 64 Zigbee channel scanning 64 Manage multiple Zigbee networks 65 Filter PAN ID 65 Configure security keys 65 Prevent unwanted devices from joining 65 Application messaging framework 66 Transmission, addressing, and routing Addressing 68 64-bit device addresses 68 16-bit device addresses 68 Application layer addressing 68 Data transmission 68 Broadcast transmissions 68 Unicast transmissions 69 Address resolution 69 Address table 70 Group table 71 Binding transmissions 71 Address resolution 71 Binding table 71 Multicast transmissions 72 Address resolution 72 Fragmentation 72 Data transmission examples 72 Transparent mode 72 API mode 73 API frame 74 RF packet routing 74 Link status transmission 75 AODV mesh routing 76 Many-to-One routing 79 High/Low RAM Concentrator mode 79 Source routing 79 Encrypted transmissions 84 Maximum RF payload size 84 Throughput 86 ZDO transmissions 86 Send a ZDO command 87 Receiving ZDO command and responses 87 XBee3® Zigbee® RF Module User Guide 5 Transmission timeouts 89 Unicast timeout 89 Extended timeout 90 Transmission examples 90 Zigbee security Security overview 94 Network key 94 Link key 94 Preconfigured link key - moderate security 94 Well-known default link key - low security 95 Install code derived link key - high security 95 Join window 95 Key management 96 Centralized security 96 Distributed security 96 Device registration 96 Centralized trust center 97 Distributed trust center 97 Example: Forming a secure network 97 Example: Joining a secure network using a preconfigured link key 98 Example: Registering a joining node without a preconfigured link key 99 Example: Registration of a joining node using an install code 100 Example: Deregistering a previously registered device 100 Registration scenario 101 Network commissioning and diagnostics Place devices 103 Test links in a network - loopback cluster 103 RSSI indicators 103 Device discovery 104 Network discovery 104 ZDO discovery 104 Joining Announce 104 Commissioning pushbutton and associate LED 104 XBee3 SMT 105 XBee3 Micro 105 XBee3 Through-hole 106 Commissioning pushbutton 106 Associate LED 107 Binding 108 End_Device_Bind_req 108 Example of a End_Device_Bind_req 110 Group Table API 111 Add Group command 111 View group 112 Get Group Membership 113 Remove Group 116 Remove All Groups 117 Default responses 118 Common status codes 118 XBee3® Zigbee® RF Module User Guide 6 Manage End Devices End device operation 121 Parent operation 121 End Device poll timeouts 122 Packet buffer usage 122 Non-Parent device operation 123 End Device configuration 123 Pin sleep 124 Cyclic sleep 126 Recommended sleep current measurements 130 Achieve the lowest sleep current 130 Compensate for switching time 130 Internal pin pull-ups 131 Transmit RF data 131 Receiving RF data 131 I/O sampling 132 Wake end devices with the Commissioning Pushbutton 132 Parent verification 132 Rejoining 132 Router/Coordinator configuration 133 RF packet buffering timeout 133 Child poll timeout 133 Transmission timeout 134 Short sleep periods 134 Extended sleep periods 134 Sleep examples 134 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. 135 Example 2: Configure an end device to sleep for 20 seconds, send 4 I/O samples in 2 seconds, and return to sleep. 135 Example 3: configure a device for extended sleep: to sleep for 4 minutes. 135 Analog and digital I/O lines I/O configuration 138 I/O sampling 138 I/O examples 140 Example 1: Configure the following I/O settings on the XBee 140 Example 2: Calculate the PWM counts for a packet received with an RSSI of -84 dBm 140 Example 3: Configure the RSSI/PWM pin to operate for 2 seconds after each received RF packet 140 Queried sampling 141 Periodic I/O sampling 141 Change detection sampling 141 RSSI PWM 142 AT commands Network commands 144 CE (Device Role) 144 ID (Extended PAN ID) 144 II (Initial 16-bit PAN ID) 144 XBee3® Zigbee® RF Module User Guide 7 ZS (Zigbee Stack Profile) 145 CR (Conflict Report) 145 NJ (Node Join Time) 145 DJ (Disable Joining) 146 NW (Network Watchdog Timeout) 146 JV (Coordinator Join Verification) 147 JN (Join Notification) 147 DO (Miscellaneous Device Options) 147 DC (Joining Device Controls) 148 CB (Commissioning Pushbutton) 149 NR (Network Reset) 149 Operational Network Parameters commands 149 AI (Association Indication) 149 OP (Operating Extended PAN ID) 150 OI (Operating 16-bit PAN ID) 150 CH (Operating Channel) 151 NC (Number of Remaining Children) 151 Security commands 151 EE (Encryption Enable) 151 EO (Encryption Options) 152 KY (Link Key) 152 NK (Trust Center Network Key) 152 KT (Trust Center Link Key Registration Timeout) 153 I? (Install Code) 153 Addressing commands 153 SH (Serial Number High) 153 SL (Serial Number Low) 154 MY (16-bit Network Address) 154 MP (16-bit Parent Network Address) 154 DH (Destination Address High) 154 DL command 155 NI (Node Identifier) 155 NH (Maximum Unicast Hops) 155 BH (Broadcast Hops) 156 AR (Aggregate Routing Notification) 156 DD (Device Type Identifier) 156 ND (Network Discovery) 157 DN (Discover Node) 157 NT (Node Discover Timeout) 158 NO (Network Discovery Options) 158 NP (Maximum Packet Payload Bytes) 158 Zigbee addressing commands 159 TO (Transmit Options) 159 SE (Source Endpoint) 159 DE (Destination Endpoint) 160 CI (Cluster ID) 160 RF interfacing commands 160 PL