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.
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.
© 2018 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
[e-mail].
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.
Digi XBee3® DigiMesh RF Module User Guide 2

Contents
About the XBee3 DigiMesh RF Module
Applicable firmware and hardware 8
Change the firmware protocol 8
Getting started
Verify kit contents 10
Assemble the hardware 10
Plug in the XBee3 DigiMesh RF Module 11
How to unplug an XBee module 12
Configure the device using XCTU 12
Configure remote devices 12
Configure the devices for a range test 13
Perform a range test 14
Configure the XBee3 DigiMesh RF Module
Software libraries 18
Configure the device using XCTU 18
Modes
Transparent operating mode 20
API operating mode 20
Command mode 20
Enter Command mode 20
Send AT commands 21
Apply command changes 21
Exit Command mode 21
Idle mode 22
Transmit mode 22
Receive mode 22
Serial communication
Serial interface 24
Serial data 24
UART data flow 24
Serial receive buffer 25
Digi XBee3® DigiMesh RF Module User Guide 3

Digi XBee3® DigiMesh RF Module User Guide 4
Serial transmit buffer 25
Flow control 25
CTS flow control 26
RTS flow control 26
Networking
Network identifiers 28
Operating channels 28
Delivery methods 28
Point-to-multipoint 28
DigiMesh networking 29
Broadcast addressing 30
Unicast addressing 30
Route discovery 30
Routing 31
Routers 31
Repeater/directed broadcast 31
MAC layer 31
Encryption 32
Maximum payload 32
Network commissioning and diagnostics
Local configuration 34
Remote configuration 34
Send a remote command 34
Apply changes on remote devices 34
Remote command response 34
Build aggregate routes 35
DigiMesh routing examples 35
Replace nodes 36
Test links between adjacent devices 36
Trace route option 38
NACK messages 39
Associate LED 39
Node discovery 39
Discover all the devices on a network 40
Directed node discovery 40
Destination Node 40
Discover devices within RF range 41
AT commands
Network commands 43
ID (Network ID) 43
NI (Network Identifier) 43
NT (Network Discovery Back-off) 43
NO (Network Discovery Options) 43
NP (Maximum Packet Payload Bytes) 44
CE (Routing / Messaging Mode) 44
DM (DigiMesh Options) 45
Addressing discovery/configuration commands 45

Digi XBee3® DigiMesh RF Module User Guide 5
AG (Aggregator Support) 45
DN (Discover Node) 45
ND (Network Discover) 46
FN (Find Neighbors) 47
MAC diagnostics 47
BC (Bytes Transmitted) 48
GD (Good Packets Received) 48
EA (MAC ACK Failure Count) 48
EC (CCA Failures) 48
TR (Transmission Failure Count) 49
UA (Unicasts Attempted Count) 49
Security commands 49
EE (Encryption Enable) 49
KY (AES Encryption Key) 50
Addressing commands 50
SH (Serial Number High) 50
SL (Serial Number Low) 50
DH (Destination Address High) 50
DL (Destination Address Low) 51
RR (Unicast Mac Retries) 51
MT(Broadcast Multi-Transmits) 51
BH (Broadcast Hops) 51
NH (Network Hops) 52
MR (Mesh Unicast Retries) 52
NN (Network Delay Slots) 52
TO (Transmit Options) 53
C8 (Compatibility Options) 53
CI (Cluster ID) 54
Diagnostic commands - addressing timeouts 54
%H (MAC Unicast One Hop Time) 54
%8 (MAC Broadcast One Hop Time) 54
N? (Network Discovery Timeout) 55
RF interfacing commands 55
CH (Operating Channel) 55
PL (TX Power Level) 55
PP (Output Power in dBm) 56
CA (CCA Threshold) 56
DB (Last Packet RSSI) 56
UART serial interfacing 57
BD (Baud Rate) 57
NB (Parity) 57
SB (Stop Bits) 58
AP (API Enable) 58
AO (API Options) 58
RO (Packetization Timeout) 59
FT (Flow Control Threshold) 59
Command mode options 59
CC (Command Character) 59
CT (Command Mode Timeout) 60
GT (Guard Time) 60
Diagnostics – Firmware/Hardware Information 60
VR (Firmware Version) 60
HV (Hardware Version) 60
DD (Device Type Identifier) 61
CK (Configuration CRC) 61

