Digi XBee3 DigiMesh 2.4 User manual

Digi XBee3® Cellular LTE-M
Smart Modem
User Guide

Revision history—90002258
Revision Date Description
AMay
2018
Initial release of the document.
B June
2018
0B software release. Added file system and TLS sections, ATcommands and
related changes.
C June
2018
Updated band specifications.
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 Cellular LTE-M Global Smart Modem User Guide 2

Contents
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide
Applicable firmware and hardware 11
SIM cards 11
Getting started with the XBee Smart Modem Development Kit
Identify the kit contents 13
Connect the hardware 14
XBIB-U-DEV reference 16
Cellular service 17
Configure the device using XCTU 18
Add a device 18
Check for cellular registration and connection 19
Update to the latest firmware 19
Connect to the ELIZA server 21
Debugging 22
Connect to the Echo server 23
Debugging 24
Connect to the Daytime server 25
Debugging 26
Get started with MicroPython 26
About MicroPython 26
MicroPython on the XBee Smart Modem 27
Use XCTU to enter the MicroPython environment 27
Use the MicroPython Terminal in XCTU 27
Example: hello world 28
Example: turn on an LED 28
Exit MicroPython mode 29
Other terminal programs 30
Use picocom in Linux 31
More examples 32
Perform a (GET) HTTP request 33
Get started with CoAP 35
Connect to a TCP/IP address 39
Get started with MQTT 40
Software libraries 48
Technical specifications
Interface and hardware specifications 51
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 3

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 4
Cellular RF characteristics 51
Bluetooth RF characteristics 51
Cellular networking specifications 51
Power requirements 52
Power consumption 53
Electrical specifications 54
Regulatory approvals 55
Hardware
Mechanical drawings 57
Pin signals 57
Pin connection recommendations 59
RSSI PWM 59
SIM card 59
The Associate LED 60
Antenna recommendations
Antenna placement 62
Design recommendations
Cellular component firmware updates 64
USB Direct design 64
Power supply considerations 64
Minimum connection diagram 65
Heat considerations and testing 65
Cellular connection process
Connecting 68
Cellular network 68
Data network connection 68
Data communication with remote servers (TCP/UDP) 68
Disconnecting 68
Modes
Select an operating mode 71
Transparent operating mode 72
API operating mode 72
Bypass operating mode 72
Enter Bypass operating mode 73
Leave Bypass operating mode 73
Restore cellular settings to default in Bypass operating mode 73
USB direct mode 73
Configure the data pins 73
Enable USB direct mode 73
Command mode 74
Enter Command mode 74
Troubleshooting 74

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 5
Send AT commands 75
Response to AT commands 75
Apply command changes 75
Make command changes permanent 76
Exit Command mode 76
MicroPython mode 76
Sleep modes
About sleep modes 78
Normal mode 78
Pin sleep mode 78
Cyclic sleep mode 78
Cyclic sleep with pin wake up mode 78
SPI mode and sleep pin functionality 78
The sleep timer 79
MicroPython sleep behavior 79
Power saving features
Airplane mode 81
Power Saving Mode (PSM) 81
PSM behavior 81
Deep Sleep mode 81
Serial communication
Serial interface 83
Serial data 83
UART data flow 83
Serial buffers 84
CTS flow control 84
RTS flow control 84
Enable UART or SPI ports 84
SPI operation
SPI communications 87
Full duplex operation 88
Low power operation 89
Select the SPI port 89
Force UART operation 90
Data format 90
File system
Overview of the file system 92
Directory structure 92
Paths 92
Secure files 92
XCTU interface 93
Encrypt files 93

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 6
Socket behavior
Supported sockets 95
Socket timeouts 95
Socket limits in API mode 95
Enable incoming TCP sockets in API mode 95
API mode behavior for outgoing TCP and SSL connections 95
API mode behavior for outgoing UDP data 96
API mode behavior for incoming TCP connections 96
API mode behavior for incoming UDP data 97
Transparent mode behavior for outgoing TCP and SSL connections 97
Transparent mode behavior for outgoing UDP data 97
Transparent mode behavior for incoming TCP connections 98
Transparent mode behavior for incoming UDP connections 98
Transport Layer Security (TLS)
TLS AT commands 100
Transparent mode and TLS 101
API mode and TLS 101
Key formats 101
Certificate formats 101
Certificate limitations 101
Cipher suites 102
Server Name Indication (SNI) 102
AT commands
Special commands 104
AC (Apply Changes) 104
FR (Force Reset) 104
RE (Restore Defaults) 104
WR (Write) 104
Cellular commands 105
PH (Phone Number) 105
S# (ICCID) 105
IM (IMEI) 105
MN (Operator) 105
MV (Modem Firmware Version) 106
DB (Cellular Signal Strength) 106
AN (Access Point Name) 106
CP (Carrier Profile) 106
AM (Airplane Mode) 107
Network commands 107
IP (IP Protocol) 107
TL (SSL/TLS Protocol Version) 108
$0 (SSL/TLS Profile 0) 108
$1 (SSL/TLS Profile 1) 108
$2 (SSL/TLS Profile 2) 109
TM (IP Client Connection Timeout) 109
TS (IP Server Connection Timeout) 109
DO (Device Options) 109
EQ (Remote Manager FQDN) 110
Addressing commands 110

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 7
SH (Serial Number High) 111
SL (Serial Number Low) 111
MY (Module IP Address) 111
P# (Destination Phone Number) 111
N1 (DNS Address) 111
N2 (DNS Address) 112
DL (Destination Address) 112
OD (Operating Destination Address) 112
DE (Destination Port) 112
C0 (Source Port) 113
LA (Lookup IP Address of FQDN) 113
Serial interfacing commands 113
BD (Baud Rate) 113
NB (Parity) 114
SB (Stop Bits) 114
RO (Packetization Timeout) 115
TD (Text Delimiter) 115
FT (Flow Control Threshold) 115
AP (API Enable) 115
I/O settings commands 116
D0 (DIO0/AD0) 116
D1 (DIO1/AD1) 116
D2 (DIO2/AD2) 117
D3 (DIO3/AD3) 117
D4 (DIO4) 118
D5 (DIO5/ASSOCIATED_INDICATOR) 118
D6 (DIO6/RTS) 118
D7 (DIO7/CTS) 119
D8 (DIO8/SLEEP_REQUEST) 119
P0 (DIO10/PWM0 Configuration) 120
P1 (DIO11/PWM1 Configuration) 121
P2 (DIO12 Configuration) 121
P3 (DIO13/DOUT) 122
P4 (DIO14/DIN) 122
PD (Pull Direction) 122
PR (Pull-up/down Resistor Enable) 123
M0 (PWM0 Duty Cycle) 124
I/O sampling commands 124
TP (Temperature) 124
IS (Force Sample) 124
Sleep commands 125
SM (Sleep Mode) 125
SP (Sleep Period) 126
ST (Wake Time) 126
PA (Requested Active Timer) 126
PU (Requested Tracking Area Update Timer) 126
Command mode options 127
CC (Command Sequence Character) 127
CT (Command Mode Timeout) 127
CN (Exit Command mode) 127
GT (Guard Times) 128
MicroPython commands 128
PS (Python Startup) 128
PY (MicroPython Command) 128
Firmware version/information commands 129

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 8
VR (Firmware Version) 129
VL (Verbose Firmware Version) 129
HV (Hardware Version) 130
AI (Association Indication) 130
HS (Hardware Series) 130
CK (Configuration CRC) 131
Diagnostic interface commands 131
DI (Remote Manager Indicator) 131
CI (Protocol/Connection Indication) 131
Execution commands 133
NR (Network Reset) 133
!R (Modem Reset) 133
File system commands 133
Error responses 134
ATFS (File System) 134
ATFS PWD 134
ATFS CDdirectory 134
ATFS MDdirectory 135
ATFS LS [directory] 135
ATFS PUTfilename 135
ATFS XPUTfilename 135
ATFS HASHfilename 135
ATFS GETfilename 135
ATFS MVsource_pathdest_path 135
ATFS RMfile_or_directory 136
ATFS INFO 136
ATFSFORMAT confirm 136
Operate in API mode
API mode overview 138
Use the AP command to set the operation mode 138
API frame format 138
API operation (AP parameter = 1) 138
API operation with escaped characters (AP parameter = 2) 139
API frames
AT Command - 0x08 143
Transmit (TX) SMS - 0x1F 144
Transmit (TX) Request: IPv4 - 0x20 145
Tx Request with TLS Profile - 0x23 147
AT Command Response - 0x88 149
Transmit (TX) Status - 0x89 150
Modem Status - 0x8A 152
Receive (RX) Packet: SMS - 0x9F 153
Receive (RX) Packet: IPv4 - 0xB0 154
Configure the XBee Smart Modem using Digi Remote Manager
Create a Remote Manager account 156
Get the XBee Smart Modem IMEI number 156
Add a XBee Smart Modem to Remote Manager 156

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 9
Update the firmware 157
Update the firmware using web services 157
Example: update the XBee firmware synchronously with Python 3.0 157
Example: use the device's firmware image to update the XBee firmware synchronously 158
Troubleshooting
Cannot find the serial port for the device 161
Condition 161
Solution 161
Other possible issues 162
Enable Virtual COM port (VCP) on the driver 162
Correct a macOS Java error 163
Condition 163
Solution 163
Unresponsive cellular component in Bypass mode 164
Condition 164
Solution 164
Syntax error at line 1 164
Solution 164
Error Failed to send SMS 164
Solution 164
Network connection issues 165
Condition 165
Solution 165
Brownout issue 165
Voltage brownout 165
Power-on discontinuities 165
How to distinguish revision B parts 165
Hardware flow control in Bypass mode 166
Socket leaks 166
Condition 166
Solution 167
Regulatory information
United States (FCC) 169
OEM labeling requirements 169
FCC notices 169
FCC-approved antennas 170
RF exposure 171
Innovation, Science and Economic Development Canada (ISED) 171
Labeling requirements 171
RF Exposure 171

