Digi XBee3 DigiMesh 2.4 User manual

Digi XBee3® DigiMesh 2.4
RF Module
User Guide

Revision history—90002277
Revision Date Description
A April 2018 Initial release.
B September
2018
Added features for S2C parity.
C April 2019 Added sleep support, file system, OTA file system updates, and several
MicroPython features.
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.
© 2019 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)
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.
Digi XBee3® DigiMesh 2.4 RF Module User Guide 2

Feedback
To provide feedback on this document, email your comments to
[e-mail]
Include the document title and part number (Digi XBee3® DigiMesh 2.4 RF Module User Guide,
90002277 B) in the subject line of your email.
Digi XBee3® DigiMesh 2.4 RF Module User Guide 3

Contents
About the XBee3 DigiMesh RF Module
Applicable firmware and hardware 14
Change the firmware protocol 14
Regulatory information 14
Get started
Verify kit contents 16
Assemble the hardware 16
Plug in the XBee3 DigiMesh RF Module 17
Unplug an XBee3 DigiMesh RF Module 18
Configure the device using XCTU 18
Configure remote devices 18
Configure the devices for a range test 19
Perform a range test 20
XBIB-C Micro Mount reference 22
XBIB-C SMT reference 25
XBIB-CU TH reference 27
XBIB-C-GPS reference 29
Interface with the XBIB-C-GPS module 31
I2C communication 32
UART communication 32
Run the MicroPython GPS demo 32
Get started with MicroPython
About MicroPython 35
MicroPython on the XBee3 DigiMesh RF Module 35
Use XCTU to enter the MicroPython environment 35
Use the MicroPython Terminal in XCTU 36
MicroPython examples 36
Example: hello world 36
Example: enter MicroPython paste mode 36
Example:using the time module 37
Example: AT commands using MicroPython 37
MicroPython networking and communication examples 38
Exit MicroPython mode 44
Other terminal programs 45
Tera Term for Windows 45
Use picocom in Linux 46
Digi XBee3® DigiMesh 2.4 RF Module User Guide 4

Digi XBee3® DigiMesh 2.4 RF Module User Guide 5
Micropython help () 47
File system
Overview of the file system 50
Directory structure 50
Paths 50
Limitations 50
XCTU interface 51
Configure the XBee3 DigiMesh RF Module
Software libraries 53
Over-the-air (OTA) firmware update 53
Custom defaults 53
Set custom defaults 53
Restore factory defaults 53
Limitations 53
Custom configuration: Create a new factory default 54
Set a custom configuration 54
Clear all custom configuration on a device 54
XBee bootloader 54
Send a firmware image 55
XBee Network Assistant 55
XBee Multi Programmer 56
Modes
Transparent operating mode 58
API operating mode 58
Command mode 58
Enter Command mode 58
Troubleshooting 59
Send AT commands 59
Response to AT commands 59
Apply command changes 60
Make command changes permanent 60
Exit Command mode 60
Idle mode 60
Transmit mode 60
Receive mode 60
Serial communication
Serial interface 62
Serial receive buffer 62
Serial transmit buffer 62
UART data flow 62
Serial data 63
Flow control 63
Clear-to-send (CTS) flow control 64
RTS flow control 64

Digi XBee3® DigiMesh 2.4 RF Module User Guide 6
SPI operation
SPI communications 66
Full duplex operation 67
Low power operation 67
Select the SPI port 68
Force UART operation 69
I/O support
Digital I/O support 71
Analog I/O support 71
Monitor I/O lines 72
I/O sample data format 73
API frame support 74
On-demand sampling 74
Example: Command mode 74
Example: Local AT command in API mode 75
Example: Remote AT command in API mode 75
Periodic I/O sampling 76
Source 76
Destination 77
Digital I/O change detection 77
I/O line passing 77
Digital line passing 78
Example:Digital line passing 78
Analog line passing 78
Example:Analog line passing 79
Output sample data 79
Output control 79
I/O behavior during sleep 79
Digital I/O lines 80
Analog and PWM I/O Lines 80
Networking
Network identifiers 82
Operating channels 82
Delivery methods 82
Point-to-multipoint 82
DigiMesh networking 83
Broadcast addressing 84
Unicast addressing 84
Route discovery 84
Routing 85
Routers 85
Repeater/directed broadcast 85
MAC layer 85
Encryption 86
Maximum payload 86

