Digi XBee 3802.15.4 User manual

Digi XBee® 3 802.15.4
Radio Frequency (RF) Module
User Guide

Revision history—90002273
Revision Date Description
A April 2018 Initial release.
B September
2018
S2C parity release.
C April 2019 Added sleep support, file system, OTA file system updates, and several
MicroPython features.
D August
2019
Added %P and DM. Updated RR. Updates to Remote AT Command Request
frame. Added location and BLE commands. Added statuses to the 0x8A
frame. Added frames Ox2C, 0x2D, 0xAC, and 0xAD. Added Get started with
BLE and BLE reference sections. Made changes to the CCA operations
section.
E September
2019
Added *S,*V,*W,*X,*Y,SA,AZ, and FSINFOFULL. Added reserved
endpoints to 0x11 frame.
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
Digi XBee® 3 802.15.4 RF Module User Guide 2

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.
Feedback
To provide feedback on this document, email your comments to
[e-mail]
Include the document title and part number (Digi XBee® 3 802.15.4 RF Module User Guide, 90002273
E) in the subject line of your email.
Digi XBee® 3 802.15.4 RF Module User Guide 3

Contents
Digi XBee® 3 802.15.4 RF Module User Guide
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 XBee 3 802.15.4 RF Module 17
Unplug an XBee 3 802.15.4 RF Module 18
Configure the device using XCTU 18
Configure remote devices 18
Configure the devices for a range test 20
Perform a range test 21
XBIB-C Micro Mount reference 25
XBIB-C SMT reference 28
XBIB-CU TH reference 30
XBIB-C-GPS reference 32
Interface with the XBIB-C-GPS module 34
I2C communication 35
UART communication 35
Run the MicroPython GPS demo 35
Get started with MicroPython
About MicroPython 38
MicroPython on the XBee 3 802.15.4 RF Module 38
Use XCTU to enter the MicroPython environment 38
Use the MicroPython Terminal in XCTU 39
MicroPython examples 39
Example: hello world 39
Example: enter MicroPython paste mode 39
Example:use the time module 40
Example: AT commands using MicroPython 40
MicroPython networking and communication examples 41
Exit MicroPython mode 47
Other terminal programs 48
Tera Term for Windows 48
Use picocom in Linux 49
Digi XBee® 3 802.15.4 RF Module User Guide 4

Digi XBee® 3 802.15.4 RF Module User Guide 5
Micropython help () 50
Secure access
Secure Sessions 53
Configure the secure session password for a device 53
Start a secure session 53
End a secure session 54
Secured remote AT commands 54
Secure a node against unauthorized remote configuration 54
Remotely configure a node that has been secured 55
Send data to a secured remote node 56
End a session from a server 56
Secure Session API frames 57
Secure transmission failures 58
Data Frames - 0x10 and 0x11 frames 58
Remote AT Commands- 0x17 frames 58
File system
Overview of the file system 60
Directory structure 60
Paths 60
Limitations 60
XCTU interface 61
Get started with BLE
Enable BLE on the XBee 3 802.15.4 RF Module 63
Enable BLEand configure the BLEpassword 63
Get the Digi XBeeMobile phone application 64
Connect with BLEand configure your XBee 3 device 65
BLE reference
BLE advertising behavior and services 67
Device Information Service 67
XBee API BLEService 67
API Request characteristic 67
API Response characteristic 68
Configure the XBee 3 802.15.4 RF Module
Software libraries 70
Firmware over-the-air (FOTA) update 70
Custom defaults 70
Set custom defaults 70
Restore factory defaults 70
Limitations 70
Custom configuration: Create a new factory default 71
Set a custom configuration 71
Clear all custom configuration on a device 71