Digi XBee3 Cellular LTE-M Global Smart Modem User
Guide
The XBee Smart Modem provides OEMs with a simple way to integrate low-power cellular connectivity
into their devices.
The XBee Smart Modem contains a u-blox R410M-02B module that also supports NB-IoT. Digi has not
released support for the NB-IoT feature. Contact your sales representative if you would like more
information about our roadmap to support NB-IoT.
Features include:
nFCC certified and carrier end-device certified
nExcellent coverage and building penetration
nManage and configure with XCTU and Digi Remote Manager®
nAvailable with Digi provided SIM cards and data plans
nDigital I/O support
nAnalog input support
nAPI and Transparent mode
nCommand mode
nBypass to the raw cellular modem
nSMS—Verizon does not currently support SMS on LTE-M.
nTCP/UDP (up to six sockets)
nTLS (up to six sockets)
nIncoming connections
nMicroPython
lOn-module programmability to add local intelligence
lMany examples in the Digi MicroPython Programming Guide
lAT commands for managing run-time behavior
nLow power modes
nLTE power save mode (PSM)
nDeep sleep mode
nPin sleep support
nCyclic sleep support
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 10

Digi XBee3 Cellular LTE-M Global Smart Modem User Guide Applicable firmware and hardware
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 11
nAirplane mode support
nDigi TrustFence secure boot
nMulti-network capability (Verizon, AT&T)
Applicable firmware and hardware
This manual supports the following firmware:
n114xx
It supports the following hardware:
nXB3-C-A2-UT-xxx
SIM cards
The XBee Smart Modem requires a 4FF (Nano) size SIM card. The SIM interface supports both 1.8 V
and 3 V SIM types.