Digi XBee3® DigiMesh 2.4 RF Module User Guide 7
Network commissioning and diagnostics
Local configuration 88
Remote configuration 88
Send a remote command 88
Apply changes on remote devices 88
Remote command response 88
Build aggregate routes 89
DigiMesh routing examples 89
Replace nodes 90
Test links between adjacent devices 90
Trace route option 92
NACK messages 92
RSSI indicators 93
Associate LED 93
The Commissioning Pushbutton 93
Definitions 94
Use the Commissioning Pushbutton 94
Node discovery 95
Discover all the devices on a network 95
Directed node discovery 95
Destination Node 96
Discover devices within RF range 96
Sleep support
Sleep modes 98
Asynchronous sleep modes 98
Asynchronous Pin Sleep mode (SM = 1) 98
Asynchronous Cyclic Sleep mode (SM = 4) 98
Asynchronous Cyclic Sleep with Pin Wake-up mode (SM = 5) 99
MicroPython sleep with optional pin wake (SM = 6) 99
Synchronous sleep modes 99
Synchronous sleep support mode (SM = 7) 99
Synchronous cyclic sleep mode (SM = 8) 100
Sleep parameters 100
Sleep pins 100
Sleep conditions 101
The sleep timer 101
Sleep coordinator sleep modes in the network 102
Synchronization messages 102
Become a sleep coordinator 104
Set the sleep coordinator option 104
Resolution criteria and selection option 104
Commissioning Pushbutton option 105
Overriding syncs 105
Sleep guard times 105
Auto-early wake-up sleep option 106
Select sleep parameters 106
Start a sleeping synchronous network 107
Add a new node to an existing network 108
Change sleep parameters 108
Rejoin nodes that lose sync 109
Diagnostics 110

Digi XBee3® DigiMesh 2.4 RF Module User Guide 8
Query sleep cycle 110
Sleep status 110
Missed sync messages command 110
Sleep status API messages 110
AT commands
Networking commands 112
CH (Operating Channel) 112
ID (Network ID) 112
CE (Routing / Messaging Mode) 112
C8 (Compatibility Options) 113
NI (Network Identifier) 113
ND (Network Discover) 115
DN (Discover Node) 115
FN (Find Neighbors) 116
NT (Network Discovery Back-off) 117
NO (Network Discovery Options) 117
NP (Maximum Packet Payload Bytes) 117
DigiMesh Addressing commands 118
SH (Serial Number High) 118
SL (Serial Number Low) 118
DH (Destination Address High) 118
DL (Destination Address Low) 118
RR (Unicast Mac Retries) 119
MT(Broadcast Multi-Transmits) 119
TO (Transmit Options) 119
CI (Cluster ID) 120
DigiMesh configuration commands 120
MR (Mesh Unicast Retries) 120
BH (Broadcast Hops) 120
NH (Network Hops) 121
NN (Network Delay Slots) 121
DM (DigiMesh Options) 121
AG (Aggregator Support) 122
Diagnostic commands - addressing timeouts 122
%H (MAC Unicast One Hop Time) 122
%8 (MAC Broadcast One Hop Time) 122
N? (Network Discovery Timeout) 123
Security commands 123
EE (Encryption Enable) 123
KY (AES Encryption Key) 123
RF interfacing commands 124
PL (TX Power Level) 124
PP (Output Power in dBm) 124
CA (CCA Threshold) 124
DB (Last Packet RSSI) 125
MAC diagnostics commands 125
EA (MAC ACK Failure Count) 125
EC (CCA Failures) 125
BC (Bytes Transmitted) 126
GD (Good Packets Received) 126
TR (Transmission Failure Count) 126
UA (Unicasts Attempted Count) 127
ED (Energy Detect) 127