Digi XBee® 3 802.15.4 RF Module User Guide 6
XBee bootloader 71
Send a firmware image 72
XBee Network Assistant 72
XBee Multi Programmer 73
Modes
Transparent operating mode 75
Serial-to-RF packetization 75
API operating mode 75
Command mode 75
Enter Command mode 76
Troubleshooting 76
Send AT commands 76
Response to AT commands 77
Apply command changes 77
Make command changes permanent 77
Exit Command mode 77
Idle mode 78
Transmit mode 78
Receive mode 78
Serial communication
Serial interface 80
Serial receive buffer 80
Serial transmit buffer 80
UART data flow 80
Serial data 80
Flow control 81
Clear-to-send (CTS) flow control 81
RTS flow control 82
SPI operation
SPI communications 84
Full duplex operation 85
Low power operation 85
Select the SPI port 86
Force UART operation 87
I/O support
Legacy support 89
Mixed network considerations 90
Digital I/O support 90
Analog I/O support 91
Monitor I/O lines 92
I/O sample data format 93
Legacy data format 93
Enhanced data format 94
API frame support 95
On-demand sampling 96

Digi XBee® 3 802.15.4 RF Module User Guide 7
Example: Command mode 96
Example: Local AT command in API mode 97
Example: Remote AT command in API mode 97
Periodic I/O sampling 98
Source 98
Destination 99
Multiple samples per packet 99
Example: Remote AT command in API mode 99
Digital I/O change detection 100
I/O line passing 101
Digital line passing 101
Example:Digital line passing 102
Analog line passing 102
Example:Analog line passing 102
Output sample data 103
Output control 103
I/O behavior during sleep 103
Digital I/O lines 103
Analog and PWM I/O Lines 104
Networking
Networking terms 106
MAC Mode configuration 106
Clear Channel Assessment (CCA) 107
CCA operations 107
Retries configuration 107
Transmit status based on MAC mode and XBee retries configurations 108
Addressing 109
Send packets to a specific device in Transparent APImode 109
Addressing modes 109
Peer-to-peer networks 110
Master/slave networks 110
End device association 110
Coordinator association 111
Association indicators 112
Modem status messages 112
Association indicator status codes 113
Direct and indirect transmission 113
Configure an indirect messaging coordinator 114
Send indirect messages 114
Receive indirect messages 114
Encryption 115
Maximum payload 116
Maximum payload rules 116
Maximum payload summary tables 117
Work with Legacy devices 118
Network commissioning and diagnostics
Remote configuration commands 120
Send a remote command 120
Apply changes on remote devices 120
Remote command responses 120

Digi XBee® 3 802.15.4 RF Module User Guide 8
Node discovery 120
About node discovery 121
Node discovery in compatibility mode 121
Directed node discovery 121
Directed node discovery in compatibility mode 122
Destination Node 122
Sleep support
Sleep modes 124
Pin Sleep mode (SM = 1) 124
Cyclic Sleep mode (SM = 4) 124
Cyclic Sleep with Pin Wake-up mode (SM = 5) 125
MicroPython sleep with optional pin wake (SM = 6) 125
Sleep parameters 125
Sleep pins 125
Sleep conditions 126
AT commands
Network and security commands 128
CH (Operating Channel) 128
ID (Extended PAN ID) 128
C8 (Compatibility Options) 128
NI (Node Identifier) 130
ND (Network Discover) 130
DN (Discover Node) 131
NT (Node Discover Timeout) 132
NO (Node Discovery Options) 132
MM (MAC Mode) 132
NP (Maximum Packet Payload Bytes) 133
Coordinator/End Device configuration commands 133
CE (Coordinator Enable) 133
A1 (End Device Association) 134
A2 (Coordinator Association) 134
SC (Scan Channels) 135
DA (Force Disassociation) 136
AI (Association Indication) 136
802.15.4 Addressing commands 137
SH (Serial Number High) 137
SL (Serial Number Low) 137
MY (16-bit Source Address) 137
DH (Destination Address High) 138
DL (Destination Address Low) 138
RR (XBee Retries) 138
TO (Transmit Options) 139
Security commands 139
EE (Encryption Enable) 139
KY (AES Encryption Key) 140
DM (Disable Features) 140
RF interfacing commands 140
PL (TX Power Level) 140
PP (Output Power in dBm) 141
CA (CCA Threshold) 141