Getting started with the XBee Smart Modem
Development Kit
This section describes how to connect the hardware in the XBee Smart Modem Development Kit, and
provides some examples you can use to communicate with the device.
There are some initial examples of how to use the device, followed by introductory MicroPython
examples and finally some advanced examples in More examples.
Identify the kit contents 13
Connect the hardware 14
XBIB-U-DEV reference 16
Cellular service 17
Configure the device using XCTU 18
Connect to the ELIZA server 21
Connect to the Echo server 23
Connect to the Daytime server 25
Get started with MicroPython 26
More examples 32
Software libraries 48
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 12

Getting started with the XBee Smart Modem Development Kit Identify the kit contents
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 13
Identify the kit contents
The Developer's kit includes the following:
One XBIB-U-DEV board
One 12 V power supply
One cellular antenna with U.FL connector
One Bluetooth Low Energy (BLE) antenna
(BLE support is forthcoming but not currently
available)
One USB cable
One XBee Smart Modem
Note The XBee Smart Modem comes
attached to the board in ESDwrap.
One SIMcard

Getting started with the XBee Smart Modem Development Kit Connect the hardware
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 14
Connect the hardware
1. The XBee Smart Modem should already be plugged into the XBIB-U-DEV board.
2. The SIMcard should already be inserted into the XBee Smart Modem. If not, install the
SIMcard into the XBee Smart Modem before attaching the XBee device to the board.
WARNING! Never insert or remove the SIM card while the device is powered!
Note The SIM cards in XBee3 Cellular LTE-M Global Smart Modem kits do not support SMS.
3. Connect the antennas to the XBee Smart Modem by aligning the U.FL connectors carefully,
then firmly pressing straight down to seat the connector. You should hear a snap when the
antenna attaches correctly. U.FL is fragile and is not designed for multiple insertions, so
exercise caution when connecting or removing the antennas. We recommend using a U.FL
removal tool.
4. Plug the 12 V power supply to the power jack on the development board.