Digi XBee3® DigiMesh 2.4 RF Module User Guide 9
Sleep settings commands 127
SM (Sleep Mode) 127
SP (Sleep Time) 128
ST (Wake Time) 128
SN (Number of Sleep Periods) 128
WH (Wake Host Delay) 129
SO (Sleep Options) 129
Diagnostic - sleep status/timing commands 130
SS (Sleep Status) 130
OS (Operating Sleep Time) 130
OW (Operating Wake Time) 130
MS (Missed Sync Messages) 131
SQ (Missed Sleep Sync Count) 131
UART interface commands 131
BD (Baud Rate) 131
NB (Parity) 132
SB (Stop Bits) 132
FT (Flow Control Threshold) 133
RO (Packetization Timeout) 133
AP (API Enable) 133
AO (API Options) 134
AZ (Extended API Options) 134
Command mode options 134
CC (Command Character) 135
CT (Command Mode Timeout) 135
GT (Guard Time) 135
CN (Exit Command mode) 135
MicroPython commands 136
PS (Python Startup) 136
PY (MicroPython Command) 136
File system commands 137
FS (File System) 137
FK (File System Public Key) 138
UART pin configuration commands 139
D6 (DIO6/RTS Configuration) 139
D7 (DIO7/CTS Configuration) 139
P3 (DIO13/UART_DOUT) 140
P4 (DIO14/UART_DIN Configuration) 140
SPI interface commands 141
P5 (DIO15/SPI_MISO Configuration) 141
P6 (DIO16/SPI_MOSI Configuration) 141
P7 (DIO17/SPI_SSEL Configuration) 142
P8 (DIO18/SPI_CLK Configuration) 142
P9 (DIO19/SPI_ATTN Configuration) 143
I/O settings commands 143
D0 (DIO0/ADC0/Commissioning Configuration) 143
D1 (DIO1/ADC1/TH_SPI_ATTN Configuration) 144
D2 (DIO2/ADC2/TH_SPI_CLK Configuration) 144
D3 (DIO3/ADC3/TH_SPI_SSEL Configuration) 145
D4 (DIO4/TH_SPI_MOSI Configuration) 145
D5 (DIO5/Associate Configuration) 146
D8 (DIO8/DTR/SLP_Request Configuration) 146
D9 (DIO9/ON_SLEEP Configuration) 147
P0 (DIO10/RSSI/PWM0 Configuration) 147
P1 (DIO11/PWM1 Configuration) 148

Digi XBee3® DigiMesh 2.4 RF Module User Guide 10
P2 (DIO12/TH_SPI_MISO Configuration) 148
PR (Pull-up/Down Resistor Enable) 149
PD (Pull Up/Down Direction) 150
IO (Set Digital I/O Lines) 150
M0 (PWM0 Duty Cycle) 150
M1 (PWM1 Duty Cycle) 151
RP command 151
LT command 151
CB (Commissioning Button) 152
I/O sampling commands 152
IS (I/O Sample) 152
IR (Sample Rate) 153
IC (DIO Change Detect) 153
AV (Analog Voltage Reference) 154
IF (Sleep Sample Rate) 154
I/O line passing commands 155
IA (I/O Input Address) 155
IU (Send I/O Sample to Serial Port) 155
T0 (D0 Timeout) 155
T1 (D1 Output Timeout) 155
T2 (D2 Output Timeout) 156
T3 (D3 Output Timeout) 156
T4 (D4 Output Timeout) 156
T5 (D5 Output Timeout) 156
T6 (D6 Output Timeout) 157
T7 (D7 Output Timeout) 157
T8 (D8 Timeout) 157
T9 (D9 Timeout) 157
Q0 (P0 Timeout) 157
Q1 (P1 Timeout) 158
Q2 (P2 Timeout) 158
PT (PWM Output Timeout) 158
Diagnostics – Firmware/Hardware Information 158
VR (Firmware Version) 158
VL (Version Long) 159
VH (Bootloader Version) 159
HV (Hardware Version) 159
%C (Hardware/Software Compatibility) 159
%V (Supply Voltage) 159
TP (Temperature) 160
DD (Device Type Identifier) 160
CK (Configuration CRC) 160
FR (Software Reset) 160
Memory access commands 161
AC (Apply Changes) 161
WR (Write) 161
RE (Restore Defaults) 161
Custom default commands 161
%F (Set Custom Default) 162
!C (Clear Custom Defaults) 162
R1 (Restore Factory Defaults) 162
Operate in API mode
API mode overview 164