Digi XBee3® DigiMesh RF Module User Guide 6
FR (Software Reset) 61
Memory access commands 61
AC (Apply Changes) 62
WR (Write) 62
RE (Restore Defaults) 62
Operate in API mode
API mode overview 64
Use the AP command to set the operation mode 64
API frame format 64
API operation (AP parameter = 1) 64
API operation with escaped characters (AP parameter = 2) 65
Frame descriptions 68
AT Command Frame - 0x08 68
AT Command - Queue Parameter Value frame - 0x09 70
Transmit Request frame - 0x10 71
Explicit Addressing Command frame - 0x11 74
Remote AT Command Request frame - 0x17 77
AT Command Response frame - 0x88 79
Modem Status frame - 0x8A 81
Transmit Status frame - 0x8B 82
Route Information Packet frame - 0x8D 84
Aggregate Addressing Update frame - 0x8E 87
Receive Packet frame - 0x90 89
Explicit Rx Indicator frame - 0x91 91
Node Identification Indicator frame - 0x95 94
Remote Command Response frame - 0x97 97

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.
Applicable firmware and hardware 8
Change the firmware protocol 8
Digi XBee3® DigiMesh RF Module User Guide 7

About the XBee3 DigiMesh RF Module Applicable firmware and hardware
Digi XBee3® DigiMesh RF Module User Guide 8
Applicable firmware and hardware
This manual supports the following firmware:
n3000
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.

Getting started
Verify kit contents 10
Assemble the hardware 10
Configure the device using XCTU 12
Configure remote devices 12
Configure the devices for a range test 13
Perform a range test 14
Digi XBee3® DigiMesh RF Module User Guide 9

Getting started Verify kit contents
Digi XBee3® DigiMesh RF Module User Guide 10
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
nHow to unplug an XBee module
The kit includes several XBee Grove Development Boards. For more information about this hardware,

Getting started Assemble the hardware
Digi XBee3® DigiMesh RF Module User Guide 11
see the XBee Grove Development Board documentation.
Plug in the XBee3 DigiMesh RF Module
This kit includes three XBee Grove Development Boards. For more information about this hardware,
visit the XBee Grove Development Board documentation.
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.
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.
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.

Getting started Configure the device using XCTU
Digi XBee3® DigiMesh RF Module User Guide 12
How to unplug an XBee module
To disconnect your XBee module from the XBee Grove Development Board:
1. Disconnect the micro USB cable (or the battery) from the board so it is not powered.
2. Remove the XBee module from the board socket, taking care not to bend any of the pins.
Make sure the board is not powered when you remove the XBee 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 Configure the local device in API mode because remote commands only work in API mode.
Configure remote devices in either API or Transparent mode.
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.
3. Configure the first device in APImode and name it XBEE_A.
4. Configure the second device in either API or Transparent mode, and name it XBEE_B.
5. Disconnect XBEE_B from your computer and remove it from XCTU.
6. Connect XBEE_B to a power supply (or laptop or portable battery).
The Radio Modules area should look something like this.
7. Select XBEE_A and click the Discover radio nodes in the same network button .

Getting started Configure the devices for a range test
Digi XBee3® DigiMesh RF Module User Guide 13
8. 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
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.
1. Add the 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
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 its
own power supply.
9. Leave LOCAL_DEVICE connected to the computer.

Getting started Perform a range test
Digi XBee3® DigiMesh RF Module User Guide 14
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.