Digi XBee® 3 802.15.4 RF Module User Guide 9
RN (Random Delay Slots) 142
DB (Last Packet RSSI) 142
MAC diagnostics commands 142
AS (Active Scan) 142
ED (Energy Detect) 143
EA (ACK Failures) 144
EC (CCA Failures) 144
Sleep settings commands 144
SM (Sleep Mode) 144
SP (Cyclic Sleep Period) 145
ST (Time before Sleep) 145
DP (Disassociated Cyclic Sleep Period) 146
SO (Sleep Options) 146
FP (Force Poll) 147
UART interface commands 147
BD (Interface Data Rate) 147
NB (Parity) 148
SB (Stop Bits) 148
FT (Flow Control Threshold) 149
RO (Packetization Timeout) 149
AP(API Enable) 149
AO (API Output Options) 150
AZ (Extended API Options) 150
Command mode options 151
CC (Command Character) 151
CT (Command Mode Timeout) 151
GT (Guard Times) 151
CN (Exit Command mode) 151
UART pin configuration commands 152
D6 (DIO6/RTS Configuration) 152
D7 (DIO7/CTS Configuration) 152
P3 (DIO13/UART_DOUT Configuration) 153
P4 (DIO14/UART_DIN Configuration) 153
SPI interface commands 154
P5 (DIO15/SPI_MISO Configuration) 154
P6 (DIO16/SPI_MOSI Configuration) 154
P7 (DIO17/SPI_SSEL Configuration) 155
P8 (DIO18/SPI_CLK Configuration) 155
P9 (DIO19/SPI_ATTN Configuration) 155
I/O settings commands 156
D0 (DIO0/ADC0/Commissioning Configuration) 156
CB (Commissioning Button) 156
D1 (DIO1/ADC1/TH_SPI_ATTN Configuration) 157
D2 (DIO2/ADC2/TH_SPI_CLK Configuration) 157
D3 (DIO3/ADC3/TH_SPI_SSEL Configuration) 158
D4 (DIO4/TH_SPI_MOSI Configuration) 158
D5 (DIO5/Associate Configuration) 159
D8 (DIO8/DTR/SLP_Request Configuration) 159
D9 (DIO9/ON_SLEEP Configuration) 160
P0 (DIO10/RSSI/PWM0 Configuration) 160
P1 (DIO11/PWM1 Configuration) 161
P2 (DIO12/TH_SPI_MISO Configuration) 161
PR (Pull-up/Down Resistor Enable) 162
PD (Pull Up/Down Direction) 163
M0 (PWM0 Duty Cycle) 163

Digi XBee® 3 802.15.4 RF Module User Guide 10
M1 (PWM1 Duty Cycle) 164
RP (RSSI PWM Timer) 164
LT (Associate LED Blink Time) 164
I/O sampling commands 165
IS (I/O Sample) 165
IR (Sample Rate) 166
IC (DIO Change Detect) 166
AV (Analog Voltage Reference) 167
IT (Samples before TX) 167
IF (Sleep Sample Rate) 168
IO (Digital Output Level) 168
I/O line passing commands 168
IA (I/O Input Address) 168
IU (I/O Output Enable) 168
T0 (D0 Timeout Timer) 169
T1 (D1 Output Timeout Timer) 169
T2 (D2 Output Timeout Timer) 169
T3 (D3 Output Timeout Timer) 169
T4 (D4 Output Timeout Timer) 170
T5 (D5 Output Timeout Timer) 170
T6 (D6 Output Timeout Timer) 170
T7 (D7 Output Timeout Timer) 170
T8 (D8 Output Timer) 171
T9 (D9 Output Timer) 171
Q0 (P0 Output Timer) 171
Q1 (P1 Output Timer) 171
Q2 (P2 Output Timer) 171
PT (PWM Output Timeout) 172
Location commands 172
LX (Location X) 172
LY (Location Y) 172
LZ (Location Z) 172
Diagnostic commands - firmware/hardware information 173
VR (Firmware Version) 173
VL (Version Long) 173
VH (Bootloader Version) 173
HV (Hardware Version) 173
%C (Hardware/Software Compatibility) 173
%P (Invoke Bootloader) 174
%V (Supply Voltage) 174
TP (Module Temperature) 174
DD (Device Type Identifier) 174
CK (Configuration CRC) 175
FR (Software Reset) 175
MicroPython commands 175
PS (Python Startup) 175
PY (MicroPython Command) 175
File system commands 176
FS (File System) 176
FK (File System Public Key) 178
Memory access commands 179
AC (Apply Changes) 179
WR (Write) 179
RE (Restore Defaults) 179
BLE commands 180

