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