Getting started with the XBee Smart Modem Development Kit Connect the hardware
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 15
5. Connect the USB cable from a PC to the USB port on the development board. The computer
searches for a driver, which can take a few minutes to install.

Getting started with the XBee Smart Modem Development Kit XBIB-U-DEV reference
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 16
XBIB-U-DEV reference
This picture shows the XBee USB development board and the table that follows explains the callouts
in the picture.

Getting started with the XBee Smart Modem Development Kit Cellular service
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 17
Number Item Description
1 Programmingheader Header used to program XBee programmable devices.
2 Self power module Advanced users only—voids the warranty. Depopulate R31 to
power the device using V+ and GND from J2 and J5. You can
connect sense lines to S+ and S- for sensing power supplies.
CAUTION: Voltage is not regulated. Applying the incorrect
voltage can cause fire and serious injury.1
3 Current testing Depopulating R31 allows a current probe to be inserted across P6
terminals. The current though P6/R31 powers the device only.
Other supporting circuitry is powered by a different trace.
4 Loopback jumper Populating P8 with a loopback jumper causes serial transmissions
both from the device and from the USB to loopback.
5 DC barrel plug: 6-20V Greater than 500 mA loads require a DC supply for correct
operation. Plug in the external power supply prior to the USB
connector to ensure that proper USB communications are not
interrupted.
6 LED indicator Yellow: Modem sending serial/UART data to host.
Green: Modem receiving serial/UART data from host.
Red: Associate.
7 USB
8 RSSI indicator See RSSI PWM. On the XBIB-U, more lights are better.
9 User buttons Connected to DIO lines for user implementation.
10 Reset button
11 SPI power Connect to the power board from 3.3 V.
12 SPI Only used for surface-mount devices.
13 Indicator LEDs DS5: ON/SLEEP
DS2: DIO12, the LED illuminates when driven low.
DS3: DIO11, the LED illuminates when driven low.
DS4: DIO4, the LED illuminates when driven low.
14 Through-hole XBee
sockets
15 20-pin header Maps to standard through-hole XBee pins.
Cellular service
Digi now offers Cellular Bundled Service plans. This service includes preconfigured cellular data
options that are ideal for IoT applications, bundled together with Digi Remote Manager for customers
1Powering the board with J2 and J5 without R31 removed can cause shorts if the USB or barrel plug power are
connected. Applying too high a voltage destroys electronic circuitry in the device and other board components
and/or can cause injury.