Digi XBee® 3 802.15.4 RF Module User Guide 11
BL (Bluetooth MAC Address) 180
BT (Bluetooth Enable) 180
$S (SRP Salt) 180
$V, $W, $X, $Y commands (SRPSalt verifier) 181
Custom default commands 181
%F (Set Custom Default) 181
!C (Clear Custom Defaults) 181
R1 (Restore Factory Defaults) 182
Secure Session commands 182
*S (Secure Session Salt) 182
*V, *W, *X, *Y (Secure Session Verifier) 182
SA (Secure Access) 182
Operate in API mode
API mode overview 185
Use the AP command to set the operation mode 185
API frame format 185
API operation (AP parameter = 1) 185
API operation with escaped characters (AP parameter = 2) 186
Frame descriptions
TX Request: 64-bit address frame - 0x00 190
TX Request: 16-bit address - 0x01 191
AT Command frame - 0x08 192
AT Command - Queue Parameter Value frame - 0x09 194
Transmit Request frame - 0x10 194
Explicit Addressing Command frame - 0x11 196
Remote AT Command Request frame - 0x17 200
BLE Unlock API frame - 0x2C 201
Example sequence to perform AT Command XBee API frames over BLE 203
User Data Relay frame - 0x2D 204
Example use cases 205
Example 205
Secure Session Control frame - 0x2E 206
RX Packet: 64-bit Address frame - 0x80 210
Receive Packet: 16-bit address frame - 0x81 211
RX (Receive) Packet: 64-bit address IO frame - 0x82 212
RX Packet: 16-bit address I/O frame - 0x83 214
AT Command Response frame - 0x88 216
TX Status frame - 0x89 218
Modem Status frame - 0x8A 220
Transmit Status frame - 0x8B 221
Receive Packet frame - 0x90 223
Explicit Rx Indicator frame - 0x91 225
I/O Data Sample Rx Indicator frame - 0x92 227
Remote Command Response frame - 0x97 229
Extended Modem Status frame - 0x98 229
BLE Unlock Response frame - 0xAC 231
User Data Relay Output - 0xAD 232
Description 232
Format 232
Example 232

Digi XBee® 3 802.15.4 RF Module User Guide 12
Secure Session Response frame - 0xAE 233
Over-the-air firmware/filesystem upgrade process for 802.15.4
FOTA upgrade image file formats 236
OTA/OTB file 236
fs.ota file 236
The OTA header 236
Hardware/software compatibility 237
Parse the image blocks 237
Storage 237
ZCL OTA messaging 237
ZCL message output 238
Image Notify 238
Create the Image Notify request 239
Query Next Image request 240
Query Next Image response 242
Image Block request 244
Image Block response 246
Upgrade End request 249
Upgrade End response 250
OTA error handling 253
Default response commands 253
Upgrade End Request error statuses 254
OTA file system upgrades
OTA file system update process 257
OTA file system updates using XCTU 257
Generate a public/private key pair 257
Set the public key on the XBee 3 device 258
Create the OTA file system image 259
Perform the OTA file system update 260
OTA file system updates: OEM 261
Generate a public/private key pair 262
Set the public key on the XBee 3 device 262
Create the OTA file system image 262
Perform the OTA file system update 263