Digi XBee3® DigiMesh 2.4 RF Module User Guide 11
Use the AP command to set the operation mode 164
API frame format 164
API operation (AP parameter = 1) 164
API operation with escaped characters (AP parameter = 2) 165
Frame descriptions
AT Command Frame - 0x08 169
AT Command - Queue Parameter Value frame - 0x09 171
Transmit Request frame - 0x10 173
Explicit Addressing Command frame - 0x11 176
Remote AT Command Request frame - 0x17 179
AT Command Response frame - 0x88 181
Modem Status frame - 0x8A 183
Transmit Status frame - 0x8B 184
Route Information Packet frame - 0x8D 186
Aggregate Addressing Update frame - 0x8E 189
Receive Packet frame - 0x90 191
Explicit Rx Indicator frame - 0x91 193
I/O Data Sample Rx Indicator frame - 0x92 196
Node Identification Indicator frame - 0x95 198
Remote Command Response frame - 0x97 202
Over-the-air firmware/file system upgrade process for DigiMesh 2.4
OTA upgrade image file formats 205
OTA/OTB file 205
fs.ota file 205
The OTA header 205
Hardware/software compatibility 206
Sub-elements and tags 206
Parse the image blocks 207
Storage 207
ZCL OTA messaging 207
ZCL message output 208
Image Notify 208
Create the Image Notify request 209
Query Next Image request 211
Query Next Image response 213
Image Block request 215
Image Block response 217
Upgrade End request 220
Upgrade End response 222
OTA error handling 224
Default response commands 224
Upgrade End Request error statuses 225
OTA file system upgrades
OTA file system update process 228
OTA file system updates using XCTU 228
Generate a public/private key pair 228
Set the public key on the XBee3 device 229

Digi XBee3® DigiMesh 2.4 RF Module User Guide 12
Create the OTA file system image 230
Perform the OTA file system update 231
OTA file system updates: OEM 232
Generate a public/private key pair 233
Set the public key on the XBee3 device 233
Create the OTA file system image 233
Perform the OTA file system update 234

About the XBee3 DigiMesh RF Module
The XBee3 DigiMesh RF Module consists of DigiMesh 2.4 firmware loaded on the XBee3 hardware. This
user guide covers the firmware. For information about XBee3 hardware, see the XBee3 RF Module
Hardware Reference Manual.
Digi XBee3 devices offer the flexibility to switch between multiple frequencies and wireless protocols
as needed. These devices use the DigiMesh networking protocol using a globally deployable 2.4 GHz
transceiver. This peer-to-peer mesh network offers users added network stability through self-
healing, dense network operation, extending the operational life of battery dependent networks and
provides an upgrade path to IEEE 802.15.4 or ZigBee mesh protocols, if desired.
Digi’s XBee3 DigiMesh RF Module is an easy-to-use USB to XBee Wireless Personal Area Network
(WPAN) adapter, providing local connectivity to wireless networks. Simply plug the XBee3 DigiMesh RF
Module into the USB port of a laptop or PC for instant access to an Digi XBee network and its
connected devices. This compact, USB-powered wireless adapter enables local network configuration,
diagnostics or device monitoring.
Applicable firmware and hardware 14
Change the firmware protocol 14
Regulatory information 14
Digi XBee3® DigiMesh 2.4 RF Module User Guide 13

About the XBee3 DigiMesh RF Module Applicable firmware and hardware
Digi XBee3® DigiMesh 2.4 RF Module User Guide 14
Applicable firmware and hardware
This manual supports the following firmware:
nv.30xx DigiMesh
It supports the following hardware:
nXBee3
Change the firmware protocol
You can switch the firmware loaded onto the XBee3 hardware to run any of the following protocols:
nZigbee
n802.15.4
nDigiMesh
To change protocols, use the Update firmware feature in XCTU and select the firmware. See the
XCTU User Guide.
Regulatory information
See the Regulatory information section of the XBee3 RF Module Hardware Reference Manual for the
XBee3 hardware's regulatory and certification information.

Get started
Verify kit contents 16
Assemble the hardware 16
Configure the device using XCTU 18
Configure remote devices 18
Configure the devices for a range test 19
Perform a range test 20
XBIB-C Micro Mount reference 22
XBIB-C SMT reference 25
XBIB-CU TH reference 27
XBIB-C-GPS reference 29
Interface with the XBIB-C-GPS module 31
Digi XBee3® DigiMesh 2.4 RF Module User Guide 15

Get started Verify kit contents
Digi XBee3® DigiMesh 2.4 RF Module User Guide 16
Verify kit contents
The XBee3 DigiMesh RF Module development kit contains the following components:
Part
XBee3 Zigbee SMT module (3)
XBee Grove development board (3)
Micro USB cable (3)
Antenna - 2.4 GHz, half-wave dipole, 2.1 dBi, U.FL female, articulating
(3)
XBee stickers
Assemble the hardware
This guide walks you through the steps required to assemble and disassemble the hardware
components of your kit.
nPlug in the XBee3 DigiMesh RF Module
nUnplug an XBee3 DigiMesh RF Module

