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.
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
techcomm@digi.com.
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 Cat 1 Smart Modem User Guide
2
Contents
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
Applicable firmware and hardware9
SIM cards9
Getting started with the XBee Smart Modem Development Kit
Identify the kit contents11
XBIB-U-DEV reference12
Cellular service13
Connect the hardware14
Configure the device using XCTU15
Add a device15
Check for cellular registration and connection16
Update to the latest firmware16
Send an SMS message to a phone18
Debugging19
Connect to the ELIZA server20
Debugging21
Connect to the echo server22
Debugging23
Connect to the Daytime server24
Debugging25
Connect to a TCP/IP address26
Debugging27
Perform a (GET) HTTP request28
Debugging29
Get started with MQTT30
Example: MQTT connect30
Send a connect packet32
Example: send messages (publish) with MQTT34
Example: receive messages (subscribe) with MQTT34
Use MQTT over the XBee Cellular Modem with a PC35
Get started with CoAP39
CoAP terms39
CoAP quick start example39
Configure the device40
Example: manually perform a CoAPrequest40
Example: use Python to generate a CoAP message41
Configure the XBee Smart Modem using Digi Remote Manager44
Create a Remote Manager account44
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
3
Get the XBee Smart Modem IMEI number44
Add a XBee Smart Modem to Remote Manager44
Update the firmware45
Software libraries45
Get started with MicroPython
About MicroPython47
Why use MicroPython47
MicroPython on the XBee Smart Modem47
Use XCTU to enter the MicroPython environment47
Use the MicroPython Terminal in XCTU48
Example: hello world48
Example: turn on an LED48
Example: code a request help button49
Enter MicroPython paste mode50
Catch a button press50
Send a text (SMS) when the button is pressed52
Add the time the button was pressed53
Exit MicroPython mode54
Other terminal programs54
Tera Term for Windows54
Use picocom in Linux55
Technical specifications
Interface and hardware specifications58
RF characteristics58
Networking specifications58
Power requirements58
Power consumption59
Electrical specifications59
Regulatory approvals60
Hardware
Mechanical drawings62
Pin signals62
Pin connection recommendations63
RSSI PWM64
SIM card64
The Associate LED64
Antenna recommendations
Antenna connections67
Antenna placement68
Design recommendations
Cellular component firmware upgrades70
USB Direct design70
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
4
Power supply considerations70
Add a capacitor to the RESET line70
Heat considerations and testing71
Heat sink guidelines71
Add a fan to provide active cooling73
Cellular connection process
Connecting75
Cellular network75
Data network connection75
Data communication with remote servers (TCP/UDP)75
Disconnecting75
SMS encoding76
Modes
Select an operating mode78
Transparent operating mode79
API operating mode79
Bypass operating mode79
Enter Bypass operating mode79
Leave Bypass operating mode80
Restore cellular settings to default in Bypass operating mode80
USB direct mode80
Enable USB direct mode80
Command mode80
Enter Command mode81
Send AT commands81
Apply command changes82
Make command changes permanent82
Exit Command mode82
Sleep modes
About sleep modes84
Normal mode84
Pin sleep mode84
Cyclic sleep mode84
Cyclic sleep with pin wake up mode84
Airplane mode84
Connected sleep mode84
The sleep timer85
MicroPython sleep behavior85
Serial communication
Serial interface87
Serial data87
UART data flow87
Serial buffers87
CTS flow control88
RTS flow control88
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
5
AT commands
MicroPython commands90
PS (Python Startup)90
PY (MicroPython Command)90
Special commands91
AC (Apply Changes)91
FR (Force Reset)91
RE command92
WR command92
Cellular commands92
PH (Phone Number)92
S# (ICCID)92
IM (IMEI)93
MN (Operator)93
MV (Modem Firmware Version)93
DB (Cellular Signal Strength)93
AN (Access Point Name)93
OA (Operating APN)94
AM (Airplane Mode)94
DV (Antenna Diversity)94
Network commands95
IP (IP Protocol)95
TL (SSL/TLS Protocol Version)95
TM (IP Client Connection Timeout)95
TS (IP Server Connection Timeout)96
DO (Device Options)96
EQ (Device Cloud FQDN)96
Addressing commands97
SH (Serial Number High)97
SL (Serial Number Low)97
DL (Destination Address)97
P# (Destination Phone Number)97
N1 (DNS Address)98
N2 (DNS Address)98
DE (Destination Port)98
TD (Text Delimiter)98
MY (Module IP Address)99
LA (Lookup IP Address of FQDN)99
OD (Operating Destination Address)99
C0 (Source Port)99
Serial interfacing commands100
BD (Baud Rate)100
NB (Parity)101
SB (Stop Bits)101
RO (Packetization Timeout)101
FT (Flow Control Threshold)101
AP (API Enable)102
I/O settings commands102
D0 (DIO0/AD0)102
D1 (DIO1/AD1)103
D2 (DIO2/AD2)103
D3 (DIO3/AD3)104
D4 (DIO4)104
D5 (DIO5/ASSOCIATED_INDICATOR)105
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
CK (Configuration CRC)114
Diagnostic interface commands114
DI (Device Cloud Indicator)114
CI (Protocol/Connection Indication)114
Execution commands116
NR (Network Reset)116
!R (Modem Reset)117
IS (Force Sample)117
Operate in API mode
API mode overview120
Use the AP command to set the operation mode120
API frame format120
API operation (AP parameter = 1)120
API operation with escaped characters (AP parameter = 2)121
Frame descriptions124
AT Command - 0x08124
Transmit (TX) SMS - 0x1F125
Transmit (TX) Request: IPv4 - 0x20126
AT Command Response - 0x88127
Transmit (TX) Status - 0x89128
Modem Status - 0x8A129
Receive (RX) Packet: SMS - 0x9F130
Receive (RX) Packet: IPv4 - 0xB0131
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
7
Socket behavior
Supported sockets133
Secure Sockets Layer (SSL) certificate checking133
Socket timeouts133
Socket limits in API mode133
Enable incoming TCP connections133
API mode behavior for outgoing TCP and SSL connections134
API mode behavior for outgoing UDP data134
API mode behavior for incoming TCP connections135
API mode behavior for incoming UDP data135
Transparent mode behavior for outgoing TCP and SSL connections135
Transparent mode behavior for outgoing UDP data136
Transparent mode behavior for incoming TCP connections136
Transparent mode behavior for incoming UDP connections136
Troubleshooting
Cannot find the serial port for the device138
Condition138
Solution138
Correct a macOS Java error140
Condition140
Solution140
Unresponsive cellular component in Bypass mode141
Condition141
Solution141
Not on expected network after APN change142
Condition142
Solution142
Syntax error at line 1142
Solution142
Error Failed to send SMS142
Solution142
Regulatory information
Modification statement144
Interference statement144
FCC Class B digital device notice144
RF exposure145
FCC-approved antennas145
Bluetooth antennas145
Dipole antennas145
Flex PCB antennas145
Cellular antennas146
Labeling requirements for the host device146
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
8
Digi XBee3 Cellular LTE Cat 1 Smart Modem User
Guide
The XBee Smart Modem is an embedded Long-Term Evolution (LTE) Category 1 cellular module that
provides original equipment manufacturers (OEMs) with a simple way to integrate cellular
connectivity into their devices.
The XBee Smart Modem enables OEMs to quickly integrate cutting edge 4G cellular technology into
their devices and applications without dealing with the painful, time-consuming, and expensive FCC
and carrier end-device certifications.
With the full suite of standard XBee API frames and AT commands, existing XBee customers can
seamlessly transition to this new device with only minor software adjustments. When OEMs add the
XBee Smart Modem to their product, they create a future-proof design with flexibility to switch
between wireless protocols or frequencies as needed.
You can read some frequently asked questions here.
Applicable firmware and hardware
This manual supports the following firmware:
n 310xx
It supports the following hardware:
n XB3-C-A1-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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
9
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.
Identify the kit contents11
XBIB-U-DEV reference12
Cellular service13
Connect the hardware14
Configure the device using XCTU15
Send an SMS message to a phone18
Connect to the ELIZA server20
Connect to the echo server22
Connect to the Daytime server24
Connect to a TCP/IP address26
Perform a (GET) HTTP request28
Get started with MQTT30
Get started with CoAP39
Configure the XBee Smart Modem using Digi Remote Manager44
Software libraries45
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
10
Getting started with the XBee Smart Modem Development KitIdentify the kit contents
Identify the kit contents
The Developer's kit includes the following:
One XBIB-U-DEV board
One 12 V power supply
Two cellular antennas with U.FL connectors
One USB cable
One XBee Smart Modem
One SIMcard
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
11
Getting started with the XBee Smart Modem Development KitXBIB-U-DEV reference
XBIB-U-DEV reference
This picture shows the XBee USB development board and the table that follows explains the callouts
in the picture.
Number ItemDescription
1Programmingheader Header used to program XBee Programmable devices.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
12
Getting started with the XBee Smart Modem Development KitCellular service
Number ItemDescription
2Self power module
3Current testingDepopulating R31 allows a current probe to be inserted across P6
4Loopback jumperPopulating P8 with a loopback jumper causes serial transmissions
5DC barrel plug: 6-20V Greater than 500 mA loads require a DC supply for correct
6LED indicator
7USB
8RSSI indicator
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.
terminals. The current though P6/R31 powers the device only.
Other supporting circuitry is powered by a different trace.
both from the device and from the USB to loopback.
operation. Plug in the external power supply prior to the USB
connector to ensure that proper USB communications are not
interrupted.
Yellow: Modem sending serial/UART data to host.
Green: Modem receiving serial/UART data from host.
Red: Associate.
1
9User buttonsConnected to DIO lines for user implementation.
10Reset button
11SPI powerConnect to the power board from 3.3 V.
12SPIOnly used for surface-mount devices.
13Indicator LEDs
14Through-hole XBee
sockets
1520-pin headerMaps to standard through-hole XBee pins.
Cellular service
The XBee Cellular kit includes six months of free cellular service.
1
Powering 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.
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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
13
Getting started with the XBee Smart Modem Development KitConnect the hardware
Connect the hardware
1. The XBee Smart Modem should already be plugged into the XBIB-U-DEV board.
2. The SIMcard should be already be inserted into the XBee Smart Modem. If not, install the
SIMcard into the XBee Smart Modem.
WARNING! Never insert or remove the SIM card while the device is powered!
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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
14
Getting started with the XBee Smart Modem Development KitConfigure the device using XCTU
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.
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.
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.
Launch XCTU.
1.
Click the Discover radio modules button.
2.
3. In the Discover radio devices dialog, select the serial ports where you want to look for XBee
modules, and click Next.
4. In the Set port parameters window, maintain the default values and click Finish.
5. 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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
15
Getting started with the XBee Smart Modem Development KitConfigure the device using XCTU
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 LEDremains solid, registration has not occurred
properly. Registration can take several minutes.
Note Make sure you are in an area with adequate cellular network reception or the XBee Smart
Modem will not make the connection.
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.
Click the Configuration working modebutton.
2.
3. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
On the Configuration toolbar, click the Default buttonto load the default values
4.
established by the firmware, and click Yes to confirm.
The relevant commands are:
n AI (Association Indication) reads zero when the device successfully registers to the cellular
network. If it reads 0x23 it is connecting to the Internet; 0x22 means it is registering to the
cellular network.
n MY (Module IPAddress) should display a valid IPaddress. If it reads 0.0.0.0, it has not
registered yet.
Note To search for an ATcommand in XCTU, use the search box.
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.
Click the Configuration working modes button.
1.
2. Select a local XBee module from the Radio Modules list.
Click the Update firmware button.
3.
The Update firmware dialog displays the available and compatible firmware for the selected
XBee module.
4. Select the product family of the XBee module, the function set, and the latest firmware version.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
16
Getting started with the XBee Smart Modem Development KitConfigure the device using XCTU
5. 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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
17
Getting started with the XBee Smart Modem Development KitSend an SMS message to a phone
Send an SMS message to a phone
The XBee Smart Modem can send and receive Short Message Service (SMS) transmissions (text
messages) while in Transparent mode. This allows you to send and receive text messages to and from
an SMS capable device such as a mobile phone.
The following table explains the AT commands that you use in this example.
CommandValueDescription
AP (APIEnable)
IP (IP Protocol)
P#
(DestinationPhone
Number)
TD (Text Delimiter)
PH (Module's SIM
phone number)
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
0Set the device's API mode to Transparent mode.
2Set the expected transmission mode to SMScommunication.
<Target
phone
number>
D (0x0D)
Read
only
The target phone number that you send to, for example, your
cellular phone. See P# (Destination Phone Number) for instructions
on using this command.
The text delimiter to be used for Transparent mode, as an ASCII hex
code. No information is sent until this character is entered, unless
the maximum number of characters has been reached. Set to zero
to disable text delimiter checking. Set to D for a carriage return.
The value that represents your device's phone number as supplied
by the SIM card. This is used to send text messages to the device
from another cellular device.
To switch to SMS communication, in the IP field, select 2 and click the Write button.
5.
6. To enter your cell phone number, in the P# field, type the <target phone number> and click
the Write button. Type the phone number using only numbers, with no dashes. You can use the
+ prefix if necessary. The target phone number is the phone number you wish to send a text to.
7. In the TD field, type D and click the Write button.
8. Note the number in the PH field; it is the XBee Smart Modem phone number, which you see
when it sends an SMS to your phone.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
18
Getting started with the XBee Smart Modem Development KitSend an SMS message to a phone
Click the Consoles working mode buttonon the toolbar to open a serial console to the
9.
device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.
Click the Open buttonto open a serial connection to the device.
10.
11. Click in the left pane of the Console log, type hello world and press Enter. The XBee Smart
Modem sends the message to the destination phone number set by the P# command.
12. When the phone receives the text, you can see that the sender's phone number matches the
value reported by the XBee Smart Modem with the PH command.
13. On the phone, reply with the text connect with confidence and the XBee Smart Modem
outputs this reply from the UART.
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
19
Getting started with the XBee Smart Modem Development KitConnect to the ELIZA server
Connect to the ELIZA server
You can use the XBee Smart Modem to chat with the ELIZA Therapist Bot. ELIZAis an artificial
intelligence (AI) bot that emulates a therapist and can perform simple conversations.
The following table explains the AT commands that you use in this example.
At commandValueDescription
IP (IP Protocol)1Set the expected transmission mode to TCP
communications.
DL (Destination
Address)
DE (Destination Port)0x2328The target port number of the Eliza server.
To communicate with the ELIZA Therapist Bot:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
To switch to TCP communication, in the IP field, select 1 and click the Write button.
5.
6. To enter the destination address of the ELIZATherapist Bot, in the DL field, type 52.43.121.77
and click the Write button.
52.43.121.77 The target IP address of the Eliza server.
7. To enter the destination IP port number, in the DE field, type 2328 and click the Write button.
Click the Consoles working mode buttonon the toolbar to open a serial console to the
8.
device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.
Click the Open buttonto open a serial connection to the device.
9.
10. Click in the left pane of the Console log, then type in the Console to talk to the ELIZA Therapist
Bot. The following screenshot provides an example of this chat.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
20
Getting started with the XBee Smart Modem Development KitConnect to the ELIZA server
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
21
Getting started with the XBee Smart Modem Development KitConnect to the echo server
Connect to the echo server
This server echoes back the messages you type.
The following table explains the AT commands that you use in this example.
At
commandValueDescription
IP (IP
Protocol)
TD
(Text
Delimiter)
DL
(Destination
Address)
DE
(Destination
Port)
To communicate with the echo server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
1Set the expected transmission mode to TCP communications.
D (0x0D)
52.43.121.77 The target IPaddress of the echo server.
0x2329The target port number of the echo server.
The text delimiter to be used for Transparent mode, as an ASCII hex
code. No information is sent until this character is entered, unless the
maximum number of characters has been reached. Set to zero to
disable text delimiter checking. Set to D for a carriage return.
To switch to TCP communication, in the IP field, select 1 and click the Write button.
5.
6. To enable the XBee Smart Modem to recognize carriage return as a message delimiter, in the
TD field, type D and click the Write button.
7. To enter the destination address of the echo server, in the DL field, type 52.43.121.77 and click
the Write button.
8. To enter the destination IP port number, in the DE field, type 2329 and click the Write button.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
22
Getting started with the XBee Smart Modem Development KitConnect to the echo server
Click the Consoles working mode buttonon the toolbar to open a serial console to the
9.
device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.
Click the Open buttonto open a serial connection to the device.
10.
11. Click in the left pane of the Console log, then type in the Console to talk to the echo server.
The following screenshot provides an example of this chat.
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
23
Getting started with the XBee Smart Modem Development KitConnect to the Daytime server
Connect to the Daytime server
The Daytime server reports the current Coordinated Universal Time (UTC) value responding to any
user input.
The following table explains the AT commands that you use in this example.
At
commandValueDescription
IP (IP
Protocol)
DL
(Destination
Address)
DE
(Destination
Port)
TD (Text
Delimiter)
To communicate with the Daytime server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
1Set the expected transmission mode to TCP communications.
52.43.121.77 The target IP of the Daytime server.
0x232AThe target port number of the Daytime server.
0
The text delimiter to be used for Transparent mode, as an ASCII hex
code. No information is sent until this character is entered, unless the
maximum number of characters has been reached. Set to zero to
disable text delimiter checking.
To switch to TCP communication, in the IP field, select 1 and click the Write button.
5.
6. To enter the destination address of the daytime server, in the DL field, type 52.43.121.77 and
click the Write button.
7. To enter the destination IP port number, in the DE field, type 232A and click the Write button.
8. To disable text delimiter checking, in the TD field, type 0 and click the Write button.
Click the Consoles working mode buttonon the toolbar to open a serial console to the
9.
device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
24
Getting started with the XBee Smart Modem Development KitConnect to the Daytime server
Click the Open buttonto open a serial connection to the device.
10.
11. Click in the left pane of the Console log, then type in the Console to query the Daytime server.
The following screenshot provides an example of this chat.
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
25
Getting started with the XBee Smart Modem Development KitConnect to a TCP/IP address
Connect to a TCP/IP address
The XBee Smart Modem can send and receive TCP messages while in Transparent mode; see
Transparent operating mode.
You can use this example as a template for sending and receiving data from a user. The following table
explains the AT commands that you use in this example.
CommandValueDescription
IP (IP
Protocol)
DL
(Destination
IPAddress)
DE
(Destination
Port)
To connect to a TCP/IP address:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
1Set the expected transmission mode to TCPcommunication.
<Target
IPaddress>
<Target
portnumber>
The target IP address that you send and receive from. For example, a
data logging server’s IP address that you want to send
measurements to.
The target port number that the device sends the transmission to.
This is represented as a hexadecimal value.
In the IP field, select 1 and click the Write button.
5.
6. In the DL field, type the <target IP address> and click the Write button. The target IP address
is the IPaddress that you send and receive from.
7. In the DE field, type the <target port number>, converted to hexadecimal, and click the Write
button.
8. Exit Command mode; see Exit Command mode.
After exiting Command mode, any UART data sent to the device is sent to the destination IP address
and port number after the RO (Packetization Timeout) occurs.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
26
Getting started with the XBee Smart Modem Development KitConnect to a TCP/IP address
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
27
Getting started with the XBee Smart Modem Development KitPerform a (GET) HTTP request
Perform a (GET) HTTP request
You can use the XBee Smart Modem to perform a GET Hypertext Transfer Protocol (HTTP) request
using XCTU. This example uses http://httpbin.org/ as the target website that responds to the HTTP
request.
To perform a GETrequest:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device.
Click the Configuration working modebutton.
3.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
5. To enter the destination address of the target website, in the DL field, type httpbin.org and
click the Write button.
6. To enter the HTTP request port number, in the DE field, type 50 and click the Write button.
Hexadecimal 50 is 80 in decimal.
7. To switch to TCP communication, in the IP field, select 1 and click the Write button.
8. To move into Transparent mode, in the APfield, select 0 and click the Write button.
9. Wait for the AI (Association Indication) value to change to 0 (Connected to the Internet).
Click the Consoles working mode buttonon the toolbar.
10.
From the AT console, click the Add new packet buttonin the Send packets dialog. The
11.
Add new packet dialog appears.
12. Enter the name of the data packet.
13. Type the following data in the ASCII input tab:
GET /ip HTTP/1.1
Host: httpbin.org
14. Click the HEX input tab and add 0A (zero A) after each 0D (zero D), and add an additional 0D 0A
at the end of the message body. For example, copy and past the following text into the HEX
Note The HTTP protocol requires an empty line (a line with nothing preceding the CRLF) to terminate
the request.
15. Click Add packet.
Click the Open button.
16.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
28
Getting started with the XBee Smart Modem Development KitPerform a (GET) HTTP request
17. Click Send selected packet.
18. A GETHTTP response from httpbin.org appears in the Console log.
Debugging
If you experience problems with the settings in this example, you can load the default settings in
XCTU:
On the Configuration toolbar, click the Default buttonto load the default values
1.
established by the firmware, and click Yes to confirm.
2. Factory settings are loaded but not written to the device. To write them, click the Write button
on the toolbar.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
29
Getting started with the XBee Smart Modem Development KitGet started with MQTT
Get started with MQTT
MQ Telemetry Transport (MQTT) is a messaging protocol that is ideal for the Internet of Things (IoT)
due to a light footprint and its use of the publish-subscribe model. In this model, a client connects to a
broker, a server machine responsible for receiving all messages, filtering them, and then sending
messages to the appropriate clients.
The first two MQTTexamples do not involve the XBee Smart Modem. They demonstrate using the
MQTTlibraries because those libraries are required for Use MQTT over the XBee Cellular Modem with
a PC.
The examples in this guide assume:
n Some knowledge of Python.
n An integrated development environment (IDE)such as PyCharm, IDLE or something similar.
The examples require:
n An XBee Smart Modem.
n A compatible development board, such as the XBIB-U.
n XCTU. See Configure the device using XCTU.
n That you install Python on your computer. You can download Python from:
https://www.python.org/downloads/.
n That you install the pyserial and paho-mqtt libraries to the Python environment. If you use
Python 2, install these libraries from the command line with pip install pyserial and pip
install paho-mqtt. If you use Python 3, use pip3 install pyserial and pip3 install paho-mqtt.
n The full MQTT library source code, which includes examples and tests, which is available in the
paho-mqtt github repository at https://github.com/eclipse/paho.mqtt.python. To download this
repository you must have Git installed.
Example: MQTT connect
This example provides insight into the structure of packets in MQTT as well as the interaction
between the client and broker. MQTT uses different packets to accomplish tasks such as connecting,
subscribing, and publishing. You can use XCTU to perform a basic example of sending a broker a
connect packet and receiving the response from the server, without requiring any coding. This is a
good way to see how the client interacts with the broker and what a packet looks like. The following
table is an example connect packet:
DescriptionHex value
CONNECT packet fixed header
byte 1Control packet type0x10
byte 2Remaining length0x10
CONNECT packet variable header
Protocol name
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
30
Getting started with the XBee Smart Modem Development KitGet started with MQTT
DescriptionHex value
byte 1Length MSB (0)0x00
byte 2Length LSB (4)0x04
byte 3(M)0x4D
byte 4(Q)0x51
byte 5(T)0x54
byte 6(T)0x54
Protocol level
byte 7Level (4)0x04
Connect flags
byte 8
Keep alive
byte 9Keep Alive MSB (0)0X00
byte 10Keep Alive LSB (60)0X3C
Client ID
byte 11Length MSB (0)0x00
byte 12Length LSB (4)0x04
byte 13(D)0x44
byte 14(I)0x49
byte 15(G)0x47
byte 16(I)0x49
The following table describes the fields in the packet:
FieldnameDescription
ProtocolName The connect packet starts with the protocol name, which is MQTT. The length of
CONNECT flags byte, see the table below for the bits.
the protocol name (in bytes) is immediately before the name itself.
0X02
ProtocolLevelRefers to the version of MQTT in use, in this case a value of 4 indicates MQTT
version 3.1.1.
Connect FlagsIndicate certain aspects of the packet. For simplicity, this example only sets the
Clean Session flag, which indicates to the client and broker to discard any previous
session and start a new one.
Keep AliveHow often the client pings the broker to keep the connection alive; in this example
it is set to 60 seconds.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
31
Getting started with the XBee Smart Modem Development KitGet started with MQTT
FieldnameDescription
Client IDThe length of the ID (in bytes) precedes the ID itself. Each client connecting to a
broker must have a unique client ID. In the example, the ID is DIGI. When using the
Paho MQTT Python libraries, a random alphanumeric ID is generated if you do not
specify an ID.
The following table provides the CONNECT flag bits from byte 8, the CONNECT flags byte.
Now that you know what a connect packet looks like, you can send a connect packet to a broker and
view the response. Open XCTU and click the Configuration working mode button.
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
Open XCTU and click the Configuration working modebutton.
2.
3. Add the XBee Smart Modem to XCTU; see Add a device.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
5. In the APfield, set Transparent Mode to [0] if it is not already and click the Write button.
6. In the DL field, type the IP address of the broker you wish to use. This example uses
198.41.30.241, which is the IP address for m2m.eclipse.org, a public MQTT broker.
7. In the DE field, type 75B and set the port that the broker uses. This example uses 75B, because
the default MQTT port is 1883 (0x75B).
8. Once you have entered the required values, click the Write button to write the changes to the
XBee Smart Modem.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
32
Getting started with the XBee Smart Modem Development KitGet started with MQTT
Click the Consoles working mode buttonon the toolbar to open a serial console to the
9.
device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.
Click the Open buttonto open a serial connection to the device.
10.
From the AT console, click the Add new packet buttonin the Send packets dialog. The
11.
Add new packet dialog appears.
12. Enter the name of the data packet. Name the packet connect_frame or something similar.
13. Click the HEX input tab and type the following (these values are the same values from the
14. Click Add packet. The new packet appears in the Send packets list.
15. Click the packet in the Send packets list.
16. Click Send selected packet.
17. A CONNACK packet response from the broker appears in the Console log. This is a connection
acknowledgment; a successful response should look like this:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
33
Getting started with the XBee Smart Modem Development KitGet started with MQTT
You can verify the response from the broker as a CONNACK by comparing it to the structure of a
CONNACK packet in the MQTT documentation, which is available at http://docs.oasis-
A basic Python example of a node publishing (sending) a message is:
mqttc = mqtt.Client("digitest") # Create instance of client with client ID
“digitest”
mqttc.connect("m2m.eclipse.org", 1883) # Connect to (broker, port,
keepalive-time)
mqttc.loop_start() # Start networking daemon
mqttc.publish("digitest/test1", "Hello, World!") # Publish message to
“digitest /test1” topic
mqttc.loop_stop() # Kill networking daemon
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
This example imports the MQTT library, allowing you to use the MQTT protocol via APIs in the library,
such as the connect(), subscribe(), and publish() methods.
The second line creates an instance of the client, named mqttc. The client ID is the argument you
passed in: digitest (this is optional).
In line 3, the client connects to a public broker, in this case m2m.eclipse.org, on port 1883 (the default
MQTT port, or 8883 for MQTT over SSL). There are many publicly available brokers available, you can
find a list of them here: https://github.com/mqtt/mqtt.github.io/wiki/brokers.
Line 4 starts the networking daemon with client.loop_start() to handle the background
network/data tasks.
Finally, the client publishes its message Hello, World! to the broker under the topicdigitest/backlog/test1. Any nodes (devices, phones, computers, even microcontrollers) subscribed to
that same topic on the same broker receive the message.
Once no more messages need to be published, the last line stops the network daemon with
client.loop_stop().
Example: receive messages (subscribe) with MQTT
This example describes how a client would receive messages from within a specific topic on the
broker:
import paho.mqtt.client as mqtt
def on_connect(client, userdata, flags, rc): # The callback for when the
client connects to the broker
print("Connected with result code {0}".format(str(rc))) # Print result
of connection attempt
client.subscribe("digitest/test1") # Subscribe to the topic
“digitest/test1”, receive any messages published on it
def on_message(client, userdata, msg): # The callback for when a PUBLISH
message is received from the server.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
34
Getting started with the XBee Smart Modem Development KitGet started with MQTT
Print a received msg
client = mqtt.Client("digi_mqtt_test") # Create instance of client with
client ID “digi_mqtt_test”
client.on_connect = on_connect # Define callback function for successful
connection
client.on_message = on_message # Define callback function for receipt of a
message
# client.connect("m2m.eclipse.org", 1883, 60) # Connect to (broker, port,
keepalive-time)
client.connect('127.0.0.1', 17300)
client.loop_forever() # Start networking daemon
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
The first line imports the library functions for MQTT.
The functions on_connect and on_message are callback functions which are automatically called by
the client upon connection to the broker and upon receiving a message, respectively.
The on_connect function prints the result of the connection attempt, and performs the subscription.
It is wise to do this in the callback function as it guarantees the attempt to subscribe happens only
after the client is connected to the broker.
The on_message function prints the received message when it comes in, as well as the topic it was
published under.
In the body of the code, we:
n Instantiate a client object with the client ID digi_mqtt_test
n Define the callback functions to use upon connection and upon message receipt
n Connect to an MQTT broker at m2m.eclipse.org, on port 1883 (the default MQTT port, or 8883
for MQTT over SSL) with a keepalive of 60 seconds (this is how often the client pings the broker
to keep the connection alive).
The last line starts a network daemon that runs in the background and handles data transactions and
messages, as well as keeping the socket open, until the script ends.
Use MQTT over the XBee Cellular Modem with a PC
To use this MQTT library over an XBee Smart Modem, you need a basic proxy that transfers a payload
received via the MQTT client’s socket to the serial or COM port that the XBee Smart Modem is active
on, as well as the reverse; transfer of a payload received on the XBee Smart Modem’s serial or COM
port to the socket of the MQTT client. This is simplest with the XBee Smart Modem in Transparent
mode, as it does not require code to parse or create API frames, and not using API frames means
there is no need for them to be queued for processing.
1. To put the XBee Cellular Modem in Transparent mode, set AP to 0.
2. Set DL to the IP address of the broker you want to use.
3. Set DE to the port to use, the default is 1883 (0x75B). This sets the XBee Smart Modem to
communicate directly with the broker, and can be performed in XCTU as described in Example:
MQTT connect.
4. You can make the proxy with a dual-threaded Python script, a simple version follows:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
35
Getting started with the XBee Smart Modem Development KitGet started with MQTT
import threading
import serial
import socket
def setup():
"""
This function sets up the variables needed, including the serial port,
and it's speed/port settings, listening socket, and localhost adddress.
"""
global clisock, cliaddr, svrsock, ser
# Change this to the COM port your XBee Cellular module is using. On
# Linux, this will be /dev/ttyUSB#
comport = 'COM44'
# This is the default serial communication speed of the XBee Cellular
# module
comspeed = 115200
buffer_size = 4096 # Default receive size in bytes
debug_on = 0 # Enables printing of debug messages
toval = None # Timeout value for serial port below
# Serial port object for XBCell modem
ser = serial.Serial(comport,comspeed,timeout=toval)
# Listening socket (accepts incoming connection)
svrsock = socket.socket(socket.AF_INET,socket.SOCK_STREAM)
# Allow address reuse on socket (eliminates some restart errors)
svrsock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
clisock = None
cliaddr = None # These are first defined before thread creation
addrtuple = ('127.0.0.1', 17300) # Address tuple for localhost
# Binds server socket to localhost (allows client program connection)
svrsock.bind(addrtuple)
svrsock.listen(1) # Allow (1) connection
def ComReaderThread():
"""
This thread listens on the defined serial port object ('ser') for data
from the modem, and upon receipt, sends it out to the client over the
client socket ('clisock').
"""
global clisock
while (1):
resp = ser.read() ## Read any available data from serial port
print("Received {} bytes from modem.".format(len(resp)))
clisock.sendall(resp) # Send RXd data out on client socket
print("Sent {} byte payload out socket to client.".format(len
(resp)))
def SockReaderThread():
"""
This thread listens to the MQTT client's socket and upon receiving a
payload, it sends this data out on the defined serial port ('ser') to
the
modem for transmission.
"""
global clisock
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
36
Getting started with the XBee Smart Modem Development KitGet started with MQTT
while (1):
data = clisock.recv(4096) # RX data from client socket
# If the RECV call returns 0 bytes, the socket has closed
if (len(data) == 0):
print("ERROR - socket has closed. Exiting socket reader
thread.")
return 1 # Exit the thread to avoid a loop of 0-byte receptions
else:
print("Received {} bytes from client via socket.".format(len
(data)))
print("Sending payload to modem...")
bytes_wr = ser.write(data) # Write payload to modem via
UART/serial
print("Wrote {} bytes to modem".format(bytes_wr))
def main():
setup() # Setup the serial port and socket
global clisock, svrsock
if (not clisock): # Accept a connection on 'svrsock' to open 'clisock'
print("Awaiting ACCEPT on server sock...")
(clisock,cliaddr) = svrsock.accept() # Accept an incoming
connection
print("Connection accepted on socket")
# Make thread for ComReader
comthread = threading.Thread(target=ComReaderThread)
comthread.start() # Start the thread
# Make thread for SockReader
sockthread = threading.Thread(target=SockReaderThread)
sockthread.start() # Start the thread
main()
Note This script is a general TCP-UART proxy, and can be used for other applications or scripts that
use the TCP protocol. Its functionality is not limited to MQTT.
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
This proxy script waits for an incoming connection on localhost (127.0.0.1), on port 17300. After
accepting a connection, and creating a socket for that connection (clisock), it creates two threads,
one that reads the serial or COM port that the XBee Smart Modem is connected to, and one that
reads the socket (clisock), that the MQTT client is connected to.
With:
n The proxy script running
n The MQTT client connected to the proxy script via localhost (127.0.0.1)
n The XBee Smart Modem connected to the machine via USB and properly powered
n AP, DL, and DE set correctly
the proxy acts as an intermediary between the MQTT client and the XBee Smart Modem, allowing the
MQTT client to use the data connection provided by the device.
Think of the proxy script as a translator between the MQTT client and the XBee Smart Modem. The
following figure shows the basic operation.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
37
Getting started with the XBee Smart Modem Development KitGet started with MQTT
The thread that reads the serial port forwards any data received onward to the client socket, and the
thread reading the client socket forwards any data received onward to the serial port. This is
represented in the figure above.
The proxy script needs to be running before running an MQTT publish or subscribe script.
1. With the proxy script running, run the subscribe example from Example: receive messages
(subscribe) with MQTT, but change the connect line from client.connect("m2m.eclipse.org",
1883, 60) to client.connect("127.0.0.1", port=17300, keepalive=20). This connects the
MQTT client to the proxy script, which in turn connects to a broker via the XBee Smart
Modem’s internet connection.
2. Run the publish example from Example: send messages (publish) with MQTT in a third Python
instance (while the publish script is running you will have three Python scripts running at the
same time).
The publish script runs over your computer’s normal internet connection, and does not use the XBee
Smart Modem. You are able to see your published message appear in the subscribe script’s output
once it is received from the broker via the XBee Smart Modem. If you watch the output of the proxy
script during this process you can see the receptions and transmissions taking place.
The proxy script must be running before you run the subscribe and publish scripts. If you stop the
subscribe script, the socket closes, and the proxy script shows an error. If you try to start the proxy
script after starting the subscribe script, you may also see a socket error. To avoid these errors, it is
best to start the scripts in the correct order: proxy, then subscribe, then publish.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
38
Getting started with the XBee Smart Modem Development KitGet started with CoAP
Get started with CoAP
Constrained Application Protocol (CoAP) is based on UDP connection and consumes low power to
deliver similar functionality to HTTP. This guide contains information about sending GET, POST, PUT
and DELETE operations by using the Coap Protocol with XCTU and Python code working with the XBee
Smart Modem and Coapthon library (Python 2.7 only).
The Internet Engineering Task Force describes CoAP as:
The protocol is designed for machine-to-machine (M2M) applications such as smart energy and
building automation. CoAP provides a request/response interaction model between application
endpoints, supports built-in discovery of services and resources, and includes key concepts of
the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP
for integration with the Web while meeting specialized requirements such as multicast
support, very low overhead, and simplicity for constrained environments (source).
CoAP terms
When describing CoAP, we use the following terms:
TermMeaning
MethodCOAP's method action is similar to the HTTP method. This guide discusses the GET,
POST, PUT and DELETE methods. With these methods, the XBee Smart Modem can
transport data and requests.
URIURI is a string of characters that identifies a resource served at the server.
TokenAtoken is an identifier of a message. The client uses the token to verify if the received
message is the correct response to its query.
PayloadThe message payload is associated with the POST and PUT methods. It specifies the
data to be posted or put to the URI resource
MessageID The message ID is also an identifier of a message. The client matches the message ID
between the response and query.
CoAP quick start example
The following diagram shows the message format for the CoAP protocol; see ISSN: 2070-1721 for
details:
This is an example GET request:
44 01 C4 09 74 65 73 74 B7 65 78 61 6D 70 6C 65
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
39
Getting started with the XBee Smart Modem Development KitGet started with CoAP
The following table describes the fields in the GETrequest.
FieldHEXBitsMeaning
Ver4401Version 01, which is mandatory here.
T00Type 0: confirmable.
TKL0100Token length: 4.
Code01000 00001Code: 0.01, which indicates the GET method.
Message IDC4 092 Bytes equal
to hex at left
Token74 65 73 74 4 Bytes equal
to hex at left
Option deltaB71011Delta option: 11 indicates the option data is Uri-Path.
Optionlength0111Delta length: 7 indicates there are 7 bytes of data
Option value65 78 61 6D
70 6C 65
7 Bytes equal
to hex at left
Message ID. The response message will have the
same ID. This can help out identification.
Token. The response message will have the same
token. This can help out identification.
following as a part of this delta option.
Example.
Configure the device
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
Open XCTU and click the Configuration working modebutton.
2.
3. Add the XBee Smart Modem to XCTU; see Add a device.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
To switch to UDPcommunication, in the IP field, select 0 and click the Write button.
5.
6. To set the target IP address that the XBee Smart Modem will talk to, in the DL field type
52.43.121.77and click the Write button. A CoAP server is publicly available at address
52.43.121.77.
7. To set the XBee Smart Modem to send data to port 5683 in decimal, in the DEfield, type 1633
and click the Write button.
8. To move into Transparent mode, in the APfield, select 0 and click the Write button.
9. Wait for the AI (Association Indication) value to change to 0 (Connected to the Internet). You
can click Readto get an update on the AI value.
Example: manually perform a CoAPrequest
Follow the steps in Configure the device prior to this example. This example performs the CoAP
GETrequest:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
40
Getting started with the XBee Smart Modem Development KitGet started with CoAP
n Method: GET
n URI: example
n Given message token: test
Click the Consoles working mode buttonon the toolbar to add a customized packet.
1.
From the AT console, click the Add new packet buttonin the Send packets dialog. The
2.
Add new packet dialog appears.
3. Click the HEX tab and type the name of the data packet: GET_EXAMPLE.
4. Copy and past the following text into the HEX input tab:
44 01 C4 09 74 65 73 74 B7 65 78 61 6D 70 6C 65
This is the CoAP protocol message decomposed by bytes to perform a GET request on an
example URI with a token test.
5. Click Add packet.
Click the Open button.
6.
7. Click Send selected packet. The message is sent to the public CoAP server configured in
Configure the device. A response appears in the Console log. Blue text is the query, red text is
the response.
The payload is Get to uri: example, which specifies that this is a successful CoAP GET to URI end
example, which was specified in the query.
Click the Close button to terminate the serial connection.
Example: use Python to generate a CoAP message
This example illustrates how the CoAP protocol can perform GET/POST/PUT/DELETE requests
similarly to the HTTP protocol and how to do this using the XBee Smart Modem. In this example, the
XBee Smart Modem talks to a CoAP Digi Server. You can use this client code to provide an abstract
wrapper to generate a CoAP message that commands the XBee Smart Modem to talk to the remote
CoAP server.
Note It is crucial to configure the XBee Smart Modem settings. See Configure the device and follow
the steps. You can target the IP address to a different CoAP public server.
1. Install Python 2.7. The Installation guide is located at: https://www.python.org/downloads/.
2. Download and install the Coapthon library in the python environment from
https://pypi.python.org/pypi/CoAPthon.
3. Download these two .txt files: Coap.txt and CoapParser.txt. After you download them, open the
files in a text editor and save them as .py files.
4. In the folder that you place the Coap.py and CoapParser.py files, press Shift + right-click and
then click Open command window.
5. At the command prompt, type python Coap.py and press Enter to run the program.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
41
Getting started with the XBee Smart Modem Development KitGet started with CoAP
6. Type the USB port number that the XBee Smart Modem is connected to and press Enter. Only
the port number is required, so if the port is COM19, type 19.
Note If you do not know the port number, open XCTU and look at the XBee Smart Modem in the Radio
Modules list. This view provides the port number and baud rate, as in the figure below where the baud
rate is 9600 b/s.
7. Type the baud rate and press Enter. You must match the device's current baud rate.
XCTUprovides the current baud rate in the BD Baud Rate field. In this example you would type
9600.
8. Press Y if you want an auto-generated example. Press Enter to build your own CoAP request.
9. If you press Y it generates a message with:
n Method: POST
n URI: example
n payload:hello world
n token: test
The send and receive message must match the same token and message id. Otherwise, the client reattempts the connection by sending out the request.
In the following figure, the payload contains the server response to the query. It shows the results for
when you press Enter rather than Y.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
42
Getting started with the XBee Smart Modem Development KitGet started with CoAP
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
43
Getting started with the XBee Smart Modem
Development Kit
Configure the XBee Smart Modem using Digi Remote
Manager
Configure the XBee Smart Modem using Digi Remote Manager
Use Digi Remote Manager (https://remotemanager.digi.com/) to perform the operations in this
section. Each operation requires that you enable Remote Manager with the DO command and that
you connect the XBee Smart Modem to an access point that has an external Internet connection to
allow access to Digi Remote Manager.
Note Digi is consolidating our cloud services, Digi Device Cloud and Digi Remote Manager®, under the
Remote Manager name. This phased process does not affect device functionality or the functionality
of the web services and other features. However, customers will find that some user interface and
firmware functionality mention both Device Cloud and Digi Remote Manager.
Create a Remote Manager account
Digi Remote Manager is an on-demand service with no infrastructure requirements. Remote devices
and enterprise business applications connect to Remote Manager through standards-based web
services. This section describes how to configure and manage an XBee using Remote Manager. For
detailed information on using Remote Manager, refer to the Remote Manager User Guide, available
via the Documentation tab in Remote Manager.
Before you can manage an XBee with Remote Manager, you must create a Remote Manager account.
To create a Remote Manager account:
1. Go to https://www.digi.com/products/cloud/digi-remote-manager.
2. Click 30 DAY FREETRIAL/LOGIN.
3. Follow the online instructions to complete account registration. You can upgrade your
Developer account to a paid account at any time.
When you are ready to deploy multiple XBee Smart Modems in the field, upgrade your account to
access additional Remote Manager features.
Get the XBee Smart Modem IMEI number
Before adding an XBee to your Remote Manager account inventory, you need to determine the
International Mobile Equipment Identity (IMEI) number for the device. Use XCTUto view the IMEI
number by querying the IM parameter.
Add a XBee Smart Modem to Remote Manager
To add an XBee to your Remote Manager account inventory, follow these steps:
Go to https://remotemanager.digi.com/.
1. Log in to your account
2. Click Device Management > Devices.
3. Click Add Devices. The Add Devices dialog appears.
4. Select IMEI#, and type or paste the IMEI number of the XBee you want to add. The IM
(IMEI)command provides this number.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
44
Getting started with the XBee Smart Modem Development KitSoftware libraries
5. Click Add to add the device. The XBee is added to your inventory.
6. Click OK to close the Add Devices dialog and return to the Devices view.
Update the firmware
XBee Smart Modem supports Remote Manager firmware updates. To perform a firmware update, use
the following steps.
1. Download the updated firmware file for your device from Digi's support site. This is a zip file
containing .ebin and .mxi files for import.
2. Unzip the file.
3. In your Remote Manager account, click Device Management > Devices.
4. Select the first device you want to update.
5. To select multiple devices (must be of the same type), press the Control key and select
additional devices.
6. Click More in the Devices toolbar and select Update Firmware from the Update category of
the More menu. The Update Firmware dialog appears.
7. Click Browse to select the .ebin file that you unzipped earlier.
8. Click Update Firmware. The updated devices automatically reboot when the updates are
complete.
Software libraries
One way to communicate with the XBee device is by using a software library. The libraries available
for use with the XBee Smart Modem include:
n XBee Java library
n XBee 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.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
45
Get started with MicroPython
This guide provides an overview of how to use MicroPython with the XBee Smart Modem. For in-depth
information and more complex code examples, refer to the Digi MicroPython Programming Guide.
Continue with this guide for simple examples to get started using MicroPython on the XBee Smart
Modem.
About MicroPython47
MicroPython on the XBee Smart Modem47
Use XCTU to enter the MicroPython environment47
Use the MicroPython Terminal in XCTU48
Example: hello world48
Example: turn on an LED48
Example: code a request help button49
Exit MicroPython mode54
Other terminal programs54
Use picocom in Linux55
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
46
Get started with MicroPythonAbout MicroPython
About MicroPython
MicroPython is an open-source programming language based on Python 3, with much of the same
syntax and functionality, but modified to fit on small devices with limited hardware resources, such as
microcontrollers, or in this case, a cellular modem.
Why use MicroPython
MicroPython enables on-board intelligence for simple sensor or actuator applications using digital and
analog I/O. MicroPython can help manage battery life. Cryptic readings can be transformed into useful
data, excess transmissions can be intelligently filtered out, modern sensors and actuators can be
employed directly, and logic can glue inputs and outputs together in an intelligent way.
For more information about MicroPython, see www.micropython.org.
For more information about Python, see www.python.org.
MicroPython on the XBee Smart Modem
The XBee Smart Modem has MicroPython running on the device itself. You can access a MicroPython
prompt from the XBee Smart Modem when you install it in an appropriate development board (XBDB
or XBIB), and connect it to a computer via a USB cable.
Note MicroPython does not work with SPI.
The examples in this guide assume:
n You have XCTU on your computer. See Configure the device using XCTU.
n You have a terminal program installed on your computer. We recommend using the Use the
MicroPython Terminal in XCTU. This requires XCTU 6.3.7 or higher.
n You have an XBee Smart Modem installed in an appropriate development board such as an
XBIB-U-DEV or an XBIB-2.
Note Most examples in this guide require the XBIB-U-DEV board.
n The XBee Smart Modem is connected to the computer via a USB cable and XCTU recognizes it.
n The board is powered by an appropriate power supply, 12 VDC and at least 1.1 A.
Use XCTU to enter the MicroPython environment
To use the XBee Smart Modem in the MicroPython environment:
1. Use XCTU to add the device(s); see Configure the device using XCTU and Add a device.
2. The XBee Smart Modem appears as a box in the Radio Modules information panel. Each
module displays identifying information about itself.
3. Click this box to select the device and load its current settings.
4. To set the device's baud rate to 115200 b/s, in the BD field select 115200 [7] and click the
Write button. We recommend using flow control to avoid data loss, especially when pasting
large amounts of code/text.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
47
Get started with MicroPythonUse the MicroPython Terminal in XCTU
5. To put the XBee Smart Modem into MicroPython mode, in the APfield select MicroPython
REPL [4] and click the Write button.
6. Note what COM port(s) the XBee Smart Modem is using, because you will need this information
when you use terminal communication.
Use the MicroPython Terminal in XCTU
You can use the MicroPython Terminal to communicate with the XBee Smart Modem when it is in
MicroPython mode.1This requires XCTU 6.3.7 or higher. To enter MicroPython mode, follow the steps
in Use XCTU to enter the MicroPython environment. To use the MicroPython Terminal:
Click the Tools drop-down menuand select MicroPython Terminal. The terminal opens.
1.
2. Click Open.
3. In the Select the Serial/USB port area, click the COM port that the device uses.
4. Verify that the baud rate and other settings are correct.
Click OK. The Open icon changes to Close, indicating that the device is properly connected.
5.
You can now type or paste MicroPython code in the terminal.
Example: hello world
1. At the MicroPython >>> prompt, type the Python command: print("Hello, World!")
2. Press Enter to execute the command. The terminal echos back Hello, World!.
Example: turn on an LED
1. Note the DS4 LED on the XBIB board. The following image highlights it in a red box. The LED is
normally off.
1
See Other terminal programs if you do not use the MicroPython Terminal in XCTU.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
48
Get started with MicroPythonExample: code a request help button
2. At the MicroPython >>> prompt, type the commands below, pressing Enter after each one.
After entering the last line of code, the LED illuminates. Anything after a # symbol is a
comment, and you do not need to type it.
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
import machine
from machine import Pin
led = Pin("D4", Pin.OUT, value=0) # Makes a pin object set to output 0.
# One might expect 0 to mean OFF and 1 to mean ON, and this is normally the
case.
# But the LED we are turning on and off is setup as what is# known as
"active low".
# This means setting the pin to 0 allows current to flow through the LED and
then through the pin, to ground.
3. To turn it off, type the following and press Enter:
led.value(1)
You have successfully controlled an LED on the board using basic I/O!
Example: code a request help button
This example provides a fast, deep dive into MicroPython designed to let you see some of the powerful
things it can do with minimal code. It is not meant as a tutorial; for in-depth examples refer to the Digi
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
49
Get started with MicroPythonExample: code a request help button
MicroPython Programming Guide.
Many stores have help buttons in their aisles that a customer can press to alert the store staff that
assistance is required in that aisle. You can implement this type of system using the Digi XBee Smart
Modem, and this example provides the building blocks for such a system. This example, based on SMS
paging, can have many other uses such as alerting someone with a text to their phone if a water
sensor in a building detects water on the floor, or if a temperature sensor reports a value that is too
hot or cold relative to normal operation.
Enter MicroPython paste mode
In the following examples it is helpful to know that MicroPython supports paste mode, where you can
copy a large block of code from this user guide and paste it instead of typing it character by character.
To use paste mode:
1. Copy the code you want to run. For example, copy the following code that is the code from the
LED example:
from machine import Pin
led = Pin("D4", Pin.OUT, value=0)
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
2. In the terminal, at the MicroPython >>> prompt type Ctrl-+E to enter paste mode. The terminal
displays paste mode; Ctrl-C to cancel, Ctrl-D to finish.
3. The code appears in the terminal occupying four lines, each line starts with its line number and
three = symbols. For example line 1 starts with 1===.
4. If the code is correct, press Ctrl+D to run the code and you should once again see the DS4 LED
turn on. If you get a Line 1 SyntaxError: invalid syntax error, see Syntax error at line 1.
(If you wish to exit paste mode without running the code, for example, or if the code did not
copy correctly, press Ctrl+C to cancel and return to the normal MicroPython >>> prompt).
5. Next turn the LED off. Copy the code below:
from machine import Pin
led = Pin("D4", Pin.OUT, value=1)
print("DS4 LED now OFF!")
print("Paste Mode Successful!")
6. Press Ctrl+E to enter paste mode.
7. Press Ctrl + Shift + V or right-click in the Terminal and select Paste to paste the copied code.
8. If the code is correct, press Ctrl+D to run it. The LED should turn off and you should see two
confirmation messages print to the screen.
Catch a button press
For this part of the example, you write code that responds to a button press on the XBIB-U-DEV board
that comes with the XBee Smart Modem Development Kit. The code monitors the pin connected to
the button on the board labeled SW2.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
50
Get started with MicroPythonExample: code a request help button
On the board you see DIO0 written below SW2, to the left of the button. This represents the pin that
the button is connected to.
In MicroPython, you will create a pin object for the pin that is connected to the SW2 button. When you
create the pin object, the DIO0 pin is called D0 for short.
The loop continuously checks the value on that pin and once it goes to 0 (meaning the button has been
pressed) a print() call prints the message Button pressed! to the screen.
At the MicroPython >>> prompt, copy the following code and enter it into MicroPython using paste
mode and then run it:
# Import the Pin module from machine, for simpler syntax.
from machine import Pin
# Create a pin object for the pin that the button "SW2" is connected to.
dio0 = Pin("D0", Pin.IN, Pin.PULL_UP)
# Give feedback to inform user a button press is needed.
print("Waiting for SW2 press...")
# Create a WHILE loop that checks for a button press.
while (True):
if (dio0.value() == 0): # Once pressed.
print("Button pressed!") # Print message once pressed.
break # Exit the WHILE loop.
# When you press SW2, you should see "Button pressed!" printed to the
screen.
# You have successfully performed an action in response to a button press!
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
51
Get started with MicroPythonExample: code a request help button
Send a text (SMS) when the button is pressed
After creating a while loop that checks for a button press, add sending an SMS to your code. Instead of
printing Button pressed! to the screen, this code sends Button pressed to a cell phone as a text
(SMS) message.
To accomplish this, use the sms_send() method, which sends a string to a given phone number. It
takes the arguments in the order of
1. <phone number>
2. <message-to-be-sent>
Before you run this part of the example, you must create a variable that holds the phone number of
the cell phone or mobile device you want to receive the SMS.
1. To do this, at the MicroPython >>> prompt, type the following command, replacing 1123456789
with the full phone number (no dashes, spaces, or other symbols) and press Enter:
ph = 1123456789
2. After you create this ph variable with your phone number, copy the code below and enter it
into MicroPython using paste mode and then run it.
from machine import Pin
import network # Import network module
import time
c = network.Cellular() # initialize cellular network parameter
dio0 = Pin("D0", Pin.IN, Pin.PULL_UP)
while not c.isconnected(): # While no network connection.
print("Waiting for connection to cell network...")
time.sleep(5)
print("Connected.")
# Give feedback to inform user a button press is needed.
print("Waiting for SW2 press...")
while (True):
if (dio0.value() == 0):
# When SW2 is pressed, the module will send an SMS
# message saying "Button pressed" to the given target cell phone
print("ERROR- failed to send SMS.")
# Exit the WHILE loop.
break
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
52
Get started with MicroPythonExample: code a request help button
Add the time the button was pressed
After you add the ability to send an SMS to the code, add functionality to insert the time at which the
button was pressed into the SMS that is sent. To accomplish this:
1. Create a UDP socket with the socket() method.
2. Save the IP address and port of the time server in the addr variable.
3. Connect to the time server with the connect() method.
4. Send hello to the server to prompt it to respond with the current date and time.
5. Receive and store the date/time response in the buf variable.
6. Send an SMSin the same manner as before using the sms_send() method, except that you add
the time into the SMS message, such that the message reads: [Button pressed at: YYYY-MM-
DD HH:MM:SS]
To verify that your phone number is still in the memory, at the MicroPython >>> prompt, type ph and
press Enter.
If MicroPython responds with your number, copy the following code and enter it into MicroPython
using paste mode and then run it. If it returns an error, enter your number again as shown in Send a
text (SMS) when the button is pressed. With your phone number in memory in the ph variable, copy
the code below and enter it into MicroPython using paste mode and then run it.
from machine import Pin
import network
import usocket
import time
c = network.Cellular()
dio0 = Pin("D0", Pin.IN, Pin.PULL_UP)
while not c.isconnected(): # While no network connection.
print("Waiting for connection to cell network...")
time.sleep(5)
print("Connected.")
# Give feedback to inform user a button press is needed.
print("Waiting for SW2 press...")
while (1):
if (dio0.value() == 0):
# When button pressed, now the module will send "Button Press" AND
# the time at which it was pressed in an SMS message to the given
# target cell phone number.
socketObject = usocket.socket(usocket.AF_INET, usocket.SOCK_DGRAM)
# Connect the socket object to the web server specified in
"address".
addr = ("52.43.121.77", 10002)
socketObject.connect(addr)
bytessent = socketObject.send("hello")
print("Sent %d bytes on socket" % bytessent)
buf = socketObject.recv(1024)
# Send message to the given number. Handle error if it occurs.
try:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
53
Get started with MicroPythonExit MicroPython mode
# Exit the WHILE loop.
break
Note You can easily copy and paste code from the online version of this Guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Now you have a system based on the XBee Smart Modem that sends an SMS in response to a certain
input, in this case a simple button press.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.
Exit MicroPython mode
To exit MicroPython mode:
In the XCTU MicroPython Terminal, click the green Close button.
1.
2. Click Close at the bottom of the terminal to exit the terminal.
In XCTU's Configuration working mode, change AP API Enable to another mode and click
3.
the Write button. We recommend changing to Transparent mode [0], as most of the
examples use this mode.
Other terminal programs
If you do not use the MicroPython Terminal in XCTU, you can use other terminal programs to
communicate with the XBee Smart Modem. If you use Microsoft Windows, follow the instructions for
Tera Term, if you use Linux, follow the instructions for picocom. To download these programs:
n Tera Term for Windows; see https://ttssh2.osdn.jp/index.html.en.
n Picocom for Linux; see https://developer.ridgerun.com/wiki/index.php/Setting_up_Picocom_-_
Ubuntu and for the source code and in-depth information https://github.com/npat-
efault/picocom.
Tera Term for Windows
With the XBee Smart Modem in MicroPython mode (AP = 4), you can access the MicroPython prompt
using a terminal.
1. Open Tera Term. The Tera Term: New connection window appears.
2. Click the Serial radio button to select a serial connection.
3. From the Port: drop-down menu, select the COM port that the XBee Smart Modem is
connected to.
4. Click OK. The COMxx - Tera Term VT terminal window appears and Tera Term attempts to
connect to the device at a baud rate of 9600 b/s. The terminal will not allow communication
with the device since the baud rate setting is incorrect. You must change this rate as it was
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
54
Get started with MicroPythonUse picocom in Linux
previously set to 115200 b/s.
5. Click Setup and Serial Port. The Tera Term: Serial port setup window appears.
6. In the Tera Term: Serial port setup window, set the parameters to the following values:
n Port: Shows the port that the XBee Smart Modem is connected on.
n Baud rate:115200
n Data: 8 bit
n Parity: none
n Stop: 1 bit
n Flow control: hardware
n Transmit delay: N/A
7. Click OK to apply the changes to the serial port settings. The settings should go into effect
right away.
8. To verify that local echo is not enabled and that extra line-feeds are not enabled:
a. In Tera Term, click Setup and select Terminal.
b. In the New-line area of the Tera Term: Serial port setup window, click the
Receive drop-down menu and select CR if it does not already show that value.
c. Make sure the Local echo box is not checked.
9. Click OK.
10. Press Ctrl+B to get the MicroPython version banner and prompt.
Now you can type MicroPython commands at the >>> prompt.
Use picocom in Linux
With the XBee Smart Modem in MicroPython mode (AP = 4), you can access the MicroPython prompt
using a terminal.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
55
Get started with MicroPythonUse picocom in Linux
Note The user must have read and write permission for the serial port the XBee Smart Modem is
connected to in order to communicate with the device.
1. Open a terminal in Linux and type picocom -b 115200 /dev/ttyUSB0. This assumes you have
no other USB-to-serial devices attached to the system.
2. Press Ctrl+B to get the MicroPython version banner and prompt. You can also press Enter to
bring up the prompt.
If you do have other USB-to-serial devices attached:
1. Before attaching the XBee Smart Modem, check the directory /dev/ for any devices named
ttyUSBx, where x is a number. An easy way to list these is to type: ls /dev/ttyUSB*. This
produces a list of any device with a name that starts with ttyUSB.
2. Take note of the devices present with that name, and then connect the XBee Smart Modem.
3. Check the directory again and you should see one additional device, which is the XBee Smart
Modem.
4. In this case, replace /dev/ttyUSB0 at the top with /dev/ttyUSB<number>, where <number>
is the new number that appeared.
5. It should connect and show Terminal ready.
Now you can type MicroPython commands at the >>> prompt.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
56
Technical specifications
Interface and hardware specifications58
RF characteristics58
Networking specifications58
Power requirements58
Power consumption59
Electrical specifications59
Regulatory approvals60
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
57
Technical specificationsInterface and hardware specifications
Interface and hardware specifications
The following table provides the interface and hardware specifications for the device.
SpecificationValue
Dimensions2.438 x 3.294 cm (0.960 x 1.297 in)
Weight5 g (0.18 oz)
Operating temperature
Antenna connectorU.FL for primary and secondary antennas
Digital I/O13 I/O lines
ADC4 10-bit analog inputs
RF characteristics
The following table provides the RF characteristics for the device.
SpecificationCellular valueBLE value
ModulationLTE/4G – QPSK, 16 QAM
Transmit power23 dBm
Receive sensitivity-102 dBm
Over-the-air maximum data rate10 Mb/s2 Mb/s
Networking specifications
The following table provides the networking and carrier specifications for the device.
-40 to +80 °C
QPSK
9 dBm
-92 dBm
SpecificationValue
Addressing optionsTCP/IPand SMS
Carrier and technologyAT&T LTE Cat 1
Supported bands2, 4 and 12
SecuritySSL/TLS
Power requirements
The following table provides the power requirements for the device.
SpecificationValue
Supply voltage range3.0 to 5.5 VDC
Extended voltage range2.7 to 5.5 VDC
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
The following table provides the electrical specifications for the XBee Smart Modem.
Symbol ParameterConditionMinTypical MaxUnits
VCCMAX Maximum limits
of VCC line
VDD_IOInternal supply
voltage for I/O
VDD_IOInternal supply
voltage for I/O
05.5V
While in deep sleep and
during initial power up
In normal running mode3.3 VV
Min
(VCC-
0.3,3.3)
3.3V
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
59
Technical specificationsRegulatory approvals
Symbol ParameterConditionMinTypical MaxUnits
VIVoltage on 5 V
tolerant pins
Other input pins0.3VDD_IO +
VILInput low voltage0.3*VDD_IO V
VIHInput high
voltage
VOLVoltage output
low
VOHVoltage output
high
I_INInput leakage
current
RPUInternal pull-up
resistor
RPDInternal pull-
down resistor
XBee pin 60.3Min
(5.25,VDD_
1
IO+2)
0.3
0.7*VDD_
IO
Sinking 3 mA VDD_IO = 3.3 V0.2*VDD_IO V
Sourcing 3 mA VDD_IO = 3.3V0.8*VDD_
IO
High Z state I/O connected
to Ground or VDD_IO
Enabled40kΩ
Enabled40kΩ
0.1100nA
V
V
V
V
Regulatory approvals
The following table provides the regulatory and carrier approvals for the device.
SpecificationValue
ModelXB3C1
United States
Contains IC: 1846A-XB3C1
Europe (CE)N/A
RoHSLead-free and RoHS compliant
AustraliaN/A
Verizon end-device certifiedNo
AT&T end-device certifiedYes
PTCRB end-device certifiedYes
1
Pin 6 is also 5 V tolerant even when the XBee Smart Modem is not powered. We recommend only driving this
pin with 3.3 V for compatibility with other XBee products. The VBUS line is not used to enable/disable USB on
this product.
FCC ID: MCQ-XB3C1
Contains FCC ID:RI7XE866A1NA
IC: 1846A-XB3C1
Contains IC: 5131A-XE866A1NA
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
61
HardwareMechanical drawings
Mechanical drawings
The following figures show the mechanical drawings for the XBee Smart Modem. All dimensions are in
inches.
Pin signals
The pin locations are:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
62
HardwarePin signals
The following table shows the pin assignments for the through-hole device. In the table, low-asserted
signals have a horizontal line above signal name.
Pin NameDirection DefaultDescription
Pin NameDirection DefaultDescription
V
1
CC
2DOUTOutputOutputUART Data Out
DIN / CONFIG
3
4DIO12 / SPI_MISOEitherDisabled Digital I/O 12 or SPI Slave Output line
5RESETInput
InputInputUART Data In
Power supply
6PWM0 / RSSI /
DIO10/USB_VBUS
7DIO11/USB D+EitherDisabled Digital I/O 11 or USB D+ line
8USB D-Direct USB D- line
DTR / SLEEP_RQ/
9
DIO8
10GNDGround
11DIO4 / SPI_MOSIEitherDisabled Digital I/O 4 or SPI Slave Input Line
CTS / DIO7
12
ON /SLEEP/DIO9
13
14VREF-Feature not supported on this device. Used on
15Associate / DIO5EitherOutputAssociated Indicator, Digital I/O 5
RTS / DIO6
16
AD3/DIO3/SPI_
17
SS
18AD2 / DIO2 / SPI_
CLK
EitherOutputPWM Output 0 / RX Signal Strength Indicator /
Digital I/O 10
EitherDisabled Pin Sleep Control Line or Digital I/O 8
EitherOutputOutput Clear-to-Send Flow Control or Digital I/O 7
OutputOutputModule Status Indicator or Digital I/O 9
other XBee devices for analog voltage reference.
EitherDisabled Input Request-to-Send Flow Control, Digital I/O 6
EitherDisabled Analog Input 3 or Digital I/O 3, SPI low enabled
select line
EitherDisabled Analog Input 2 or Digital I/O 2, SPI Clock line
AD1/DIO1/ SPI_
19
ATTN
20AD0/DIO0EitherInputAnalog Input 0, Digital I/O 0
EitherDisabled
Pin connection recommendations
The recommended minimum pin connections are VCC, GND, DIN, DOUT, RTS, DTR and RESET.
Firmware updates require access to these pins.
To ensure compatibility with future updates, make USB D+ and D- (pin 7 and pin 8) available in your
design.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
Analog Input 1 or Digital I/O 1, SPI Attention line
output
63
HardwareRSSI PWM
RSSI PWM
The XBee Smart Modem features an RSSI/PWM pin (pin 6) that, if enabled, adjusts the PWM output to
indicate the signal strength of the cellular connection. Use P0 (DIO10/PWM0 Configuration) to enable
the RSSI pulse width modulation (PWM) output on the pin. If P0 is set to 1, the RSSI/PWM pin outputs a
PWM signal where the frequency is adjusted based on the received signal strength of the cellular
connection.
The RSSI/PWM output is enabled continuously unlike other XBee products where the output is enabled
for a short period of time after each received transmission. If running on the XBIB development board,
DIO10 is connected to the RSSI LEDs, which may be interpreted as follows:
Number of LEDs turned
PWM duty cycle
79.39% or more3-83 dBm or higher
onReceived signal strength (dBm)
62.42% to
79.39%
45.45% to
62.42%
Less than
45.45%
SIM card
The XBee Smart Modem uses a 4FF (Nano) size SIM card.
CAUTION! Never insert or remove SIM card while the power is on!
The Associate LED
The following table describes the Associate LED functionality. For the location of the Associate LED on
the XBIB-U development board, see number 6 on the XBIB-U-DEV reference.
2-93 to -83 dBm
1-103 to -93 dBm
0
Less than -103 dBm, or no cellular network
connection
Blink
LED status
On, solidNot joined to a mobile network.
Double blink
Standardsingleblink
The normal association LED signal alternates evenly between high and low as shown below:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
timingMeaning
½second
1second
The last TCP/UDP/SMS attempt failed. If the LED has this pattern,
you may need to check DI (Device Cloud Indicator) or CI
(Protocol/Connection Indication) for the cause of the error.
Normal operation.
64
HardwareThe Associate LED
Where the low signal means LED off and the high signal means LED on.
When CI is not 0 or 0xFF, the Associate LED has a different blink pattern that looks like this:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
65
Antenna recommendations
Antenna connections67
Antenna placement68
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
66
Antenna recommendationsAntenna connections
Antenna connections
CAUTION! The XBee Smart Modem will not function properly with only the secondary
antenna port connected!
The XBee Smart Modem has two U.FL antenna ports; a primary on the upper left of the board and a
secondary port on the upper right, see the drawing below. You must connect the primary port and the
secondary port is optional. The secondary antenna improves receive performance in certain
situations, so we recommend it for best results.
See FCC-approved antennas for a list of approved antennas.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
67
Antenna recommendationsAntenna placement
Connect the antenna cables as shown below.
WARNING! Cable directions matter. Do not cover the integrated antenna areas (the red
squares below) with cables. The left cable can travel up or down only.
Antenna placement
For optimal cellular reception, keep the antenna as far away from metal objects and other electronics
(including the XBee Smart Modem) as possible. Often, small antennas are desirable, but come at the
cost of reduced range and efficiency.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
68
Design recommendations
Cellular component firmware upgrades70
USB Direct design70
Power supply considerations70
Add a capacitor to the RESET line70
Heat considerations and testing71
Heat sink guidelines71
Add a fan to provide active cooling73
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
Even if you do not plan to use the USB interface, we strongly recommend you provide a way to access
the USB to support direct firmware upgrades of the cellular modem.
One way to provide access to the USB interface is to connect XBee pins 6, 7, and 8, and 10 to an
unpopulated USB connector; see USB Direct design for more information. At a minimum you should
connect pins 7 and 8 to test points so they are easy to wire to a connector if necessary.
If you are using pins 6, 7, and 8 for other purposes you must provide a way to disconnect those
interfaces during USB operation, such as using zero ohm resistors.
USB Direct design
Connect USB data pins 7 and 8 (USB_D+ and USB_D- respectively) on the XBee Smart Modem to the
appropriate pins on the host processor or connector. You may optionally connect pin 6 to VBUS if you
want USB to be enabled based on whether your host is connected. Alternatively, you may configure
VBUS in software; see USB direct mode for more details. VBUS is only used as a reference, not for
powering anything on the XBee Smart Modem, so it may be routed as a standard signal trace.
The USB interface follows the USB 2.0 high speed specification and data lines must be designed as a
90 Ω differential pair. Both traces should be the same length and the overall trace length should be
kept as short as possible. If you are connecting to a USB connector then we recommend that you
employ an ESD suppressor appropriate for USB 2.0 HS (for example the Littelfuse PESD0402-140).
Other than the ESD suppressor, do not place additional components in the signal paths. The
suppressor is not needed if you are connecting to an on-board host processor.
Power supply considerations
When considering a power supply, use the following design practices.
1. Power supply ripple should be less than 75 mV peak to peak.
2. The power supply should be capable of providing a minimum of 1.5 A at 3.3 V (5 W). Keep in
mind that operating at a lower voltage requires higher current capability from the power
supply to achieve the 5 W requirement.
3. Place sufficient bulk capacitance on the XBee VCC pin to maintain voltage above the minimum
specification during inrush current. Inrush current is about 2 A during initial power up of cellular
communications and wakeup from sleep mode.
4. Place smaller high frequency ceramic capacitors very close to the XBee Smart Modem VCC pin
to decrease high frequency noise.
5. Use a wide power supply trace or power plane to ensure it can handle the peak current
requirements with minimal voltage drop. We recommend that the power supply and trace be
designed such that the voltage at the XBee VCC pin does not vary by more than 0.1 V between
light load (~0.5 W) and heavy load (~3 W).
Add a capacitor to the RESET line
In high EMI noise environments, we recommend adding a 10 nF ceramic capacitor very close to pin 5.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
70
Design recommendationsHeat considerations and testing
Heat considerations and testing
The XBee Smart Modem may generate significant heat during sustained operation. In addition to
heavy data transfer, other factors that can contribute to heating include ambient temperature, air
flow around the device, and proximity to the nearest cellular tower (the XBee Smart Modem must
transmit at a higher power level when communicating over long distances). Overheating can cause
device malfunction and potential damage. In order to avoid this it is important to consider the
application the XBee Smart Modem is going into and mitigate heat issues if necessary. We recommend
that you perform thermal testing in your application to determine the resulting steady state
temperature of the XBee Smart Modem. Use TP (Temperature) to estimate the device temperature.
Convert the TP reading from hex format to decimal.
You also need to know the ambient temperature and the average current consumption during your
test. If you do not have a way to measure current consumption you can estimate it from the table in
the next section.
Use those results to approximate the maximum safe ambient temperature for the XBee Smart
Modem,TMAX,amb, with the following equation:
Where:
T
is the steady state temperature of the XBee Smart Modem that you measured during your test
XBee
(if using the TP command, be sure to convert from hex format to decimal).
T
amb,test
I
AVG,test
I
MAX
power; see Power consumption.
is the ambient air temperature during your test.
is the average current measured during your test.
is the average current draw expected for your application when transmitting at maximum RF
Heat sink guidelines
Based on the results of your thermal testing you may find it is advisable or required to implement a
method of dissipating excess heat. This section explains how to employ a heat sink on top of the XBee
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
71
Design recommendationsHeat sink guidelines
Smart Modem.
A bolt-down style heat sink on top of the XBee Smart Modem provides the best performance. An
example part number is Advanced Thermal Solutions ATS-PCBT1084/ATS-PCB1084. You must use an
electrically non-conductive thermal gasket on top of the XBee device under the area that will be
covered by the heat sink. A thermal gasket such as Gap Pad® 2500S20 is suitable for this purpose. We
recommend using a gasket with thickness of at least 0.080 in to ensure that components on top of
the XBee device do not tear through the material when pressure is applied to the heat sink.
Install the SIM card prior to placement of the heat sink. Position the thermal gasket and heat sink
assembly on the top of the device so that it covers the entire section shown inside the blue box below
(covering the RF shield with thermal gasket is optional because the RF shield is allowed to directly
contact the heat sink). Do not cover the U.FL connectors.
When attaching to the host PCB, tighten the mounting hardware until the gasket is compressed at
least 25% and the heat sink is snug against the RF shield. Avoid overtightening. To prevent shorting,
check that the surface of the heat sink does not directly contact any of the XBee device components.
The following table provides a list of typical scenarios and the maximum ambient temperature at
which the XBee Smart Modem can be safely operated under that condition. These are provided only as
guidelines as your results will vary based on application. We recommend that you perform sufficient
testing, as explained in Heat considerations and testing, to ensure that the XBee Smart Modem does
not exceed temperature specifications.
Maximum safe
ambient temperature
Heat
Average
current
Scenario
Maximum
transmission
duty cycle
50% duty cycle475 mARunning low resolution
consumption
(VCC = 3.3V)Example application
950 mARunning video camera500 to
video camera
Peak data
consumed
(MB/hr)
2000
200 to 400 TBD65 C75 C
sink
No
(bolt-
heat
down
sink
style)
N/A49 C70 C
Heat
sink
and
fan
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
72
Design recommendationsAdd a fan to provide active cooling
Maximum safe
ambient temperature
Heat
Scenario
Average
current
consumption
(VCC = 3.3V)Example application
Peak data
consumed
(MB/hr)
No
heat
sink
sink
(bolt-
down
style)
Heat
sink
and
fan
20% duty cycle200 mASending high resolution
photo less than once
per minute
Device awake,
limited
transmissions
Device primarily
asleep, very
limited
transmissions
170 mAUpdating traffic sign1 to 10TBD75 C80 C
20 mASmall data
transmission/receptions
which occur once per
hour
Add a fan to provide active cooling
Another option for heat mitigation is to add a fan to your system to provide active cooling. You can use
a fan instead of or in addition to a heat sink. The XBee Smart Modem offers a fan control feature on
I/O pin DIO11 (pin 7). When the functionality is enabled, that line is pulled high to indicate when the fan
should be turned on. The line is pulled high when the device gets above 70 °C and the cellular
component is running, and turns off when the device drops below 65 °C.
To enable the functionality set P1 (DIO11/PWM1 Configuration) to 1. Note that the I/O pin is not
capable of driving a fan directly; you must implement a circuit to power the fan from a suitable power
source.
50 to 150TBD74 C78 C
Less than
0.1
80 C 80 C80 C
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
73
Cellular connection process
Connecting75
Cellular network75
Data network connection75
Data communication with remote servers (TCP/UDP)75
Disconnecting75
SMS encoding76
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
74
Cellular connection processConnecting
Connecting
In normal operations, the XBee Smart Modem automatically attempts both a cellular network
connection and a data network connection on power-up. The sequence of these connections is as
follows:
Cellular network
1. The device powers on.
2. It looks for cellular towers.
3. It chooses a candidate tower with the strongest signal.
4. It negotiates a connection.
5. It completes cellular registration; the phone number and SMS are available.
Data network connection
1. The network enables the evolved packet system (EPS) bearer with an access point name
(APN). See AN (Access Point Name) if you have APNissues. You can use OA (Operating APN) to
query the APN value currently configured in the cellular component.
2. The device negotiates a data connection with the access point.
3. The device receives its IP configuration and address.
4. The AI (Association Indication) command now returns a 0 and the sockets become available.
Data communication with remote servers (TCP/UDP)
Once the data network connection is established, communication with remote servers can be
initiated in several ways:
n Transparent mode data sent to the serial port (see TD (Text Delimiter) and RO (Packetization
Timeout) for timing).
n API mode: Transmit (TX) Request: IPv4 - 0x20 received over the serial connection.
n Digi Remote Manager connectivity begins.
Data communication begins when:
1. A socket opens to the remote server.
2. Data is sent.
Data connectivity ends when:
1. The server closes the connection.
2. The TM timeout expires (see TM (IP Client Connection Timeout)).
3. The cellular network may also close the connection after a timeout set by the network
operator.
Disconnecting
When the XBee Smart Modem is put into Airplane mode or deep sleep is requested:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
75
Cellular connection processSMS encoding
1. Sockets are closed, cleanly if possible.
2. The cellular connection is shut down.
3. The cellular component is powered off.
Note We recommend entering Airplane mode before resetting or rebooting the device to allow the
cellular module to detach from the network.
SMS encoding
The XBee Smart Modem transmits SMS messages using the standard GSM 03.38 character set.
Because this character set only provides 7 bits of space per character, the XBee Smart Modem
ignores the most significant bit of each octet in an SMS transmission payload.
The device converts incoming SMS messages to ASCII. Characters that cannot be represented in
ASCIIare replaced with a space (' ', or 0x20 in hex). This includes emoji and other special characters.
1
1
Also referred to as the GSM 7-bit alphabet.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
76
Modes
Select an operating mode78
Transparent operating mode79
API operating mode79
Bypass operating mode79
USB direct mode80
Command mode80
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
77
ModesSelect an operating mode
Select an operating mode
The XBee Smart Modem interfaces to a host device such as a microcontroller or computer through a
logic-level asynchronous serial port. It uses a UART for serial communication with those devices.
The XBee Smart Modem supports three operating modes: Transparent operating mode, APIoperating
mode, and Bypass operating mode. The default mode is Transparent operating mode. Use the AP (API
Enable) command to select a different operating mode.
The following flowchart illustrates how the modes relate to each other.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
78
ModesTransparent operating mode
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 serial 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.
The IP (IP Protocol) command setting controls how Transparent operating mode works for the XBee
Smart Modem.
Note Transparent operation is not available when using SPI.
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 APIoperating mode include:
n It is easier to send information to multiple destinations
n The host receives the source address for each received data frame
n You can change parameters without entering Command mode
Bypass operating mode
CAUTION! Bypass operating mode is an alternative to Transparent and API modes for
advanced users with special configuration needs. Changes made in this mode might
change or disable the device and we do not recommended it for most users.
In Bypass mode, the device acts as a serial line replacement to the cellular component. In this mode,
the XBee Smart Modem exposes all control of the cellular component's AT port through the UART. If
you use this mode, you must setup the cellular modem directly to establish connectivity. The modem
does not automatically connect to the network.
Note The cellular component can become unresponsive in Bypass mode. See Unresponsive cellular
component in Bypass mode for help in this situation.
When Bypass mode is active, most of the XBee Smart Modem's AT commands do not work. For
example, IM (IMEI)may never return a value, and DB does not update. In this configuration, the
firmware does not test communication with the cellular component (which it does by sending AT
commands). This is useful in case you have reconfigured the cellular component in a way that makes it
incompatible with the firmware. Bypass operating mode exists for users who wish to communicate
directly with the cellular component settings and do not intend to use XBee Smart Modem software
features such as API mode.
Command mode is available while in Bypass mode; see Enter Command mode for instructions.
Enter Bypass operating mode
To configure a device for Bypass operating mode:
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
79
ModesUSB direct mode
1. Set the AP (API Enable) parameter value to 5.
2. Send WR command to write the changes.
3. Send FR (Force Reset) to reboot the device.
4. After rebooting, enter Command mode and verify that Bypass operating mode is active by
querying AI (Association Indication) and confirming that it returns a value of 0x2F.
It may take a moment for Bypass operating mode to become active.
Leave Bypass operating mode
To configure a device to leave Bypass operating mode:
1. Set AP (API Enable) to something other than 5.
2. Send WR command to write the changes.
3. Send FR (Force Reset) to reboot the device.
4. After rebooting, enter Command mode and verify that Bypass operating mode is not active by
querying AI (Association Indication) and confirming that it returns a value other than 0x2F.
Restore cellular settings to default in Bypass operating mode
Send AT&F1 to reset the cellular component to its factory profile.
USB direct mode
This mode allows you to replace the cellular component with the XBee Smart Modem such that the
USB lines are the same through a configuration option.
Enable USB direct mode
Set P1 (DIO11/PWM1 Configuration) to 7 to enable USB direct mode. When set to 7 DIO11/PWM1 (pin
7) brings out the USB D+ signal of the cellular component. The USB D- signal is available on pin 8. With
these pins connected to a USB host a direct connection is made to the cellular component which is not
mediated by the XBee processor.
When in USB direct mode AI (Association Indication) returns 0x2B.
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.
The three operating modes are controlled by the AP (API Enable) setting, but Command mode is
always available as a mode the XBee Smart Modem can enter while configured for any of the
operating modes.
Command mode is available on the UART interface in both Transparent and API modes. You cannot
use the SPI interface to enter Command mode.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
80
ModesCommand mode
Enter Command mode
To get a device to switch into this mode, you must issue the following sequence: +++ within one
second. There must be at least one second preceding and following the +++ sequence. Both the
command character (CC) and the silence before and after the sequence (GT) are configurable. When
the device sees a full second of silence in the data stream (the guard time, GT) followed by the string
+++ (without Enter or Return) and another full second of silence, it knows to stop sending data 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 the previous operating mode (Transparent, Bypass, API, Python, and
so forth).
You can customize the command character, the guard times and the timeout in the device’s
configuration settings. For more information, see CC (Command Sequence Character), CT (Command
Mode Timeout) and GT (Guard Times).
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 b/s).
There are two alternative ways to enter Command mode:
n A serial break for six seconds enters Command mode. The "break" command can be issued
from a serial console, and is often a button or menu item.
n Asserting DIN (serial break) upon power up or reset enters Command mode. XCTU guides you
through a reset and automatically issues the break when needed.
Both of these methods temporarily set the device's baud rate to 9600 and return an OK on the UART
to indicate that Command mode is active. When Command mode exits, the device returns to normal
operation at the baud rate the BD parameter is set to.
Send AT commands
Once the device enters Command mode, use the syntax in the following figure to send AT commands.
Every AT command starts with the letters AT, which stands for "attention." The AT is followed by two
characters that indicate which command is being issued, then by some optional configuration values.
To read a parameter value stored in the device’s register, omit the parameter field.
The preceding example changes the IP protocol to SMS.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
81
ModesCommand mode
Multiple AT commands
You can send multiple AT commands at a time when they are separated by a comma in Command
mode; for example, ATSH,SL.
Parameter format
Refer to the list of AT commands for the format of individual AT command parameters. Valid formats
for hexidecimal values include with or without a leading 0x for example FFFF or 0xFFFF.
Response to AT commands
When reading parameters, the device returns the current parameter value instead of an OK message.
Apply command changes
Any changes you make to the configuration command registers using AT commands do not take effect
until you apply the changes. For example, if you send the BD command to change the baud rate, the
actual baud rate does not change until you apply the changes. To apply changes:
1. Send the AC (Apply Changes) command.
or:
2. Exit Command mode.
Make command changes permanent
Issue a WR command command to save the changes. WR writes parameter values to non-volatile
memory so that parameter modifications persist through subsequent resets.
Exit Command mode
1. Send CN command followed by a carriage return.
or:
2. If the device does not receive any valid AT commands within the time specified by CT
(Command Mode Timeout), it returns to the mode that the device was last in.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
82
Sleep modes
About sleep modes84
Normal mode84
Pin sleep mode84
Cyclic sleep mode84
Cyclic sleep with pin wake up mode84
Airplane mode84
Connected sleep mode84
The sleep timer85
MicroPython sleep behavior85
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
83
Sleep modesAbout sleep modes
About sleep modes
A number of low-power modes exist to enable devices to operate for extended periods of time on
battery power. Use SM (Sleep Mode) to enable these sleep modes.
Normal mode
Set SM to 0 to enter Normal mode.
Normal mode is the default sleep mode. If a device is in this mode, it does not sleep and is always
awake.
Devices in Normal mode are typically mains powered.
Pin sleep mode
Set SM to 1 to enter pin sleep mode.
Pin sleep allows the device to sleep and wake according to the state of the SLEEP_RQ pin (SLEEP_RQ).
When you assert SLEEP_RQ (high), the device finishes any transmit or receive operations, closes any
active connection, and enters a low-power state.
When you de-assert SLEEP_RQ (low), the device wakes from pin sleep.
Cyclic sleep mode
Set SM to 4 to enter Cyclic sleep mode.
Cyclic sleep allows the device to sleep for a specific time and wake for a short time to poll.
If you use the D7 command to enable hardware flow control, the CTS pin asserts (low) when the
device wakes and can receive serial data, and de-asserts (high) when the device sleeps.
Cyclic sleep with pin wake up mode
Set SM to 5 to enter Cyclic sleep with pin wake up mode.
This mode is a slight variation on Cyclic sleep mode (SM = 4) that allows you to wake a device
prematurely by de-asserting the SLEEP_RQ pin (SLEEP_RQ).
In this mode, you can wake the device after the sleep period expires, or if a high-to-low transition
occurs on the SLEEP_RQ pin.
Airplane mode
While not technically a sleep mode, airplane mode is another way of saving power. When set, the
cellular component of the XBee Smart Modem is fully turned off and no access to the cellular network
is performed or possible. Use AM (Airplane Mode) to configure this mode.
Connected sleep mode
XBee Smart Modem hardware part number XB3-C-A1-UT-xxx can enter Connected sleep mode.
Set bit 0 of SO (Sleep Options) for connected sleep. When bit 0 is set and the XBee Smart Modem goes
to sleep, instead of the cellular component shutting down, it enters a lower power consumption mode
that maintains registration with the cellular network. This allows significantly faster resumption of
communications when coming out of sleep at the cost of additional power used.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
84
Sleep modesThe sleep timer
Connected sleep mode draws 9 mA during sleep and 11 mA average over time (including periodically
waking up to maintain connection).
The sleep timer
If the device receives serial or RF data in Cyclic sleep mode and Cyclic sleep with pin wake up modes
(SM = 4 or SM = 5), it starts a sleep timer (time until sleep).
n Use ST (Wake Time) to set the duration of the timer.
n When the sleep timer expires the device returns to sleep.
MicroPython sleep behavior
When the XBee Smart Modem enters deep sleep mode, any MicroPython code currently executing is
suspended until the device comes out of sleep. When the XBee Smart Modem comes out of sleep
mode, MicroPython execution continues where it left off.
Upon entering deep sleep mode, the XBee Smart Modem closes any active UDP connections and turns
off the cellular component. As a result, any sockets that were opened in MicroPython prior to sleep
report as no longer being connected. This behavior appears the same as a typical socket
disconnection event will:
n socket.send raises OSError: ENOTCONN
n socket.sendto raises OSError: ENOTCONN
n socket.recv returns the empty string, the traditional end-of-file return value
n socket.recvfrom returns an empty message, for example:
(b'', (<address from connect()>, <port from connect()>) )
The underlying UDP socket resources have been released at this point.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
85
Serial communication
Serial interface87
Serial data87
UART data flow87
Serial buffers87
CTS flow control88
RTS flow control88
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
86
Serial communicationSerial interface
Serial interface
The XBee Smart Modem interfaces to a host device through a serial port. The device can communicate
through its serial port with:
n Through logic and voltage compatible universal asynchronous receiver/transmitter (UART).
n Through a level translator to any serial device, for example, through an RS-232 or USB
interface board.
n Through a serial peripheral interface (SPI) port.
Serial data
A device sends data to the XBee Smart Modem's UART through pin 3 DIN as an asynchronous serial
signal. When the device is not transmitting data, the signals should idle high.
For serial communication to occur, you must configure the UART of both devices (the microcontroller
and the XBee Smart Modem) with compatible settings for the baud rate, parity, start bits, stop bits,
and data bits.
Each data byte consists of a start bit (low), 8 data bits (least significant bit first) and a stop bit (high).
The following diagram illustrates the serial bit pattern of data passing through the device. The
diagram shows UART data packet 0x1F (decimal number 31) as transmitted through the device.
You can configure the UART baud rate, parity, and stop bits settings on the device with the BD, NB,
and SB commands respectively. For more information, see Serial interfacing commands.
In the rare case that a device has been configured with the UART disabled, you can recover the device
to UART operation by holding DIN low at reset time. DIN forces a default configuration on the UART at
9600 baud and it brings the device up in Command mode on the UART port. You can then send the
appropriate commands to the device to configure it for UART operation. If those parameters are
written, the device comes up with the UART enabled on the next reset.
UART data flow
Devices that have a UART interface connect directly to the pins of the XBee Smart Modem as shown in
the following figure. The figure shows system data flow in a UART-interfaced environment. Lowasserted signals have a horizontal line over the signal name.
Serial buffers
The XBee Smart Modem maintains internal buffers to collect serial and RF data that it receives. The
serial receive buffer collects incoming serial characters and holds them until the device can process
them. The serial transmit buffer collects the data it receives via the RF link until it transmits that data
out the serial or SPI port.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
87
Serial communicationCTS flow control
CTS flow control
We strongly encourage you to use flow control with the XBee Smart Modem to prevent buffer
overruns.
CTS flow control is enabled by default; you can disable it with D7 (DIO7/CTS). When the serial receive
buffer fills with the number of bytes specified by FT (Flow Control Threshold), the device de-asserts
CTS (sets it high) to signal the host device to stop sending serial data. The device re-asserts CTS when
less than FT-32 bytes are in the UART receive buffer.
Note Serial flow control is not possible when using the SPI port.
RTS flow control
If you set D6 (DIO6/RTS) to enable RTS flow control, the device does not send data in the serial
transmit buffer out the DOUT pin as long as RTS is de-asserted (set high). Do not de-assert RTS for
long periods of time or the serial transmit buffer will fill.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
89
AT commandsMicroPython commands
MicroPython commands
The following commands relate to using MicroPython on the XBee Smart Modem.
PS (Python Startup)
Sets whether or not the XBee Smart Modem runs the stored Python code at startup.
Range
0 - 1
ParameterDescription
0Do not run stored Python code at startup.
1Run stored Python code at startup.
Default
0
PY (MicroPython Command)
Interact with the XBee Smart Modem using MicroPython. PY is a command with sub-commands.
These sub-commands are arguments to PY.
PYC(Code Report)
You can store compiled code in flash using the Ctrl-F command from the MicroPython REPL; refer to
the Digi MicroPython Programming Guide. The PYC sub-command reports details of the stored code.
In Command mode, it returns three lines of text, for example:
n source: the size of the source code used to generate the bytecode and its 32-bit hash.
n bytecode:the size of bytecode stored in flash and its 32-bit hash. A size of 0 indicates that
there is no stored code.
n compiled:a compilation timestamp. A timestamp of 2000-01-01T00:00:00 indicates that the
clock was not set during compilation.
In API mode, PYC returns five 32-bit big-endian values:
n source size
n source hash
n bytecode size
n bytecode hash
n timestamp as seconds since 2000-01-01T00:00:00
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
90
AT commandsSpecial commands
PYD (Delete Code)
PYDinterrupts any running code, erases any stored code and then does a soft-reboot on the
MicroPython subsystem.
PYV (Version Report)
Report the MicroPython version.
PY^ (Interrupt Program)
Sends KeyboardInterrupt to MicroPython. This is useful if there is a runaway MicroPython program
and you have filled the stdin buffer. You can enter Command mode (+++) and send ATPY^ to interrupt
the program.
Default
N/A
Special commands
The following commands are special commands.
AC (Apply Changes)
Immediately applies new settings without exiting Command mode.
Applying changes means that the device re-initializes based on changes made to its parameter values.
Once changes are applied, the device immediately operates according to the new parameter values.
This behavior is in contrast to issuing the WR (Write) command. The WR command saves parameter
values to non-volatile memory, but the device still operates according to previously saved values until
the device is rebooted or you issue the CN (Exit AT Command Mode) or AC commands.
Parameter range
N/A
Default
N/A
FR (Force Reset)
Resets the device. The device responds immediately with an OK and performs a reset 100 ms later.
If you issue FR while the device is in Command Mode, the reset effectively exits Command mode.
Note We recommend entering Airplane mode before resetting or rebooting the device to allow the
cellular module to detach from the network.
Parameter range
N/A
Default
N/A
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
91
AT commandsCellular commands
RE command
Restore device parameters to factory defaults.
The RE command does not write restored values to non-volatile (persistent) memory. Issue the WR
(Write) command after issuing the RE command to save restored parameter values to non-volatile
memory.
Parameter range
N/A
Default
N/A
WR command
Writes parameter values to non-volatile memory so that parameter modifications persist through
subsequent resets.
Note Once you issue a WR command, do not send any additional characters to the device until after
you receive the OK response.
Parameter range
N/A
Default
N/A
Cellular commands
The following AT commands are cellular configuration and data commands.
PH (Phone Number)
Reads the SIM card phone number. If PH is blank, the XBee Smart Modem is not registered to the
network.
Parameter range
N/A
Default
Set by the cellular carrier via the SIM card
S# (ICCID)
Reads the Integrated Circuit Card Identifier (ICCID) of the inserted SIM.
Parameter range
N/A
Default
Set by the SIMcard
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
92
AT commandsCellular commands
IM (IMEI)
Reads the device's International Mobile Equipment Identity (IMEI).
Parameter range
N/A
Default
Set in the factory
MN (Operator)
Reads the network operator on which the device is registered.
Parameter range
N/A
Default
AT&T
MV (Modem Firmware Version)
Read the firmware version string for cellular component communications. See the related VR
(Firmware Version) command.
Parameter range
N/A
Default
Set in the currently loaded firmware
DB (Cellular Signal Strength)
Reads the absolute value of the current signal strength to the cell tower in dB. If DB is blank, the XBee
Smart Modem has not received a signal strength from the cellular component.
Parameter range
0x71 - 0x33 (-113 dBm to -51 dBm) [read-only]
Default
N/A
AN (Access Point Name)
Specifies the packet data network that the modem uses for Internet connectivity. This information is
provided by your cellular network operator. After you set this value, applying changes with AC (Apply
Changes) or CN (Exit Command mode) triggers a network reset.
Parameter range
1 - 100 ASCII characters
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
93
AT commandsCellular commands
Default
-
OA (Operating APN)
Reads the APN value currently configured in the cellular component.
Parameter range
ASCII characters
Default
N/A
AM (Airplane Mode)
When set, the cellular component of the XBee Smart Modem is fully turned off and no access to the
cellular network is performed or possible.
Parameter range
0 - 1
0 = Normal operation
1 = Airplane mode
Default
0
DV (Antenna Diversity)
Set and read the antenna diversity setting of the cellular component. When enabled, the cellular
component uses both antennas to improve receive sensitivity.
This setting is applied only while the XBee Smart Modem is initializing the cellular component. After
changing this setting, you must:
1. Use WR command to write all values to flash.
2. Use FR (Force Reset) to reset the device.
3. Wait for the cellular component to be initialized: AI (Association Indication) reaches 0x00.
4. Use FR to reset the device a second time.
5. Wait again for the cellular component to initialize:AI reaches 0x00.
Parameter range
0 - 1
0 - diversity disabled
1 - diversity enabled
Default
1
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
94
AT commandsNetwork commands
Network commands
The following commands are network commands.
IP (IP Protocol)
Sets or displays the IP protocol used for client and server socket connections in IP socket mode.
Parameter range
0 - 4
ValueDescription
0x00UDP
0x01TCP
0x02SMS
0x03Reserved
0x04SSL over TCPcommunication
Default
0x01
TL (SSL/TLS Protocol Version)
Sets the SSL/TLS protocol version used for the SSL socket. If you change the TL value, it does not
affect any currently open sockets. The value only applies to subsequently opened sockets.
Note Due to known vulnerabilities in prior protocol versions, we strongly recommend that you use the
latest TLS version whenever possible.
Range
ValueDescription
0x00
0x01
0x02
0x03
Default
0x03
SSL v3
TLS v1.0
TLS v1.1
TLS v1.2
TM (IP Client Connection Timeout)
The IP client connection timeout. If there is no activity for this timeout then the connection is closed. If
TMis 0, the connection is closed immediately after the device sends data.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
95
AT commandsNetwork commands
If you change the TM value while in Transparent Mode, the current connection is immediately closed.
Upon the next transmission, the TM value applies to the newly created socket.
If you change the TM value while in API Mode, the value only applies to subsequently opened sockets.
Parameter range
0 - 0xFFFF [x 100 ms]
Default
0xBB8 (5 minutes)
TS (IP Server Connection Timeout)
The IP server connection timeout. If no activity for this timeout then the connection is closed. When
set to 0 the connection is closed immediately after data is sent.]
Parameter Range
10 - 0xFFFF; (x 100 ms)
Default
3000
DO (Device Options)
Enables and disables special features on the XBee Smart Modem according to the following table.
Bit 0 - Remote Manager support
If the XBee Smart Modem cannot establish a connection with Remote Manager , it waits 30 seconds
before trying again. On each successive connection failure, the wait time doubles (60 seconds, 120,
240, and so on) up to a maximum of 1 hour. This time resets to 30 seconds once the connection to
Remote Manager succeeds or if the device is reset.
Bits 1 - 7
Reserved
Range
0x00 - 0x07
ValueDescription
0x00Disable Remote Manager support.
0x01Enable Remote Manager support.
Default
0x01
EQ (Device Cloud FQDN)
Sets or display the fully qualified domain name of the Remote Manager server.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
96
AT commandsAddressing commands
Range
From 0 through 63 ASCII characters.
Default
my.devicecloud.com
Addressing commands
The following AT commands are addressing commands.
SH (Serial Number High)
The upper digits of the unique International Mobile Equipment Identity (IMEI) assigned to this device.
Parameter range
0 - 0xFFFFFFFF [read-only]
Default
N/A
SL (Serial Number Low)
The lower digits of the unique International Mobile Equipment Identity (IMEI) assigned to this device.
Parameter range
0 - 0xFFFFFFFF [read-only]
Default
N/A
DL (Destination Address)
The destination IPv4 address or fully qualified domain name.
To set the destination address to an IP address, the value must be a dotted quad, for example
XXX.XXX.XXX.XXX.
To set the destination address to a domain name, the value must be a legal Internet host name, for
example remotemanager.digi.com
Parameter range
0 - 128 ASCII characters
Default
0.0.0.0
P# (Destination Phone Number)
Sets or displays the destination phone number used for SMS when IP (IP Protocol) = 2. Phone numbers
must be fully numeric, 7 to 20 ASCIIdigits, for example:8889991234.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
97
AT commandsAddressing commands
P# allows international numbers with or without the + prefix. If you omit + and are dialing
internationally, you need to include the proper International Dialing Prefix for your calling region, for
example, 011 for the United States.
Range
7 - 20 ASCII digits including an optional + prefix
Default
N/A
N1 (DNS Address)
Displays the IPv4 address of the primary domain name server.
Parameter Range
Read-only
Default
0.0.0.0 (waiting on cellular connection)
N2 (DNS Address)
Displays the IPv4 address of the secondary domain name server.
Parameter Range
Read-only
Default
0.0.0.0 (waiting on cellular connection)
DE (Destination Port)
Sets or displays the destination IP port number.
Parameter range
0x0 - 0xFFFF
Default
0x2616
TD (Text Delimiter)
The ASCII character used as a text delimiter for Transparent mode. When you select a character,
information received over the serial port in Transparent mode is not transmitted until that character
is received. To use a carriage return, set to 0xD. Set to zero to disable text delimiter checking.
Parameter range
0 - 0xFF
Default
0x0
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
98
AT commandsAddressing commands
MY (Module IP Address)
Reads the device's IP address. This command is read-only because the IPaddress is assigned by the
mobile network.
In APImode, the address is represented as the binary four byte big-endian numeric value representing
the IPv4 address.
In Transparent or Command mode, the address is represented as a dotted-quad string notation.
Parameter range
0- 15 IPv4 characters
Default
0.0.0.0
LA (Lookup IP Address of FQDN)
Performs a DNS lookup of the given fully qualified domain name (FQDN) and outputs its IP address.
When you issue the command in API mode, the IP address is formatted in binary four byte big-endian
numeric value. In all other cases (for example, Command mode) the format is dotted decimal notation.
Range
Valid FQDN
Default
-
OD (Operating Destination Address)
Read the destination IPv4 address currently in use by Transparent mode. The value is 0.0.0.0 if no
Transparent IP connection is active.
In API mode, the address is represented as the binary four byte big-endian numeric value representing
the IPv4 address.
In Transparent or Command mode, the address is represented as a dotted-quad string notation.
Parameter range
-
Default
0.0.0.0
C0 (Source Port)
Set or get the port number used to provide the serial communication service. Data received by this
port on the network is transmitted on the XBee Smart Modem's serial port.
As long as a network connection is established to this port (for TCP) data received on the serial port is
transmitted on the established network connection.
IP (IP Protocol) sets the protocol used when UART is in Transparent or APImode.
For more information on using incoming connections, see Socket behavior.
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
99
AT commandsSerial interfacing commands
Parameter range
0 - 0xFFFF
ValueDescription
0Disabled
Non-0Enabled on that port
Default
0
Serial interfacing commands
The following AT commands are serial interfacing commands.
BD (Baud Rate)
Sets or displays the serial interface baud rate for communication between the device's serial port and
the host.
Modified interface baud rates do not take effect until the XBee Smart Modem exits Command mode or
you issue AC (Apply Changes). The baud rate resets to default unless you save it with WR command or
by clicking the Write module settings button in XCTU.
Parameter range
Standard baud rates:0x1 - 0x8
Non-standard baud rates:0x5B9 to 0x3D090 (250,000 b/s)
ParameterDescription
0x01200 b/s
0x12400 b/s
0x24800 b/s
0x39600 b/s
0x419200 b/s
0x538400 b/s
0x657600 b/s
0x7115200 b/s
0x8230400 b/s
Default
0x3 (9600 b/s)
Digi XBee3 Cellular LTE Cat 1 Smart Modem User Guide
100
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.