Digi XBee® 3 802.15.4 RF Module User Guide
XBee 3 802.15.4 RF Modules are embedded solutions providing wireless end-point connectivity to
devices. These devices use the IEEE 802.15.4 networking protocol for fast point-to-multipoint or peer-
to-peer networking. They are designed for high-throughput applications requiring low latency and
predictable communication timing.
The XBee 3 802.15.4 RF Module supports the needs of low-cost, low-power wireless sensor networks.
The devices require minimal power and provide reliable delivery of data between devices. The devices
operate within the ISM 2.4 GHz frequency band.
The XBee 3 802.15.4 RF Module uses XBee 3 hardware and the Silicon Labs EFR32 chipset. As the
name suggests, the 802.15.4 module is over-the-air compatible with our Legacy 802.15.4 modules (S1
and S2C hardware).
For information about XBee 3 hardware, see the XBee 3 RF Module Hardware Reference Manual.
Applicable firmware and hardware 14
Change the firmware protocol 14
Regulatory information 14
Digi XBee® 3 802.15.4 RF Module User Guide 13

Digi XBee® 3 802.15.4 RF Module User Guide Applicable firmware and hardware
Digi XBee® 3 802.15.4 RF Module User Guide 14
Applicable firmware and hardware
This manual supports the following firmware:
nv.20xx Digi 802.15.4
It supports the following hardware:
nXBee 3
Change the firmware protocol
You can switch the firmware loaded onto the XBee 3 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 XBee 3 RF Module Hardware Reference Manual for the
XBee 3 hardware's regulatory and certification information.

Get started
This section covers the following tasks and features:
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 20
Perform a range test 21
XBIB-C Micro Mount reference 25
XBIB-C SMT reference 28
XBIB-CU TH reference 30
XBIB-C-GPS reference 32
Interface with the XBIB-C-GPS module 34
Digi XBee® 3 802.15.4 RF Module User Guide 15

Get started Verify kit contents
Digi XBee® 3 802.15.4 RF Module User Guide 16
Verify kit contents
The XBee 3 802.15.4 RF Module development kit contains the following components:
Part
XBee 3 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 XBee 3 802.15.4 RF Module
nUnplug an XBee 3 802.15.4 RF Module

Get started Assemble the hardware
Digi XBee® 3 802.15.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 XBee 3 802.15.4 RF Module
This kit includes two 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 XBee 3 802.15.4 RF Module into each 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.
CAUTION! Never insert or remove the XBee while the power is on (either from the
micro USB or a battery)!
For XBee SMT devices, align all XBee pins with the spring header and carefully push the device
until it clicks firmly into the board.

Get started Configure the device using XCTU
Digi XBee® 3 802.15.4 RF Module User Guide 18
2. Once theXBee 3 802.15.4 RF Module is plugged into the board, connect the board to your
computer using the micro USB cables provided.
3. Ensure the loopback jumper is in the UART position.
Unplug an XBee 3 802.15.4 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 XBee 3 802.15.4 RF Module.
CAUTION! Make sure the board is not powered when you remove the XBee 3 802.15.4 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 the LT (Associate LED Blink Time) parameter on a
remote device.

Get started Configure remote devices
Digi XBee® 3 802.15.4 RF Module User Guide 19
1. Add two XBee devices to XCTU.
2. Load XBee 3 802.15.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
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 .

Get started Configure the devices for a range test
Digi XBee® 3 802.15.4 RF Module User Guide 20
7. Click Add selected devices in the Discovering remote devices dialog. The discovered remote
device appears below XBEE_A.
8. Select the remote device XBEE_B, and configure the following parameter:
LT: FF (hexadecimal representation for 2550 ms)
9. Click the Write radio settings button .
The remote XBee device now has a different LED blink time.
10. To return to the default LED blink times, change the LT parameter back to 0for XBEE_B.
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
AP: Transparent mode [0] (The remote node must be in transparent mode to loop back
packets)
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.