Get started Assemble the hardware
Digi XBee3® DigiMesh 2.4 RF Module User Guide 17
The kit includes several XBee Grove Development Boards. For more information about this hardware,
see the XBee Grove Development Board documentation.
Plug in the XBee3 DigiMesh RF Module
Follow these steps to connect the XBee devices to the boards included in the kit:
1. Plug one XBee3 DigiMesh RF Module into the XBee Grove Development Board. When you
connect the development board to a PC for the first time, the PC automatically installs drivers,
which may take a few minutes to complete.
Make sure the board is NOT powered (either by the micro USB or a battery) when
you plug in the XBee module.
For XBee SMT modules, align all XBee pins with the spring header and carefully push the
module until it is hooked to the board.
WARNING! Never insert or remove the XBee device while the power is on!
2. Once the XBee module is plugged into the board (and not before), connect the board to your
computer using the micro USB cables provided.
3. Ensure the loopback jumper is in the UART position.

Get started Configure the device using XCTU
Digi XBee3® DigiMesh 2.4 RF Module User Guide 18
Unplug an XBee3 DigiMesh RF Module
To disconnect a device from the XBee Grove Development Board:
1. Disconnect the micro USB cable from the board so it is not powered.
2. Remove the device from the board socket, taking care not to bend any of the pins. The surface
mount device uses spring pins rather than a socket and has a rectangular board cutout
designed to help in removing the XBee3 DigiMesh RF Module.
CAUTION! Make sure the board is not powered when you remove the XBee3 DigiMesh RF
Module.
Configure the device using XCTU
XBee Configuration and Test Utility (XCTU) is a multi-platform program that enables users to interact
with Digi radio frequency (RF) devices through a graphical interface. The application includes built-in
tools that make it easy to set up, configure, and test Digi RF devices.
For instructions on downloading and using XCTU, see the XCTU User Guide.
Configure remote devices
You can communicate with remote devices over the air through a corresponding local device.
Note Using API mode on the local device allows you to send remote API commands.
These instructions show you how to configure a remote device parameter on a remote device.
1. Add two XBee devices to XCTU.
2. Load XBee3 DigiMesh 2.4 firmware onto each device if it is not already loaded. See How to
update the firmware of your modules in the XCTU User Guide for more information.
3. Configure the first device in API mode and name it XBEE_A by configuring the following
parameters:
nID: 2018
nNI: XBEE_A
nAP: API enabled [1]
4. Configure the second device in either API or Transparent mode, and name it XBEE_B by
configuring the following parameters:
nID: 2018
nNI: XBEE_B
nAP: 0 or 1

Get started Configure the devices for a range test
Digi XBee3® DigiMesh 2.4 RF Module User Guide 19
4. Disconnect XBEE_B from your computer and remove it from XCTU.
5. Connect XBEE_B to a power supply (or laptop or portable battery).
The Radio Modules area should look something like this.
6. Select XBEE_A and click the Discover radio nodes in the same network button .
7. Click Add selected devices in the Discovering remote devices dialog. The discovered remote
device appears below XBEE_A.
9. Select the remote device XBEE_B to display its current configuration settings. If you want to
modify a command parameter, use the radio configuration pane.
10. Click the Write radio settings button to apply any changes and write it to the remote device.
Configure the devices for a range test
1. Add two devices to XCTU.
2. Select the first module and click the Load default firmware settings button.
3. Configure the following parameters:
ID: 2018
NI: LOCAL_DEVICE
AP: API Mode Enabled [1]
4. Click the Write radio settings button.
5. Select the other module and click the Default firmware settings button.
6. Configure the following parameters:
ID: 2018
NI: REMOTE_DEVICE

Get started Perform a range test
Digi XBee3® DigiMesh 2.4 RF Module User Guide 20
7. Click the Write radio settings button.
After you write the radio settings for each device, their names appear in the Radio Modules
area. The Port indicates that the LOCAL_DEVICE is in API mode.
8. Disconnect REMOTE_DEVICE from the computer, remove it from XCTU, and connect it to a
power supply, laptop, or portable battery.
9. Leave LOCAL_DEVICE connected to the computer.
Perform a range test
1. Go to the XCTU display for radio 1.
2. Click to discover remote devices within the same network. The Discover remote devices
dialog appears.
3. Click Add selected devices.