Getting started Perform a range test
Digi XBee3® DigiMesh RF Module User Guide 15
4. Click and select Range test. The Radio Range Test dialog appears.
5. In the Select the local radio device area, select radio 1. XCTU automatically selects the
Discovered device option, and the Start Range Test button is active.

Getting started Perform a range test
Digi XBee3® DigiMesh RF Module User Guide 16
6. Click to begin the range test.
If the test is running properly, the packets sent should match the packets received. You will
also see the received signal strength indicator (RSSI) update for each radio after each
reception.
7. Move Radio 1 around to see the resulting signal strength at different distances. You can also
test different power levels by reconfiguring the PL (TX Power Level) parameter on both
devices. When the test is complete, click Stop Range Test.

Configure the XBee3 DigiMesh RF Module
Software libraries 18
Configure the device using XCTU 18
Digi XBee3® DigiMesh RF Module User Guide 17

Configure the XBee3 DigiMesh RF Module Software libraries
Digi XBee3® DigiMesh RF Module User Guide 18
Software libraries
One way to communicate with the XBee3 DigiMesh RF Module is by using a software library. The
libraries available for use with the XBee3 DigiMesh RF Module include:
nXBee Java library
nXBee Python library
The XBee Java Library is a Java API. The package includes the XBee library, its source code and a
collection of samples that help you develop Java applications to communicate with your XBee devices.
The XBee Python Library is a Python API that dramatically reduces the time to market of XBee
projects developed in Python and facilitates the development of these types of applications, making it
an easy process.
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.

Modes
Transparent operating mode 20
API operating mode 20
Command mode 20
Idle mode 22
Transmit mode 22
Receive mode 22
Digi XBee3® DigiMesh RF Module User Guide 19

Modes Transparent operating mode
Digi XBee3® DigiMesh RF Module User Guide 20
Transparent operating mode
Devices operate in this mode by default. The device acts as a serial line replacement when it is in
Transparent operating mode. The device queues all UART data it receives through the DIN pin for RF
transmission. When a device receives RF data, it sends the data out through the DOUT pin. You can set
the configuration parameters using Command mode.
API operating mode
API operating mode is an alternative to Transparent operating mode. API mode is a frame-based
protocol that allows you to direct data on a packet basis. The device communicates UART or SPI data
in packets, also known as API frames. This mode allows for structured communications with
computers and microcontrollers.
The advantages of APIoperating mode include:
nIt is easier to send information to multiple destinations
nThe host receives the source address for each received data frame
nYou can change parameters without entering Command mode
Command mode
Command mode is a state in which the firmware interprets incoming characters as commands. It
allows you to modify the device’s configuration using parameters you can set using AT commands.
When you want to read or set any parameter of the device when operating in Transparent mode, you
have to enter Command mode and send an AT command. Every AT command starts with the letters
AT followed by the two characters that identify the command and then by some optional configuration
values.
Command mode is available on the UART interface in both Transparent and API modes. You cannot
use the SPI interface to enter Command mode.
Enter Command mode
To get a device to switch into this mode, you must issue the following sequence: GT +CC(+++) + GT.
When GT is set to the default value, if the device sees a full second of silence in the data stream (the
guard time) followed by the string +++ (without Enter or Return) and another full second of silence, it
knows to stop sending data through and start accepting commands locally.
Note Do not press Return or Enter after typing +++ because it will interrupt the guard time silence
and prevent you from entering Command mode.
When the device is in Command mode, it listens for user input and is able to receive AT commands on
the UART. If CT time (default is 10 seconds) passes without any user input, the device drops out of
Command mode and returns to Receive mode.
You can customize the command character, the guard times and the timeout in the device’s
configuration settings. For more information, see CC (Command Character),CT (Command Mode
Timeout) and GT (Guard Time).
Troubleshooting
Failure to enter Command mode is often due to baud rate mismatch. Ensure that the baud rate of the
connection matches the baud rate of the device. By default, the BD parameter = 3 (9600 baud).