Getting started with the XBee Smart Modem Development Kit Configure the device using XCTU
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 18
who want to remotely monitor and manage their devices. To learn more, or obtain the plan that is
right for your needs, contact us:
nBy phone: [phone] (USA/toll free) or [phone] (International). Select the
Wireless Plan Support or Activation option in the menu.
nBy email: [e-mail].
The XBee Cellular kit includes six months of free cellular service.1
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.
XCTU does not work directly over an SPI interface.
For instructions on downloading and using XCTU, see the XCTU User Guide.
To use XCTU, you may need to install FTDI Virtual COMport (VCP)drivers onto your computer. Click
here to download the drivers for your operating system.
Note If you are on a macOS computer and encounter problems installing XCTU, see Correct a macOS
Java error.
Add a device
These instructions show you how to add the XBee Smart Modem to XCTU.
If XCTU does not find your serial port, see Cannot find the serial port for the device and Enable Virtual
COM port (VCP) on the driver.
1. Launch XCTU .
Note XCTU's Update the radio module firmware dialog box may open and will not allow you to
continue until you click Update or Cancel on the dialog.
2. Click Help >Check for XCTUUpdates to ensure you are using the latest version of XCTU.
3. Click the Discover radio modules button .
4. In the Discover radio devices dialog, select the serial ports where you want to look for XBee
modules, and click Next.
5. In the Set port parameters window, maintain the default values and click Finish.
6. As XCTU locates radio modules, they appear in the Discovering radio modules dialog box.
If your module could not be found, XCTU displays the Could not find any radio module dialog
providing possible reasons why the module could not be added.
1Six months of free cellular service assumes a rate of 5 Mb/month. If you exceed a limit of 30 Mb during the six
month period your SIM will be deactivated.

Getting started with the XBee Smart Modem Development Kit Configure the device using XCTU
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 19
Check for cellular registration and connection
In the following examples, proper cellular network registration and address assignment must occur
successfully. The LED on the development board blinks when the XBee Smart Modem is registered to
the cellular network; see The Associate LED. If the LEDremains solid, registration has not occurred
properly.
Registration typically takes 5 - 6 minutes the first time a device is connected to the network.
Note Make sure you are in an area with adequate cellular network reception or the XBee Smart
Modem will not make the connection.
Note Check the antenna connections if the device has trouble connecting to the network.
In addition to the LED confirmation, you can check the AT commands below in XCTU to check the
registration and connection. To view these commands:
1. Open XCTU and Add a device.
2. Click the Configuration working mode button.
3. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
4. Update to the latest firmware.
Note To search for an ATcommand in XCTU, use the search box .
The relevant commands are:
nAI (Association Indication) reads zero when the device successfully registers to the cellular
network. If it reads 23 it is connecting to the Internet; 22 means it is registering to the cellular
network.
nMY (Module IPAddress) should display a valid IPaddress. If it reads 0.0.0.0, it has not
registered yet.
Note To read a command's value, click the Read button next to the command.
Update to the latest firmware
Firmware is the program code stored in the device's persistent memory that provides the control
program for the device. Use XCTU to update the firmware.
Note If you have already updated the firmware in a previous step, this process is not necessary.
1. Click the Configuration working modes button .
2. Select a local or remote XBee module from the Radio Modules list.

Getting started with the XBee Smart Modem Development Kit Configure the device using XCTU
Digi XBee3 Cellular LTE-M Global Smart Modem User Guide 20
3. Click the Update firmware button to ensure you have the most current firmware.
The Update firmware dialog displays the available and compatible firmware for the selected
XBee module.
4. Make sure you check the Force the module to maintain its current configuration box and
then click Update.
5. Select the product family of the XBee module, the function set, and the latest firmware version.
6. Click Update. A dialog displays update progress. Click Show details for details of the firmware
update process.
See How to update the firmware of your modules in the XCTU User Guide for more information.