Digi XBee3 XB3M1 User Manual

Download

Page 1

Digi XBee3® Cellular LTE-M/NB-IoT

Smart Modem

User Guide

Page 2

Revision history—90002258

Revision Date Description

F November

2018

G February

2019

H April 2019 Added information for Digi Remote Manager®

I May 2019

J June 2019

Added information for BLE

Added information for XBIB-C-TH and XBIB-C-GPS development boards

Added information for Clean shutdown and securing the connection between and XBee and Remote Manager.

Added FCC publication 996369 related information. Added firmware update information.

Trademarks and copyright

Digi, Digi International, and the Digi logo are trademarks or registered trademarks in the United States and other countries worldwide. All other trademarks mentioned in this document are the property of their respective owners.

Disclaimers

Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International. Digi provides this document “as is,” without warranty of any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or merchantability for a particular purpose. Digi may make improvements and/or changes in this manual or in the product(s) and/or the program(s) described in this manual at any time.

Warranty

To view product warranty information, go to the following website:

www.digi.com/howtobuy/terms

Customer support

Gather support information: Before contacting Digi technical support for help, gather the following

information:

Product name and model

Product serial number (s)

Firmware version

Operating system/browser (if applicable)

Logs (from time of reported issue)

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 3

Trace (if possible)

Description of issue

Steps to reproduce

Contact Digi technical support: Digi offers multiple technical support plans and service packages. Contact us at +1 952.912.3444 or visit us at www.digi.com/support.

Feedback

To provide feedback on this document, email your comments to

Include the document title and part number (Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide, 90002258 I) in the subject line of your email.

techcomm@digi.com

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 4

Contents

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Applicable firmware and hardware 15 SIM cards 15 NB-IoT network 15

Get started with the XBee Smart Modem Development Kit

Identify the kit contents 17 Acquire a SIM card 18

UScustomers 18

European customers 18 Connect the hardware 19 XBIB-U-DEV reference 21 XBIB-CU-TH reference 23 XBIB-C-GPS reference 26 Interface with the XBIB-C-GPS module 27

I2C communication 28

UART communication 28

Run the MicroPython GPSdemo 28 Cellular service 29 Configure and update your XBee 30

Add a device 30

Update to the latest firmware from XCTU 31

Configure your module for cellular connectivity 31

Check for cellular registration and connection 33

Update an XBee module from A2.00 to A2.01 using APImode 34

Update an XBee module from A2.00 to A2.01 using FOTA 37 XBee bootloader 39

XBee connection examples

Connect to the Echo server 42 Connect to the ELIZA server 44 Connect to the Daytime server 46 Perform a (GET) HTTP request 48 Get started with CoAP 50

CoAP terms 50

CoAP quick start example 50

Configure the device 51

Example: manually perform a CoAPrequest 51

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 5

Example: use Python to generate a CoAP message 52 Connect to a TCP/IP address 54 Get started with MQTT 55

Example: MQTT connect 55

Send a connect packet 57

Example: send messages (publish) with MQTT 58

Example: receive messages (subscribe) with MQTT 59

Use MQTT over the XBee Cellular Modem with a PC 60 Debugging 63 Software libraries 63

Get started with MicroPython

About MicroPython 65

Why use MicroPython 65 MicroPython on the XBee Smart Modem 65 Use XCTU to enter the MicroPython environment 65 Use the MicroPython Terminal in XCTU 66

Troubleshooting 66 Example: hello world 66 Example: turn on an LED 66 Example: debug the secondary UART 67 Exit MicroPython mode 68 Other terminal programs 68

Tera Term for Windows 69 Use picocom in Linux 70

Get started with BLE

Enable BLE on an XBee device 72 Enable BLEand configure the BLEpassword using XCTU 72 Get the Digi XBeeMobile phone application 73 Connect with BLEand configure your XBee device 74 BLE reference 74

BLE advertising behavior and services 74

Device Information Service 74

XBee API BLEService 75

API Request characteristic 75

API Response characteristic 75

Get started with Digi Remote Manager

Create a Remote Manager account and add devices 77

Create a Remote Manager account 78

Add an XBee Smart Modem to Remote Manager 78

Verify the connection between a device and Remote Manager 79 Configure Remote Manager features by scheduling tasks 79

Overview: Create a schedule for a set of tasks 80

Examples 80

Example: Read settings and state using Remote Manager 80

Example: Configure a device from Remote Manager using XML 81

Example: Update XBee firmware using Remote Manager 82

Example: Update MicroPython from Remote Manager using XML 83

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 6

Restore persistent connection to a remote XBee 87 Manage data in Remote Manager 88

Review device status information from Remote Manager 89

Update the firmware from Remote Manager 89

Update the firmware using web services in Remote Manager 91

Manage secure files in Remote Manager 94 Remote Manager reference 95

Enable SM/UDP 95

Disconnect 96

Configure XBee settings within Remote Manager 96

Technical specifications

Interface and hardware specifications 100 Cellular RF characteristics 100 Bluetooth RF characteristics 100 Cellular networking specifications 100 Power requirements 101 Power consumption 102 Electrical specifications 103 Regulatory approvals 104

Hardware

Mechanical drawings 106 Pin signals 106

Pin connection recommendations 107 RSSI PWM 108 SIM card 108 Associate LED functionality 108

Antenna recommendations

Antenna placement 111

Design recommendations

Cellular component firmware updates 113 Power supply considerations 113 Minimum connection diagram 113 Heat considerations and testing 114 Custom configuration: Create a new factory default 114

Set a custom configuration 115

Clear all custom configurations on a device 115 Clean shutdown 115

SD (Shutdown) command 115

Sleep feature 116

Airplane mode 116

Cellular connection process

Connecting 118

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 7

Cellular network 118

Data network connection 118 Data communication with remote servers (TCP/UDP) 118 Disconnecting 119

Modes

Select an operating mode 121 Transparent operating mode 122 API operating mode 122 Command mode 122

Enter Command mode 122

Troubleshooting 123

Send AT commands 123

Response to AT commands 123

Apply command changes 124

Make command changes permanent 124

Exit Command mode 124 MicroPython mode 124 USB direct mode 125

Configure the data pins 125

Enable USB direct mode 125 Bypass operating mode (DEPRECATED) 125

Enter Bypass operating mode 126

Leave Bypass operating mode 126

Restore cellular settings to default in Bypass operating mode 126

Sleep modes

About sleep modes 128 Normal mode 128 Pin sleep mode 128 Cyclic sleep mode 128 Cyclic sleep with pin wake up mode 128 SPI mode and sleep pin functionality 128 The sleep timer 129 MicroPython sleep behavior 129

Power saving features

Airplane mode 131 Power Saving Mode (PSM) 131 PSM behavior 131 Deep Sleep mode 131

Serial communication

Serial interface 134 Serial data 134 UART data flow 134 Serial buffers 135 CTS flow control 135 RTS flow control 135

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 8

Enable UART or SPI ports 135 I2C 136

SPI operation

SPI communications 138 Full duplex operation 139 Low power operation 140 Select the SPI port 140 Force UART operation 141 Data format 141

File system

Overview of the file system 143

Directory structure 143

Paths 143

Secure files 143 XCTU interface 144 Encrypt files 144

Socket behavior

Supported sockets 146 Best practices when using sockets 146

Sockets and Remote Manager 146

Sockets and API mode 146 Socket timeouts 146 Socket limits in API mode 147 Enable incoming TCP sockets in API mode 147 API mode behavior for outgoing TCP and SSL connections 147 API mode behavior for outgoing UDP data 148 API mode behavior for incoming TCP connections 148 API mode behavior for incoming UDP data 149 Transparent mode behavior for outgoing TCP and SSL connections 149 Transparent mode behavior for outgoing UDP data 150 Transparent mode behavior for incoming TCP connections 150 Transparent mode behavior for incoming UDP connections 150

Transport Layer Security (TLS)

TLS AT commands 152 Transparent mode and TLS 153 API mode and TLS 153 Key formats 153 Certificate formats 153 Certificate limitations 153 Cipher suites 154 Server Name Indication (SNI) 154 Secure the connection between an XBee and Remote Manager with server authentication 154

Step 1: Get the certificate 155

Step 2: Configure device 155

Step 3: Verify that authentication is being performed 155

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 9

AT commands

Special commands 158

AC (Apply Changes) 158

FR (Force Reset) 158

RE (Restore Defaults) 158

WR (Write) 158 Cellular commands 160

PH (Phone Number) 160

S# (ICCID) 160

IM (IMEI) 160

MN (Operator) 160

MV (Modem Firmware Version) 160

DB (Cellular Signal Strength) 161

AN (Access Point Name) 161

CP (Carrier Profile) 161

BM (Bandmask) (LTE-M) 162

BN (Bandmask) (NB-IoT) 162

AM (Airplane Mode) 163

N# (Preferred Network Technology) 163 Network commands 165

IP (IP Protocol) 165

TL (SSL/TLS Protocol Version) 165

$0 (SSL/TLS Profile 0) 166

$1 (SSL/TLS Profile 1) 166

$2 (SSL/TLS Profile 2) 166

TM (IP Client Connection Timeout) 167

TS (IP Server Connection Timeout) 167

DO (Device Options) 167

DT (Cellular Network Time) 168 Addressing commands 169

SH (Serial Number High) 169

SL (Serial Number Low) 169

MY (Module IP Address) 169

P# (Destination Phone Number) 169

N1 (DNS Address) 170

N2 (DNS Address) 170

DL (Destination Address) 170

OD (Operating Destination Address) 170

DE (Destination port) 171

C0 (Source Port) 171

LA (Lookup IP Address of FQDN) 171 Serial interfacing commands 172

BD (Baud Rate) 172

NB (Parity) 172

SB (Stop Bits) 173

RO (Packetization Timeout) 173

TD (Text Delimiter) 173

FT (Flow Control Threshold) 173

AP (API Enable) 174 I/O settings commands 175

D0 (DIO0/AD0) 175

D1 (DIO1/AD1) 175

D2 (DIO2/AD2) 176

D3 (DIO3/AD3) 176

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 10

D4 (DIO4) 176

D5 (DIO5/ASSOCIATED_INDICATOR) 177

D6 (DIO6/RTS) 177

D7 (DIO7/CTS) 177

D8 (DIO8/SLEEP_REQUEST) 178

D9 (DIO9/ON_SLEEP) 178

P0 (DIO10/PWM0 Configuration) 179

P1 (DIO11/PWM1 Configuration) 179

P2 (DIO12 Configuration) 180

P3 (DIO13/DOUT) 180

P4 (DIO14/DIN) 181

PD (Pull Direction) 181

PR (Pull-up/down Resistor Enable) 181

M0 (PWM0 Duty Cycle) 182 I/O sampling commands 183

TP (Temperature) 183

IS (Force Sample) 183 Sleep commands 185

SM (Sleep Mode) 185

SP (Sleep Period) 185

ST (Wake Time) 185

PA (Requested Active Timer) 186

PU (Requested Tracking Area Update Timer) 186 Command mode options 187

CC (Command Sequence Character) 187

CT (Command Mode Timeout) 187

CN (Exit Command mode) 187

GT (Guard Times) 187 MicroPython commands 189

PS (Python Startup) 189

PY (MicroPython Command) 189 Firmware version/information commands 191

VR (Firmware Version) 191

VL (Verbose Firmware Version) 191

HV (Hardware Version) 191

AI (Association Indication) 191

HS (Hardware Series) 192

CK (Configuration CRC) 192 Diagnostic interface commands 193

DI (Remote Manager Indicator) 193

CI (Protocol/Connection Indication) 193

AS (Active scan for network environment data) 195 Execution commands 196

NR (Network Reset) 196

!R (Modem Reset) 196 File system commands 197

Error responses 197

ATFS (File System) 197

ATFS PWD 197

ATFS CDdirectory 197

ATFS MDdirectory 197

ATFS LS [directory] 197

ATFS PUTfilename 198

ATFS XPUTfilename 198

ATFS HASHfilename 198

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 11

ATFS GETfilename 198

ATFS MVsource_pathdest_path 198

ATFS RMfile_or_directory 198

ATFS INFO 198

ATFSFORMAT confirm 199 BLE commands 200

BL (Bluetooth MAC address) 200

BT (Bluetooth enable) 200

$S (SRPSalt) 200

$V, $W, $X, $Y (SRPpassword verifier) 201 Remote Manager commands 202

DF (Remote Manager Status Check Interval) 202

EQ (Remote Manager FQDN) 202

K1 (Remote Manager Server Send Keepalive) 202

K2 (Remote Manager Device Send Keepalive) 202

MO (Remote Manager Options) 203

$D (Remote Manager certificate) 203

RI (Remote Manager Service ID) 203

DP (Remote Manager Phone Number) 204

HF (Health Metrics Reporting Frequency) 204

HM (Health Metrics) 204 System commands 205

KL (Device Location) 205

KP (Device Description) 205

KC (Contact Information) 205

Operate in API mode

API mode overview 207 Use the AP command to set the operation mode 207 API frame format 207

API operation (AP parameter = 1) 207

API operation with escaped characters (AP parameter = 2) 208

API frames

AT Command - 0x08 212 AT Command: Queue Parameter Value - 0x09 213 Transmit (TX) SMS - 0x1F 214 Transmit (TX) Request: IPv4 - 0x20 215 Tx Request with TLS Profile - 0x23 217 AT Command Response - 0x88 219 Transmit (TX) Status - 0x89 220 Modem Status - 0x8A 222 Receive (RX) Packet: SMS - 0x9F 223 Receive (RX) Packet: IPv4 - 0xB0 224 User Data Relay - 0x2D 225

Example use cases 225 User Data Relay Output - 0xAD 227 BLE Unlock API - 0x2C 228

Example sequence to perform AT Command XBee API frames over BLE 230 BLEUnlock Response - 0xAC 232

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 12

Packaged firmware updates

About packaged firmware updates 234

Module firmware update 234

Cellular component firmware update 234

Packaged firmware update 234 FW Update - 0x2B 235 FW Update Response - 0xAB 235 Important notes 236 Perform a cellular component firmware update 236 Error recovery 237

Corrupted firmware on the cellular component 237

Error 237

Host initiated cancellation 237

Troubleshooting

Cannot find the serial port for the device 239

Condition 239

Solution 239

Other possible issues 240

Enable Virtual COM port (VCP) on the driver 240 Correct a macOS Java error 241

Condition 241

Solution 241 Unresponsive cellular component in Bypass mode 242

Condition 242

Solution 242 Syntax error at line 1 242

Solution 242 Error Failed to send SMS 242

Solution 242 Network connection issues 243

Condition 243

Solution 243 Brownout issue 243

Voltage brownout 243

Power-on discontinuities 243

How to distinguish revision B parts 243 Hardware flow control in Bypass mode 244 Socket leaks 244

Condition 244

Solution 245

Regulatory information

United States (FCC) 247

OEM labeling requirements 247

FCC notices 247

FCC-approved antennas 248

RF exposure 248

FCC publication 996369 related information 249 Innovation, Science and Economic Development Canada (ISED) 250

Labeling requirements 250

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 13

RF Exposure 250 CE mark (Europe) 251

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 14

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

The XBee Smart Modem provides OEMs with a simple way to integrate low-power cellular connectivity into their devices.

Features include:

n FCC certified and carrier end-device certified

n Excellent coverage and building penetration

n Manage and configure with XCTU and Digi Remote Manager®

n Available with Digi provided SIM cards and data plans

n Digital I/O support

n Analog input support

n API and Transparent mode

n Command mode

n Bypass to the raw cellular modem

n SMS: Some carriers do not support SMS on LTE-M and/or NB-IoT. Check with your carrier for

details.

n TCP/UDP (up to six sockets)

n TLS (up to six sockets)

n Incoming connections

n MicroPython

l On-module programmability to add local intelligence

l Many examples in the Digi MicroPython Programming Guide

l AT commands for managing run-time behavior

n Low power modes

n LTE power save mode (PSM)

n Deep sleep mode

n Pin sleep support

n Cyclic sleep support

n Airplane mode support

n Digi TrustFence secure boot

n Multi-network capability (Verizon, AT&T)

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 15

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide Applicable firmware and hardware

Applicable firmware and hardware

This manual supports the following firmware:

n 114xx

It supports the following hardware:

n XB3-C-A2-UT-xxx

SIM cards

The XBee Smart Modem requires a 4FF (Nano) size SIM card. The SIM interface supports both 1.8 V and 3 V SIM types.

NB-IoT network

NB-IoT network is supported by XBee3 Cellular. Note the following:

n NB-IoT does not support roaming. You cannot roam between networks.

n For NB-IoT, TCP support is dependent on the network. Contact your network provider for

details.

n For NB-IoT, SMSsupport is dependent on the network. Contact your network provider for

details.

n Digi Remote Manager® requires TCPand will not work with NB-IoT unless the network

supports TCP.

n The SIM card in the device determines whether the device supports NB-IoT, LTE-M, or both.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 16

Get 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.

You should perform all of the steps below in the order shown.

1. Identify the kit contents

2. Acquire a SIM card

3. Connect the hardware

4. Review the development board

5. Set up cellular service

6. Configure and update your XBee

7. Use one of the following methods to verify your cellular connection:

n Connect to the Echo server

n Connect to the ELIZA server

n Connect to the Daytime server

Optional steps

You can review the information in these steps for more XBee connection examples and examples of how to use MicroPython.

1. Review additional connection examples to help you learn how to use the device. See XBee

connection examples.

2. Review introductory MicroPython examples. You can use MicroPython to enhance the

intelligence of the XBee to enable you to do edge-computing by adding business logic in MicroPython, rather than using external components.

n Example: hello world

n Example: turn on an LED

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 17

Get started with the XBee Smart Modem Development Kit Identify the kit contents

Identify the kit contents

The Developer's kit includes the following:

One XBIB-U-DEV board

One 12 V power supply

One cellular antenna with U.FL connector

One Bluetooth Low Energy (BLE) antenna

One USB cable

One XBee Smart Modem

Note The XBee Smart Modem comes

attached to the board in ESDwrap.

One SIMcard

Note NB-IoT kits (Digi product number

XK3-C-N1-UT-E) do not include a SIM card. Contact your NB-IoT mobile carrier provider to obtain a SIM card and service. See Acquire a SIM card.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 18

Get started with the XBee Smart Modem Development Kit Acquire a SIM card

Acquire a SIM card

NB-IoT kits (Digi product number XK3-C-N1-UT-E) do not include a SIM card. The sections below explain how to purchase an NB-IoT SIMcard in the US and Europe.

UScustomers

In the US, Digi XBee3® Cellular LTE-M/NB-IoT works with AT&T, Verizon, and. T-Mobile. You must purchase a SIM card before you can connect the hardware. Contact Digi Sales at

www.digi.com/contactus for information about obtaining a SIM card and activating cellular service.

After you have purchased your SIMcard, you must get the APN from the carrier. You will need this information when you get service. See Configure your module for cellular connectivity.

The APN for NB-IoT on T-Mobile may be "iot.nb". You should confirm the APN when you set up service. You can contact Digi Sales at www.digi.com/contactus for information about obtaining NB-IoT service.

European customers

If you are using the NB-IoT European kit, you must purchase a SIM card before you can connect the hardware. Contact your NB-IoT mobile carrier provider to obtain a SIM card and service.

n Vodafone: www.vodafone.com

n Deutsche Telekom: www.telekom.com/en

After you have purchased your SIMcard, you can get the APN (if needed by your carrier), network bands, and supported channels from the carrier. You will need this information when configuring the device from the SIM card and service you have selected. See Configure your module for cellular

connectivity.

Note Some carriers in Europe do not use the APN with NB-IoT.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 19

Get started with the XBee Smart Modem Development Kit Connect the hardware

Connect the hardware

1. The XBee Smart Modem should already be plugged into the XBIB-U-DEV board.

2. If a SIM card is included with the kit, the card is inserted into the XBee Smart Modem. If a SIM

card is not included, install the SIMcard into the XBee Smart Modem before attaching the XBee device to the board.

Note NB-IoT kits (Digi product number XK3-C-N1-UT-E) do not include a SIM card. Contact your

NB-IoT mobile carrier provider to obtain a SIM card and service. See Acquire a SIM card.

WARNING! Never insert or remove the SIM card while the device is powered!

3. Attach the XBee device to the board.

4. Connect the antennas.

a. Connect the cellular antenna.

b. Connect the BLE antenna if you are using BLE functionality. If you are not, you do

not have to connect the BLEantenna.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 20

Get started with the XBee Smart Modem Development Kit Connect the hardware

Note Align the U.FL connectors carefully, then firmly press 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.

5. Plug the 12 V power supply to the power jack on the development board. The LED indicator

blinks when the board is powered.

6. 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. If you have trouble downloading the USB driver, see Other possible issues.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 21

Get started with the XBee Smart Modem Development Kit XBIB-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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 22

Get started with the XBee Smart Modem Development Kit XBIB-U-DEV reference

Number Item Description

1 Programmingheader Header used to program XBee programmable devices.

2 Self power module

Advanced users only—voids the warranty. Depopulate R31 to power the device using V+ and GND from J2 and J5. You can connect sense lines to S+ and S- for sensing power supplies.

CAUTION: Voltage is not regulated. Applying the incorrect

voltage can cause fire and serious injury.

3 Current testing Depopulating R31 allows a current probe to be inserted across P6

terminals. The current though P6/R31 powers the device only. Other supporting circuitry is powered by a different trace.

4 Loopback jumper Populating P8 with a loopback jumper causes serial transmissions

both from the device and from the USB to loopback.

5 DC barrel plug: 6-20V Greater than 500 mA loads require a DC supply for correct

operation. Plug in the external power supply prior to the USB connector to ensure that proper USB communications are not interrupted.

6 LED indicator

Yellow: Modem sending serial/UART data to host. Green: Modem receiving serial/UART data from host. Red: Associate.

7 USB Connects to your computer.

8 RSSI indicator

See RSSI PWM. On the XBIB-U, more lights are better.

9 User buttons Connected to DIO lines for user implementation.

10 Reset button Press the reset button to reset the device to the default

configuration.

11 SPI power Connect to the power board from 3.3 V.

12 SPI Only used for surface-mount devices.

13 Indicator LEDs

DS5: ON/SLEEP DS2: DIO12, the LED illuminates when driven low. DS3: DIO11, the LED illuminates when driven low. DS4: DIO4, the LED illuminates when driven low.

14 Through-hole XBee

sockets

Connects the Digi XBee3® Cellular LTE-M/NB-IoT modem to the XBee USB development board.

15 20-pin header Maps to standard through-hole XBee pins. Male, Samtec header,

part number: TSW-110-26-L-D. 2.54 mm / .100" pitch and row spacing.

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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 23

Get started with the XBee Smart Modem Development Kit XBIB-CU-TH reference

XBIB-CU-TH reference

This picture shows the XBee-CU-TH development board and the table that follows explains the callouts in the picture.

Note This module is sold separately.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 24

Get started with the XBee Smart Modem Development Kit XBIB-CU-TH reference

Number Item Description

1 Secondary USB

(USB MICRO B) and DIP Switch

2 Current

Measure

3 Battery

Connector

Secondary USB Connector for direct programming of modules on some XBee units. Flip the Dip switches to the right for I2C access to the board; flip Dip switches to the left to disable I2C access to the board. The USB_P and USB_N lines are always connected to the XBee, regardless of Dip switch setting. This USB port is not designed to power the module or the board. Do not plug in a USB cable here unless the board is already being powered through the main USB-C connector. Do not attach a USB cable here if the Dip switches are pushed to the right.

WARNING! Direct input of USB lines into XBee units or I2C lines not designed to handle 5V can result in the destruction of the XBee or I2C components. Could cause fire or serious injury. Do not plug in a USB cable here if the XBee device is not designed for it and do not plug in a USB cable here if the Dip switches are pushed to the right.

Large switch controls whether current measure mode is active or inactive. When inactive, current can freely flow to the VCC pin of the XBee. When active, the VCC pin of the XBee is disconnected from the 3.3 V line on the development board. This allows current measurement to be conducted by attaching a current meter across the jumper P10.

If desired, a battery can be attached to provide power to the development board. The voltage can range from 2 V to 5 V. The positive terminal is on the left. If the USB-C connector is connected to a computer, the power will be provided through the USB-C connector and not the battery connector.

4 USB-C

Connector

5 LED indicator Red: UART DOUT (modem sending serial/UART data to host)

6 User Buttons Comm DIO0 Button connects the Commissioning/DIO0 pin on the XBee

7 Breakout

Connector

Connects to your computer and provides the power for the development board. This is connected to a USB to UART conversion chip that has the five UART lines passed to the XBee. The UART Dip Switch can be used to disconnect these UART lines from the XBee.

Note Requires USB 3.0 to supply required current.

Green: UART DIN (modem receiving serial/UART data from host) White: ON/SLP/DIO9 Blue: Connection Status/DIO5 Yellow: RSSI/PWM0/DIO10

Connector through to a 10 Ω resistor to GND when pressed.

RESET Button Connects to the RESET pin on the XBee Connector to GND when pressed.

This 40 pin connector can be used to connect to various XBee pins as shown on the silkscreen on the bottom of the board.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 25

Get started with the XBee Smart Modem Development Kit XBIB-CU-TH reference

Number Item Description

8 UART Dip

Switch

9 Grove

Connector

10 Temp/Humidity

Sensor

11 XBee Socket This is the socket for the XBee (TH form factor).

12 XBee Test

Point Pins

This dip switch allows the user to disconnect any of the primary UART lines on the XBee from the USB to UART conversion chip. This allows for testing on the primary UART lines without the USB to UART conversion chip interfering. Push Dip switches to the right to disconnect the USB to UART conversion chip from the XBee.

This connector can be used to attach I2C enabled devices to the development board. Note that I2C needs to be available on the XBee in the board for this functionality to be used. Pin 1: I2C_CLK/XBee DIO1 Pin2: I2C_SDA/XBee DIO11 Pin3: VCC Pin4: GND

This as a Texas Instruments HDC1080 temperature and humidity sensor. This part is accessible through I2C. Be sure that the XBee that is inserted into the development board has I2C if access to this sensor is desired.

Allows easy access for probes for all 20 XBee TH pins. Pin 1 is shorted to Pin 1 on the XBee and so on.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 26

Get started with the XBee Smart Modem Development Kit XBIB-C-GPS reference

XBIB-C-GPS reference

This picture shows the XBIB-C-GPS module and the table that follows explains the callouts in the picture.

Note This module is sold separately. You must also have purchased an XBIB-CU-TH development

board.

Note For a demo of how to use MicroPython to parse some of the GPS NMEA sentences from the

UART, print them and report them to Digi Remote Manager, see Run the MicroPython GPSdemo.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 27

Get started with the XBee Smart Modem Development Kit Interface with the XBIB-C-GPS module

Number Item Description

1 40-pin

header

2 GPS

unit

This header is used to connect the XBIB-C-GPS board to a compatible XBIB development board. Insert the XBIB-C-GPS module slowly with alternating pressure on the upper and lower parts of the connector. If added or removed improperly, the pins on the attached board could bend out of shape.

This is the CAM-M8Q-0-10 module made by u-blox. This is what makes the GPS measurements. Proper orientation is with the board laying completely flat, with the module facing towards the sky.

Interface with the XBIB-C-GPS module

The XBee Smart Modem can interface with the XBIB-C-GPS board through the large 40-pin header. This header is designed to fit into XBIB-C development board. This allows the XBee Smart Modem in the XBIB-C board to communicate with the XBIB-C-GPS board—provided the XBee device used has MicroPython capabilities (see this link to determine which devices have MicroPython capabilities). There are two ways to interface with the XBIB-C-GPS board: through the host board’s Secondary UART or through the I2C compliant lines.

The following picture shows a typical setup:

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 28

Get started with the XBee Smart Modem Development Kit Interface with the XBIB-C-GPS module

I2C communication

There are two I2C lines connected to the host board through the 40-pin header, SCL and SDA. I2C communication is performed over an I2C-compliant Display Data Channel. The XBIB-C-GPS module operates in slave mode. The maximum frequency of the SCL line is 400 kHz. To access data through the I2C lines, the data must be queried by the connected XBee Smart Modem.

For more information about I2C Operation see the I2C section of the Digi Micro Python Programming

Guide.

For more information on the operation of the XBIB-C-GPS board see the CAM-M8 datasheet. Other CAM-M8 documentation is located here.

UART communication

There are two UART pins connected from the XBIB-C-GPS to the host board by the 40-pin header: RX and TX. By default, the UART on the XBIB-C-GPS board is active and sends GPS readings to the connected device’s secondary UART pins. Readings are transmitted once every second. The baud rate of the UART is 9600 baud.

For more information about using Micro Python to communicate to the XBIB-C-GPS module, see Class

UART.

Run the MicroPython GPSdemo

The Digi MicroPython github repository contains a GPS demo program that parses some of the GPS NMEA sentences from the UART, prints them and also reports them to Digi Remote Manager.

Note If you are unfamiliar with MicroPython on XBee you should first run some of the tutorials earlier

in this manual to familiarize yourself with the environment. See Get started with MicroPython. For more detailed information, refer to the Digi MicroPython Programming Guide.

Step 1: Create a Remote Manager developer account

You must have a Remote Manager developer account to be able to use this program. Make sure you know the user name and password for this account.

If you don't currently have a Remote Manager developer account, you can create a free developer

account.

Step 2: Download or clone the XBee MicroPython repository

1. Navigate to: https://github.com/digidotcom/xbee-micropython/

2. Click Clone or download.

3. You must either clone or download a zip file of the repository. You can use either method.

n Clone: If you are familiar with GIT, follow the standard GITprocess to clone the

repository.

n Download

a. Click Download zip to download a zip file of the repository to the download

folder of your choosing.

b. Extract the repository to a location of your choosing on your hard drive.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 29

Get started with the XBee Smart Modem Development Kit Cellular service

Step 3: Edit the MicroPython file

1. Navigate to the location of the repository zip file that you created in Step 2.

2. Navigate to: samples/gps

3. Open the MicroPython file: gpsdemo1.py

4. Using the editor of your choice, edit the MicroPython file. At the top of the file, enter the user name and password for your Remote Manager developer account. The correct location is indicated in the comments in the file.

Step 4: Run the program

1. Rename the file you edited in Step 3 from gpsdemo1.py to main.py.

2. Copy the renamed file onto your device's root filesystem directory.

3. Copy the following three modules from the locations specified below into your device's /lib directory:

n From the /lib directory of the Digi xbee-micropython repository: urequest.py and

remotemanager.py

n From the /lib/sensor directory of the Digi xbee-micropython repository: hdc1080.py

Note These modules are required to be able to run the gpsdemo1.py.

4. Open XCTU and use the MicroPython Terminal to run the demo.

5. Type <CTRL>-R from the MicroPython prompt to run the code.

Cellular service

Digi now offers Cellular Bundled Service plans. This service includes pre-configured cellular data options that are ideal for IoT applications, bundled together with Digi Remote Manager for customers who want to remotely monitor and manage their devices.

Note The Digi Cellular Bundled Service plan is not offered for NB-IoT. Contact Digi for more

information about Digi Cellular Bundled Service.

To learn more, or obtain the plan that is right for your needs, contact us:

n By phone: 1-877-890-4014 (USA/toll free) or +1-952-912-3456 (International). Select the

Wireless Plan Support or Activation option in the menu.

n By email: Data.Plan.QuoteDesk@digi.com.

WARNING! Digi Remote Manager is enabled by default on the XBee device. You should configure the device to avoid excess cellular data usage. For more information, see

Configure Remote Manager keepalive interval.

The XBee Cellular kit includes six months of free cellular service. Six months of free cellular service assumes a rate of 5 MB/month. If you exceed a limit of 30 MB during the six month period your SIM will be deactivated.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 30

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

Note The NB-IoT kit does not include free cellular service. Note that carriers put limits on your data

service. Exceeding the allotted usage may result in automatic suspension or termination of service.

Configure and update your XBee

You should update your XBee to the latest firmware available for the device.

XBee Configuration and Test Utility (XCTU) is a multi-platform program developed by Digi 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.

Update the device firmware

You can use XCTU to update the firmware.

1. To use XCTU, you may need to install FTDI Virtual COMport (VCP)drivers onto your computer. Click here to download the drivers for your operating system.

2. Upgrade XCTU to version 6.4.2 or later. This step is required.

3. You must add a device to XCTU before you can update the device's firmware from XCTU.

4. Update to the latest firmware from XCTU.

Configure your module for cellular connectivity

You should configure your module for cellular connectivity and set the APN.

Check for cellular registration and connection

You should verify proper cellular network registration and address assignment.

Update the u-blox module

You can check the version of your cellular module using ATMV.

n Update an XBee module from A2.00 to A2.01 using APImode

n Update an XBee module from A2.00 to A2.01 using FOTA

Add a device

These instructions show you how to add the XBee Smart Modem to XCTU.

If XCTU does not find your serial port, see Cannot find the serial port for the device and Enable Virtual

COM port (VCP) on the driver.

Launch XCTU .

Note XCTU's Update the radio module firmware dialog box may open and will not allow you

to continue until you click Update or Cancel on the dialog.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 31

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

2. Click Help > Check for XCTUUpdates to ensure you are using the latest version of XCTU.

Click the Discover radio modules button in the upper left side of the XCTU screen.

4. In the Discover radio devices dialog, select the serial ports where you want to look for XBee modules, and click Next.

5. In the Set port parameters window, maintain the default values and click Finish.

6. As XCTU locates radio modules, they appear in the Discovering radio modules dialog box.

7. Select the device(s) you want to add and click Add selected devices.

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.

Update to the latest firmware from XCTU

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.

WARNING! Version 1140F reorganizes the product's flash memory and upgrades the product to version 11410. You cannot downgrade to a version earlier than 11410 after installing 1140F/11410. You also need to use XCTU version 6.4.2 or later.

Note If you have already updated the firmware in a previous step, this process is not necessary.

Launch XCTU .

Click the Configuration working modes button .

3. Select a local XBee module from the Radio Modules list.

Click the Update firmware button to ensure you have the most current firmware.

The Update firmware dialog displays the available and compatible firmware for the selected XBee module.

5. Make sure you check the Force the module to maintain its current configuration box and then click Update.

6. Select the product family of the XBee module, the function set, and the latest firmware version.

7. 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.

Configure your module for cellular connectivity

Note LTE-M is configured by default. You can skip this section if you are using LTE-M.

If you are using an NB-IoT kit, you must configure the device to use NB-IoT.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 32

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

UScustomers

Note Some carriers require an APN. If the carrier does not require an APN, you should not change the

APN from the default

Click the Configuration working modes button

2. Select an XBee module from the Radio Modules list.

3. Set the APN using the AN command. You should get the APN from your carrier when you purchased your SIMcard. See Acquire a SIM card.

4. To set the APN, in the AN field, type the APN value from your carrier and click the Write button

European customers

Note Some carriers require an APN. If the carrier does not require an APN, you should not change the

APN from the default

Click the Configuration working modes button .

2. Select an XBee module from the Radio Modules list.

3. Set the APN using the AN command. You should get the APN from your carrier when you purchased your SIMcard. See Acquire a SIM card.

To set the APN, in the AN field, type the APN value from your carrier and click the Write button

4. Set the N# parameter to 3. In the N# field, select NB-IoT Only [3] and click the Write button

5. Enable the bands. The bands are specified as a bit mask given as a hexadecimal value.

To enable bands 8 and 20, in the BNfield, enter 80080 and click the Write button .

To set the CP, in the CP field, select No Profile (1) and click the Write button .

7. Reset the module with either the reset button or issue the FR command.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 33

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

8. Wait for a connection. You may wait for up to 5-6 minutes.

n If you have a connection: This process is complete. The LED on the development board

blinks when the XBee Smart Modem is registered to the cellular network. See Check for

cellular registration and connection.

n If you do not have a connection: If the LEDremains solid, registration has not

occurred properly.

a. Repeatsteps 1-5 to make sure you have correctly configured NB-IoT.

b. Ifyou still do not have a connection, contact your carrier to confirm that the

carrier has correctly configured the service.

l If the carrier makes a change to the service, reset the module and wait

5-6 minutes.

l If the carrier does not make a change to the service, then contact Digi

support.

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 Associate LED functionality. If the LEDremains solid, registration has not occurred properly.

Registration typically takes 5 - 6 minutes the first time a device is connected to the network.

Note Make sure you are in an area with adequate cellular network reception or the XBee Smart

Modem will not make the connection.

Note Check the antenna connections if the device has trouble connecting to the network.

In addition to the LED confirmation, you can check the AT commands below in XCTU to check the registration and connection.

To view these commands:

1. You must have previously added at least one device. See Add a device.

2. Open XCTU.

Click the Configuration working mode button.

4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for that device.

Note To search for an ATcommand in XCTU, use the search box .

The relevant commands are:

n AI (Association Indication) reads 0 when the device successfully registers to the cellular

network. If it reads 23 it is connecting to the Internet; 22 means it is registering to the cellular network.

n MY (Module IP Address) should display a valid IPaddress. If it reads 0.0.0.0, it has not

registered yet.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 34

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

Note To read a command's value, click the Read button next to the command.

Update an XBee module from A2.00 to A2.01 using APImode

You can update an XBee Cellular LTE-M/NB-IoT module from A2.00 to A2.01 using APImode and the script described in this section.

Prerequisites

n Each module must be inserted into a development board such as the Digi XBIB-CU-TH,

powered on, and connected to the PC.

n Each module must be running firmware 11412 or later. For update instructions, see Update to

the latest firmware from XCTU.

n Each module must have an active, registered SIM card installed.

n Each module must be configured in the default operating mode:

l ATAM set to 0 to disable airplane mode

l ATSM set to 0 to disable sleep

l ATP0 set to 0 and ATP1 set to 0 to disable direct USB.

If any of these settings needed to be changed, issue ATWR to save changes.

n Each module must be configured to use unescaped API mode: ATAP set to 1.

n Each module must be configured to use the same baud rate on the UART interface (same ATBD

value).

n The machine that will be performing the update must have Python 3.6 or higher installed and

the script must be run using Python 3.

n The machine that will be performing the update must have visibility to an HTTP server hosting

the files.

n The script dependencies must be satisfied by running pip install -r

requirements.txt in the directory containing the script. Creating and using a Python virtual environment with the virtualenv command is recommended as a best practice.

Script usage

The arguments and default values for the script are shown below. By default, Digi hosts the update files on a public FTP server and the script attempts to apply the appropriate update files based on intelligence built into the script. The optional arguments should only rarely need to be changed and generally only if the Digi FTP server is not accessible on a private APN, or by direction of Digi Technical Support.

usage: update.py [-h] [--baud <BAUD>] [--type {auto,es2,ip}]

[--remote BASE_URL | --local BASE_DIRECTORY] [-f FILE] [-v] <PORT> [<PORT> ...] [<BAUD>]

Update the u-blox SARA-R410M cellular module used by the Digi XBee3 Cellular LTE-M/NB-IoT device to firmware version L0.00.00.05.06,A.02.01 using a serial link to one or XBee3 Cellular devices. Script version: 1.0

optional arguments:

-h, --help show this help message and exit

Serial port:

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 35

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

Arguments which control how the script interfaces with the XBee

<PORT> COM port (or /dev/ttyUSBx device) for the XBee3

Cellular device. Can be specified multiple times to update multiple devices.

<BAUD> Current baud rate of the XBee3 Cellular device(s)

(default: 9600)

Firmware update:

Arguments which control the firmware update process

--type {auto,es2,ip} Type of modules (default: auto)

--remote BASE_URL HTTP server base path where update files are located (default: http://ftp1.digi.com/support/ublox)

--local BASE_DIRECTORY Local directory where update files are located (overrides --remote) (default: None)

-f FILE, --file FILE Apply only this one file (default: None)

Other arguments:

-v, --verbose Also emit log messages about communications with the XBee (default: False)

For additional help, see the XBee3 Cellular LTE-M/NB-IoT user guide or contact Digi Technical Support at <tech.support@digi.com>.

Example

Examples of usage:

C:\Users\admin\over-thewire>C:\Users\admin\AppData\Local\Programs\Python\Python37-32\python.exe update.py COM17

Run the update script

The serial port (COM port or /dev/ttyX device) values for the modules you want to update are entered as arguments when you run the script. See Script usage for information about the arguments.

1. Download the script.

a. Go to the Digi XBee3 Cellular LTE-M support page.

b. Scroll down to the Firmware Updates section.

c. Locate and click u-blox Over the Wire Update Script to download the zip file:

over-the-wire.zip.

d. Unzip the downloaded file.

2. Go to a command line.

3. Navigate to the directory containing the script.

4. Run pip install -r requirements.txt in the directory containing the script.

5. Verify that you are in the same directory as the script.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 36

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

6. Run the script. Type: python update.py <arguments>

where <arguments> includes the serial port (COM# port or /dev/tty# device, where # is the port number) and any optional parameters needed for the environment. For more information, see Script usage.

Windows example

C:\Users\admin\over-thewire>C:\Users\admin\AppData\Local\Programs\Python\Python3732\python.exe update.py COM17

Linux examples

$ python update.py /dev/tty5

$ python update.py COM10 --baud=115200

7. Press Enter to begin running the script. For a detailed description of how the update script works, see How the script works.

8. When complete, a digi-update.log text file is created, which contains a copy of the log messages emitted to the terminal while the script was running.

9. A successful update appears as:

2019-06-27 16:06:28,479 update.py: INFO: Reading cellular component version string (ATMV)... 2019-06-27 16:06:28,501 update.py: INFO: Update successful. New MV value: L0.0.00.00.05.06,A.02.01 2019-06-27 16:06:28,502 update.py: INFO: Cellular component update successful. 2019-06-27 16:06:28,503 update.py: INFO: Restoring previous baud rate and RTS/CTS configuration. 2019-06-27 16:06:28,743 update.py: INFO: Completed update of XBee3 Cellular device with IMEI 352753090861053 2019-06-27 16:06:28,744 update.py: INFO: Updates complete. This script should automatically exit in a moment. If it does not exit, use Ctrl-C to stop the script.

How the script works

The behavior of the update script is detailed below, so that you can implement the same behavior in a different programming language, or as part of one's host application.

1. Establish communications with the XBee3 Cellular LTE-M/NB-IoT modem. The Digi XBee Python library does this by querying the ATAP parameter, and observing that a response frame is generated.

2. Query the firmware version of the XBee3 Cellular modem's cellular component, using ATMV.

n If the value is not "L0.0.00.00.05.06,A.02.00", this update does not apply.

n If the value is "L0.00.00.05.06,A.02.01", this update is not necessary, as the cellular

component is already running the expected firmware.

3. Query the IMEI of the XBee3 Cellular modem. This can be done by reading the ATIM value, or by concatenating ATSH and ATSL.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 37

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

4. Look for the IMEI in the es2-imeis.txt file.

n If the IMEI is present, the relevant update files are in the 2stg-upd-for-ES2

directory.

n If the IMEI is not present, the relevant update files are in the 2stg-upd-for-IP

directory.

5. For each number in the sequence 1,2,3:

a. Download the relevant "stage 1" update file from Digi's FTP server, using HTTP. For

example, http://ftp1.digi.com/support/ublox/2stg-upd-for-

IP/stg1-pkg1-5.6A2.00_to_5.6A2.01.pkg. The file name is of the format stg1-pkg<NUMBER>-5.6A2.00_to_5.6A2.01.pkg, where <NUMBER> is

replaced with either 1, 2, or 3.

b. Transmit the update package file contents into the XBee3 Cellular modem using

Firmware Update API frames. For a description of this process, see Perform a

cellular component firmware update.

c. Wait approximately a minute for the response to the last API frame.

n If this update package was successful (response to the last frame indicates

success), move on to step 6.

n If this update package was not successful (response to the last frame

indicates Internal Error), repeat for the next package number. If this was package number 3, stop and contact Digi Technical Support.

6. Download the relevant "stage 2" update file from Digi's FTP server, using HTTP. For example,

http://ftp1.digi.com/support/ublox/2stg-upd-for-IP/stg2-pkg-

5.6A2.00_to_5.6A2.01.pkg. The file name is stg2-pkg-5.6A2.00_to_

5.6A2.01.pkg.

7. Transmit the update package file contents into the XBee3 Cellular modem using Firmware Update API frames. For a description of this process, see Perform a cellular component

firmware update.

8. Wait approximately 10 minutes for the response to the last API frame.

9. If the update was not successful (response to the last frame indicates "internal error" or other error), try the update again with this flag: --type=ip

10. If the update was still not successful (response to the last frame indicates "internal error"), contact Digi Technical Support at tech.support@digi.com.

11. Query the firmware version of the XBee3 Cellular modem's cellular component again, using

ATMV. The value should now be "L0.0.00.00.05.06,A.02.01".

Update an XBee module from A2.00 to A2.01 using FOTA

You can update an XBee Cellular LTE-M/NB-IoT module from A2.00 to A2.01 using FOTA and the script described in this section.

Prerequisites

n You will need a list of the IMEI values for all XBee Cellular LTE-M/NB-IoT modules to be updated.

n Each module must be running firmware 11412 or later. For update instructions, see Update to

the latest firmware from XCTU.

n Each module must have an active, registered SIM card installed.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 38

Get started with the XBee Smart Modem Development Kit Configure and update your XBee

n Each module must be configured to be connected to Remote Manager and to reconnect when

connection is lost. For instructions, see Restore persistent connection to a remote XBee.

n Each module must have visibility to an FTP server hosting the files.

n The machine that will be performing the update must have Python 3.6 or higher installed and

the script must be run using Python 3.

n The script dependencies must be satisfied by running pip install -r

requirements.txt in the directory containing the script. Creating and using a Python virtual environment with the virtualenv command is recommended as a best practice.

Script usage

usage: fota.py [-h] [--type {auto,es2,ip}] [--ftp_server FTP_SERVER]

[--ftp_port FTP_PORT] [--ftp_user FTP_USER] [--ftp_password FTP_PASSWORD] [--ftp_basedir FTP_BASEDIR]

<IMEI> [<IMEI> ...] Perform Over The Air Firmware update (FOTA) on XBee Cellular LTE-M/NB-IoT positional arguments:

<IMEI> IMEI of device on which to perform update.

optional arguments:

-h, --help show this help message and exit

--type {auto,es2,ip} Type of modules (default: auto)

--ftp_server FTP_SERVER FTP server (default: ftp1.digi.com)

--ftp_port FTP_PORT FTP port (default: 21)

--ftp_user FTP_USER FTP username (default: anonymous)

--ftp_password FTP_PASSWORD FTP password (default: fota@digi.com)

--ftp_basedir FTP_BASEDIR FTP base directory (default: /support/ublox)

Run the update script

The IMEI values for the modules you want to update are entered as arguments when you run the script. See Script usage for information about the arguments.

1. Download the script.

a. Go to the Digi XBee3 Cellular LTE-M support page.

b. Scroll down to the Firmware Updates section.

c. Locate and click u-blox Module Over the Air Update Script to download the zip

file: over-the-air.zip.

d. Unzip the downloaded file.

2. Go to a command line and navigate to the directory containing the script.

3. Run pip install -r requirements.txt in the directory containing the script.

4. Run the script. Type: python fota.py <arguments>

where <arguments> includes the IMEIs and any optional parameters needed for the environment. For more information, see Script usage.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 39

Get started with the XBee Smart Modem Development Kit XBee bootloader

5. Press Enter. You will be prompted for your Remote Manager user name and password.

6. After you have entered the user name and password, the script connects to Remote Manager. For each device listed as an argument in the command line, the script performs the following items:

n Verifies connectivity to Remote Manager and the module configuration.

n Apples a sequence of updates to the module that are needed to perform the update to

A2.01.

n Verifies the final cellular component version.

7. When complete, a CSV is generated and named using this format: results<timestamp>.csv, where <timestamp> is the time of the run. The file lists each IMEI,

whether the update for that IMEI was successful, and any error message if the update failed.

8. A successful update appears as:

9. If the update was not successful (response to the last frame indicates "internal error" or other error), try the update again with this flag: --type=ip

10. If the update was still not successful (response to the last frame indicates "internal error"), contact Digi Technical Support at tech.support@digi.com.

XBee bootloader

XBee devices use a modified version of Ember’s bootloader. This bootloader version supports a custom entry mechanism that uses module pins DIN (pin 3), DTR / SLEEP_RQ (SLEEP_RQ), and RTS (pin 16).

To invoke the bootloader, do the following:

1. Set DTR/SLEEP_RQ low (TTL 0V) and RTS high.

2. Send a serial break to the DIN pin and power cycle or reset the module.

3. When the device powers up, set DTR/SLEEP_RQ and DIN to low (TTL 0V) and RTS should be high.

4. Terminate the serial break and send a carriage return at 115200 baud to the device.

5. If successful, the device sends the Ember bootloader menu out the DOUT pin at 115200 baud.

6. Commands can be sent to the bootloader at 115200 b/s.

Note Disable hardware flow control when entering and communicating with the XBee3 cellular

bootloader.

All serial communications with the module use 8 data bits, no parity bit, and 1 stop bit.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 40

Get started with the XBee Smart Modem Development Kit XBee bootloader

You can update firmware on the XBee Smart Modem serially. This is done by invoking the bootloader and transferring the firmware image using XMODEM.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 41

XBee connection examples

The following examples provide some additional scenarios you can try to get familiar with the XBee Smart Modem. These examples are focused on inter-operating with a host processor to drive the XBee.

If you are interested in using the intelligence built into the XBee, see Get started with MicroPython.

Note Some carriers restrict your internet access. If access is restricted, running some of these

examples may not be possible. Check with your carrier provider to determine whether internet access is restricted.

Connect to the Echo server 42 Connect to the ELIZA server 44 Connect to the Daytime server 46 Perform a (GET) HTTP request 48 Get started with CoAP 50 Connect to a TCP/IP address 54 Get started with MQTT 55 Debugging 63 Software libraries 63

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 42

XBee connection examples Connect to the Echo server

Connect to the Echo server

This server echoes back the messages you type.

You may use TCP or UDP, depending on the protocols supported by your network carrier.

Note For help with debugging, see Debugging.

The following table explains the AT commands that you use in this example.

At command Value Description

IP (IP

Protocol)

(Text

Delimiter)

(Destination Address)

(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.

1 TCP: Set the expected transmission mode to TCP communications.

0 UDP: Set the expected transmission mode to UDP communications.

D (0x0D)

52.43.121.77 The target IPaddress of the echo server.

0x2329 TCP: The target port number of the TCP echo server.

0x2711

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 0 to disable text delimiter checking. Set to D for a carriage return.

Note Some carriers may require whitelisted IP addresses. If this IP is

not whitelisted by your carrier you will not be able to run this example.

This port in decimal is 9001.

UDP: The target port number of the UDP echo server. This port in decimal is 10001.

Click the Configuration working mode button.

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 .

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.

Note XCTU does not follow the standard hexadecimal numbering convention. The leading 0x is

not needed in XCTU.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 43

XBee connection examples Connect to the Echo server

Click the Consoles working mode button on the toolbar to open a serial console to the device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.

10.

Click the Open button to open a serial connection to the device.

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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 44

XBee connection examples Connect to the ELIZA server

Connect to the ELIZA server

You can use the XBee Smart Modem to chat with the ELIZA Therapist Bot. ELIZAis an artificial intelligence (AI) bot that emulates a therapist and can perform simple conversations.

Note For help with debugging, see Debugging.

The following table explains the AT commands that you use in this example.

At command Value Description

IP (IP

Protocol)

(Destination Address)

(Destination Port)

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 mode button.

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 .

6. To enter the destination address of the ELIZATherapist Bot, 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 2328 and click the Write button.

1 Set the expected transmission mode to TCP communications.

52.43.121.77 The target IP address of the ELIZA server.

Note Some carriers may require whitelisted IP addresses. If this IP is

not whitelisted by your carrier you will not be able to run this example.

0x2328 The target port number of the ELIZA server.

Click the Consoles working mode button on the toolbar to open a serial console to the device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.

Click the Open button to open a serial connection to the device.

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 with the user's text in blue.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 45

XBee connection examples Connect to the ELIZA server

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 46

XBee connection examples Connect 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.

Note For help with debugging, see Debugging.

The following table explains the AT commands that you use in this example.

At command Value Description

IP (IP

Protocol)

(Destination Address)

(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 mode button.

4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for that device.

1 Set the expected transmission mode to TCP communications.

52.43.121.77 The target IP of the Daytime server.

Note Some carriers may require whitelisted IP addresses. If this IP is

not whitelisted by your carrier you will not be able to run this example.

0x232A The target port number of the Daytime server.

To switch to TCP communication, in the IP field, select 1 and click the Write button .

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 button on the toolbar to open a serial console to the device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.

10.

Click the Open button to open a serial connection to the device.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 47

XBee connection examples Connect to the Daytime server

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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 48

XBee connection examples Perform 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. HTTP is an application-layer protocol that runs over TCP. This example uses httpbin.org/ as the target website that responds to the HTTP request.

Note For help with debugging, see Debugging.

To perform a GETrequest:

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 mode button.

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 APfield, select 0 and click the Write button.

9. Wait for the AI (Association Indication) value to change to 0 (Connected to the Internet).

10.

Click the Consoles working mode button on the toolbar.

11.

From the AT console, click the Add new packet button in the Send packets dialog. The 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 input tab:

47 45 54 20 2F 69 70 20 48 54 54 50 2F 31 2E 31 0D 0A 48 6F 73 74 3A 20 68 74 74 70 62 69 6E 2E 6F 72 67 0D 0A 0D 0A

Note The HTTP protocol requires an empty line (a line with nothing preceding the CRLF) to terminate

the request.

15. Click Add packet.

16.

Click the Open button .

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 49

XBee connection examples Perform a (GET) HTTP request

17. Click Send selected packet.

18. A GETHTTP response from httpbin.org appears in the Console log.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 50

XBee connection examples Get 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:

Term Meaning

Method COAP'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.

URI URI is a string of characters that identifies a resource served at the server.

Token Atoken is an identifier of a message. The client uses the token to verify if the received

message is the correct response to its query.

Payload The message payload is associated with the POST and PUT methods. It specifies the

data to be posted or put to the URI resource.

MessageID 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-M/NB-IoT Global Smart Modem User Guide

Page 51

XBee connection examples Get started with CoAP

The following table describes the fields in the GETrequest.

Field HEX Bits Meaning

Ver 44 01 Version 01, which is mandatory here.

T 00 Type 0: confirmable.

TKL 0100 Token length: 4.

Code 01 000 00001 Code: 0.01, which indicates the GET method.

Message ID C4 09 2 Bytes equal

to hex at left

Token 74 65 73 74 4 Bytes equal

to hex at left

Option delta B7 1011 Delta option: 11 indicates the option data is Uri-Path.

Optionlength 0111 Delta length: 7 indicates there are 7 bytes of data

Option value 65 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 mode button.

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 UDPcommunication, in the IP field, select 0 and click the Write button .

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 DEfield, type 1633 and click the Write button.

8. To move into Transparent mode, in the APfield, 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 Read to get an update on the AI value.

Example: manually perform a CoAPrequest

Follow the steps in Configure the device prior to this example. This example performs the CoAP GETrequest:

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 52

XBee connection examples Get started with CoAP

n Method: GET

n URI: example

n Given message token: test

Click the Consoles working mode button on the toolbar to add a customized packet.

From the AT console, click the Add new packet button in the Send packets dialog. The 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 .

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: python.org/downloads/.

2. Download and install the CoAPthon library in the python environment from

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.

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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 53

XBee connection examples Get started with CoAP

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. XCTUprovides 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-M/NB-IoT Global Smart Modem User Guide

Page 54

XBee connection examples Connect 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.

Note You can use this example as a template for sending and receiving data to or from any

TCP/IPserver.

Note For help with debugging, see Debugging.

The following table explains the AT commands that you use in this example.

Command Value Description

IP (IP

Protocol)

(Destination IPAddress)

(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 mode button.

4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for that device.

In the IP field, select 1 and click the Write button .

6. In the DL field, type the <target IP address> and click the Write button. The target IP address is the IPaddress 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.

1 Set the expected transmission mode to TCPcommunication.

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.

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-M/NB-IoT Global Smart Modem User Guide

Page 55

XBee connection examples Get 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 MQTTexamples do not involve the XBee Smart Modem. They demonstrate using the MQTTlibraries 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 and update your XBee.

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:

Description Hex value

CONNECT packet fixed header

byte 1 Control packet type 0x10

byte 2 Remaining length 0x10

CONNECT packet variable header

Protocol name

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 56

XBee connection examples Get started with MQTT

Description Hex value

byte 1 Length MSB (0) 0x00

byte 2 Length LSB (4) 0x04

byte 3 (M) 0x4D

byte 4 (Q) 0x51

byte 5 (T) 0x54

byte 6 (T) 0x54

Protocol level

byte 7 Level (4) 0x04

Connect flags

byte 8

Keep alive

byte 9 Keep Alive MSB (0) 0X00

byte 10 Keep Alive LSB (60) 0X3C

Client ID

byte 11 Length MSB (0) 0x00

byte 12 Length 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:

Fieldname Description

ProtocolName 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

ProtocolLevel Refers to the version of MQTT in use, in this case a value of 4 indicates MQTT

version 3.1.1.

Connect Flags Indicate 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 Alive How often the client pings the broker to keep the connection alive; in this example

it is set to 60 seconds.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 57

XBee connection examples Get started with MQTT

Fieldname Description

Client ID The 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.

CONNECT Flag Bit(s) Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0

User name flag 0

Password flag 0

Will retain 0

Will QoS 0 0

Will flag 0

Clean session 1

Reserved 0

Send a connect packet

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 mode button.

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 APfield, set Transparent Mode to [0] if it is not already and click the Write button.

6. In the DL field, type the IP address or the fully qualified domain name of the broker you wish to use. This example uses test.mosquitto.org.

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.

Click the Consoles working mode button on the toolbar to open a serial console to the device. For instructions on using the Console, see the AT console topic in the XCTU User Guide.

10.

Click the Open button to open a serial connection to the device.

11.

From the AT console, click the Add new packet button in the Send packets dialog. The Add new packet dialog appears.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 58

XBee connection examples Get started with MQTT

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 table in Example: MQTT connect):

10 10 00 04 4D 51 54 54 04 02 00 3C 00 04 44 49 47 49

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:

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-

open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718081).

Example: send messages (publish) with MQTT

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)

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 59

XBee connection examples Get started with MQTT

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 topic digitest/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.

print("Message received-> " + msg.topic + " " + str(msg.payload)) #

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)

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 60

XBee connection examples Get started with MQTT

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:

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. """

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 61

XBee connection examples Get started with MQTT

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 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)))

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 62

XBee connection examples Get started with MQTT

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-M/NB-IoT Global Smart Modem User Guide

Page 63

XBee connection examples Debugging

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.

Debugging

If you experience problems with the settings in the examples, you can load the default settings in XCTU.

Note If you load the default settings, you will need to reapply any configuration settings that you have

previously made.

On the Configuration toolbar, click the Default button to load the default values 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.

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-M/NB-IoT Global Smart Modem User Guide

Page 64

Get started with MicroPython

This section provides an overview and simple examples of how to use MicroPython with the XBee Smart Modem. You can use MicroPython to enhance the intelligence of the XBee to enable you to do edge-computing by adding business logic in MicroPython, rather than using external components.

Note For in-depth information and more complex code examples, refer to the Digi MicroPython

Programming Guide.

About MicroPython 65 MicroPython on the XBee Smart Modem 65 Use XCTU to enter the MicroPython environment 65 Use the MicroPython Terminal in XCTU 66 Example: hello world 66 Example: turn on an LED 66 Example: debug the secondary UART 67 Exit MicroPython mode 68 Other terminal programs 68 Use picocom in Linux 70

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 65

Get started with MicroPython About 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 and update your XBee.

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.

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 and update your XBee 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. Set the device's baud rate to 115200 b/s, in the BD field select 115200 [7] or higher and click

the Write button . We recommend using flow control to avoid data loss, especially when pasting large amounts of code/text.

5. Put the XBee Smart Modem into MicroPython mode, in the APfield select MicroPython REPL

[4] and click the Write button .

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 66

Get started with MicroPython Use the MicroPython Terminal in XCTU

6. Note what COM port(s) the XBee Smart Modem is using, because you will need this information when you use terminal communication. The Radio Modules information panel lists the COM port in use.

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 menu and select MicroPython Terminal. The terminal opens.

2. Click Open. If you have not already added devices to XCTU:

a. In the Select the Serial/USB port area, click the COM port that the device uses.

b. 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.

4. Press Ctrl+B to get the MicroPython version banner and prompt.

You can now type or paste MicroPython commands at the >>> prompt.

Troubleshooting

If you receive No such port: 'Port is already in use by other applications.' in the MicroPython Terminal close any other console sessions open inside XCTU and close any other serial terminal

programs connected to the device, then retry the MicroPython connection in XCTU.

If the device seems unresponsive, try pressing Ctrl+C to end any running programs.

You can use the +++ escape sequence and look for an OK for confirmation that you have the correct baud rate.

Example: hello world

Before you begin, you must have previously added a device in XCTU. See Add a device.

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.

See Other terminal programs if you do not use the MicroPython Terminal in XCTU.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 67

Get started with MicroPython Example: debug the secondary UART

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: debug the secondary UART

This sample code is handy for debugging the secondary UART. It simply relays data between the primary and secondary UARTs.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 68

Get started with MicroPython Exit MicroPython mode

from machine import UART import sys, time

def uart_init():

u = UART(1) u.write('Testing from XBee\n') return u

def uart_relay(u):

while True:

uart_data = u.read(-1) if uart_data:

sys.stdout.buffer.write(uart_data) stdin_data = sys.stdin.buffer.read(-1) if stdin_data:

u.write(stdin_data)

time.sleep_ms(5)

u = uart_init() uart_relay(u)

You only need to call uart_init() once.

Call uart_relay() to pass data between the UARTs.

Send Ctrl-C to exit relay mode.

When done, call u.close() to close the secondary UART.

Exit MicroPython mode

To exit MicroPython mode:

In the XCTU MicroPython Terminal, click the green Close button .

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

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/npatefault/picocom.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 69

Get started with MicroPython Other terminal programs

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 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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 70

Get started with MicroPython Use picocom in Linux

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.

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.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 71

Get started with MicroPython Use picocom in Linux

Now you can type MicroPython commands at the >>> prompt.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 72

Get started with BLE

BLE (Bluetooth® Low Energy) is an RF protocol that enables you to connect your XBee device to another device. Both devices must have BLEenabled.

For example, you can use your cellphone to connect to and configure your XBee device.

Enable BLE on an XBee device

This process explains how to enable BLEon your XBee3 device and verify the connection.

1. Set up your XBee device, and make sure to connect the BLE antenna to the device. See Get

started with the XBee Smart Modem Development Kit.

2. Enable BLEand configure the BLEpassword using XCTU.

3. Get the Digi XBeeMobile phone application.

4. Connect with BLEand configure your XBee device.

Note The BLE protocol is disabled on the XBee device by default. You can create a custom factory

default configuration that ensures BLE is always enabled. See Custom configuration: Create a new

factory default.

Enable BLEand configure the BLEpassword using XCTU

Some of the latest XBee3 modules support Bluetooth Low Energy (BLE) as an extra interface for configuration. If you want to use this feature, you have to enable BLE. You must also enable security by setting a BLE password on the XBee device in order to connect, configure, or send data over BLE.

The BLE password is configured using XCTU. Make sure you have installed or updated XCTU to version

6.4.2. or later. Earlier versions of XCTU do not include the BLEconfiguration features. See Download

and install XCTU for installation instructions.

Before you begin, you should determine the password you want to use for BLEon the XBee device and store it in a secure place. Digi recommends a secure password of at least 8 characters and a random combination of letters, numbers, and special characters. Digi also recommends using a security management tool such as LastPass or Keepass for generating and storing passwords for many devices.

Note When you enter the BLEpassword in XCTU, the salt and verifier values are calculated as you set

your password. For more information on how these values are used in the authentication process, see

BLE Unlock API - 0x2C.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 73

Get started with BLE Get the Digi XBeeMobile phone application

Launch XCTU .

Switch to Configuration working mode .

3. Select a BLE compatible radio module from the device list.

4. In the Bluetooth Options section, select Enabled[1] from the BT Bluetooth Enable command drop-down.

Click the Write setting button . The Bluetooth authentication not set dialog appears.

Note If BLE has been previously configured, the Bluetooth authentication not set dialog does

not appear. If this happens, click Configure in the Bluetooth Options section to display the Configure Bluetooth Authentication dialog.

6. Click Configure in the dialog. The Configure Bluetooth Authentication dialog appears.

7. In the Password field, type the password for the device. As you type, the Salt and Verifier fields are automatically calculated and populated in the dialog as shown above. Make a note of the password, as this password is used when you connect to this XBee device via BLE using the Digi

XBee Mobile app.

8. Click OK to save the configuration.

Get the Digi XBeeMobile phone application

To see the nearby devices that have BLEenabled, you must get the free Digi XBee Mobile application from the iOS App Store or Google Play and downloaded to your phone.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 74

Get started with BLE Connect with BLEand configure your XBee device

1. On your phone, go to the App store.

2. Search for Digi XBee Mobile.

3. Download and install the application.

The Digi XBee Mobile application is compatible with the following operating systems and versions:

n Android 5.0 or higher

n iOS 11 or higher

Connect with BLEand configure your XBee device

You can use the Digi XBee Mobileapplication to verify that BLEis enabled on your XBee device.

1. Get the Digi XBeeMobile phone application.

2. Open the Digi XBee Mobile application. The Find XBee devices screen appears and the app automatically begins scanning for devices. All nearby devices with BLEenabled are displayed in a list.

3. Scroll through the list to find your XBee device.

The first time you open the app on a phone and scan for devices, the device list contains only the name of the device and the BLE signal strength. No identifying information for the device displays. After you have authenticated the device, the device information is cached on the phone. The next time the app on this phone connects to the XBee device, the IMEI for the device displays in the app device list.

Note The IMEI is derived from the SH and SL values.

4. Tap the XBee device name in the list. A password dialog appears.

5. Enter the password you previously configured for the device in XCTU.

6. Tap OK. The Device Information screen displays. You can now scroll through the settings for the XBee device and change the device's configuration as needed.

BLE reference

BLE advertising behavior and services

When the Bluetooth radio is enabled, periodic BLE advertisements are transmitted. The advertisement data includes the product name. When an XBee device connects to the Bluetooth radio, the BLE services are listed:

n Device Information Service

n XBee API BLEService

Device Information Service

The standard Device Information Service is used. The Manufacturer, Model, and Firmware Revision characters are provided inside the service.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 75

Get started with BLE BLE reference

XBee API BLEService

You can configure the XBee through the BLE interface using API frame requests and responses. The API frame format through Bluetooth is equivalent to setting AP=1 and transmitting the frames over the UART or SPI interface. API frames can be executed over Bluetooth regardless of the AP setting.

The BLE interface allows these frames:

n BLE Unlock API - 0x2C

n BLEUnlock Response - 0xAC

n AT Command - 0x08

This API reference assumes that you are familiar with Bluetooth and GATT services. The specifications for Bluetooth are an open standard and can be found at the following links:

n Bluetooth Core Specifications: https://www.bluetooth.com/specifications/bluetooth-core-

specification

n Bluetooth GATT: https://www.bluetooth.com/specifications/gatt/generic-attributes-overview

The XBee API GATT Service contains two characteristics: the API Request characteristic and the API Response characteristic. The UUIDs for the service and its characteristics are listed in the table below.

Characteristic UUID

APIService UUID 53da53b9-0447-425a-b9ea-9837505eb59a

APIRequest Characteristic UUID

API Response Characteristic UUID

7dddca00-3e05-4651-9254-44074792c590

f9279ee9-2cd0-410c-81cc-adf11e4e5aea

API Request characteristic

UUID: 7dddca00-3e05-4651-9254-44074792c590

Permissions: Writeable

XBee API frames are broken into chunks and transmitted sequentially to the request characteristic using write operations. Valid frames will then be processed and the result will be returned through indications on the response characteristic.

API frames do not need to be written completely in a single write operation to the request characteristic. In fact, Bluetooth limits the size of a written value to 3 bytes smaller than the configured MTU (Maximum Transmission Unit), which defaults to 23, meaning that by default, you can only write 20 bytes at a time.

You must bond with the XBee in order to write to this characteristic. If you do not bond before writing, you will receive errors when attempting to write.

After connecting and bonding, you must send a valid Bluetooth Unlock API Frame in order to authenticate the connection. If the Bluetooth Unlock API Frame has not been executed, all other API frames will be silently ignored and not processed.

API Response characteristic

UUID: f9279ee9-2cd0-410c-81cc-adf11e4e5aea

Permissions: Readable, Indicate

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 76

Get started with BLE BLE reference

Responses to API requests made to the request characteristic will be returned through the response characteristics. This characteristic cannot be read directly.

Response data will be presented through indications on this characteristic. Indications are acknowledged and re-transmitted at the BLE link layer and application layer and provides a robust transport for this data.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 77

Get started with Digi Remote Manager

Digi Remote Manager® is a cloud-based device and data management platform that you can use to configure and update a device, and view and manage device data.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

The sections below describe how to create a Remote Manager account, upgrading your device, configure your device, and manage data in Remote Manager.

1. Create a Remote Manager account and add devices

2. To ensure that all Remote Manager features are available, you should upgrade your device to the latest firmware. See Update the firmware from Remote Manager or Update the firmware

using web services in Remote Manager.

3. Configure your device in Remote Manager

To be able to configure your device in Remote Manager, the device must be connected to Remote Manager. You can connect to and configure your device in Remote Manager using one of the following methods:

Scheduled connection: In this method, you create a list of tasks that you want to perform on the device, and then start the operation. This is the recommended method, and is the best choice for low data usage. See Configure Remote Manager features by

scheduling tasks.

Always connected: This method can be used for initial configuration, or when you are not concerned with low data usage. See Configure XBee settings within Remote

Manager.

4. Secure the connection between an XBee and Remote Manager with server authentication.

5. Manage data in Remote Manager

6. Remote Manager reference

Create a Remote Manager account and add devices

To be able to use Remote Manager, you must create a Remote Manager account and add your XBee devices to the device list. You should also verify that the device is enabled to connect to Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 78

Get started with Digi Remote Manager Create a Remote Manager account and add devices

1. Create a Remote Manager account.

2. Add an XBee Smart Modem to Remote Manager.

3. Verify the connection between a device and 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.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

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 FREETRIAL/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.

Add an XBee Smart Modem to Remote Manager

Each XBee Smart Modem must be added to the Remote Manager account inventory list.

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 XCTUto view the IMEI number by querying the IM parameter.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

To add an XBee to your Remote Manager account inventory, follow these steps:

1. Log into Remote Manager.

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-M/NB-IoT Global Smart Modem User Guide

Page 79

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

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.

Verify the connection between a device and Remote Manager

By default, the XBee is configured to enable a connection to Remote Manager. The connection between XBee and Remote Manager is maintained using periodic UDP operations.

You should verify the default settings to ensure that the connection will work as desired.

Launch XCTU .

2. Verify that the MO command is set to 6, which is the default.

3. Configure the frequency of polls for Remote Manager activity using the DF command. The default is 1440 minutes (24 hours).

4. Enable the SM/UDP feature in Remote Manager for each device. See Enable SM/UDP.

Configure Remote Manager features by scheduling tasks

Remote Manager provides tools to perform common management and maintenance tasks on your XBee device. A Remote Manager task is a sequence of commands that can be performed on one or more XBee Cellular devices. Tasks can then be assigned to a schedule. When a scheduled task is run it becomes an active operation and can be monitored for status and completion.

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Some typical examples of useful things that can be done with scheduled tasks include:

n Change configuration

n Update your MicroPython application and libraries to add features and capabilities

n Update your security certificates

n Perform a data service device request

n Send an SMS message to your device

Scheduled tasks can be created and performed through the following methods:

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 80

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

n Remote Manager Schedules user interface.

n Remote Manager API Explorer user interface

n Programming web service calls

Note For any of these methods to work properly, you must have SM/UDP enabled. See Enable

SM/UDP.

Overview: Create a schedule for a set of tasks

When using the most current firmware version, the XBee Cellular devices are designed to poll Remote Manager once per day over the SM/UDP protocol to check for any active operations. In order to perform a set of tasks, the device needs to be told to connect to Remote Manager, perform the sequence of tasks, and then told to disconnect.

The following provides a template of how to create a schedule for an XBee to connect, perform a set of tasks and then disconnect:

1. Make sure that SM/UDPis enabled. See Enable SM/UDP.

2. Log into Remote Manager.

3. Click Device Management > Schedules.

4. Click New Schedule. The New Schedule page displays.

Note The Steps to schedule a task wizard may display. Click the x in the upper left corner to

close the wizard. See Schedule walk-through feature in the Digi Remote Manager® User Guide for more information.

5. In the Description field, enter a name for the schedule, such "Read Settings."

6. Add the following tasks:

a. Click SM/UDP > SM/UDP Request Connect. A task is added to the dialog.

b. Add other tasks as needed. For examples, refer to the Examples section.

c. Click Device > Disconnect. A task is added to the dialog.

7. Click Schedule in the lower right corner of the dialog to schedule the tasks to run. The schedule screen displays.

Note You can also click Save as to save this schedule for future use.

8. Select the device(s) on which you want to run this schedule. You can add more than one device.

9. Click Run Now.

Examples

The examples in the following sections assume you are using the Digi Remote Manager Schedule wizard. However, you should be aware that operations can be created and performed programmatically via web service calls or via the API explorer. The XML web service calls provide more options than are available in the GUI dashboard for some tasks.

Example: Read settings and state using Remote Manager

In order to configure devices you will need to know the structure of the XML for your XBee's settings. The easiest way to obtain this is to perform a query_setting RCI request against your device.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 81

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Note To obtain the state of the device, you can perform the same operations in the example below,

but replace query_setting with query_state.

1. Log into Remote Manager.

2. Click Device Management > Schedules.

3. Click New Schedule. The New Schedule page displays.

Note The Steps to schedule a task wizard may display. Click the x in the upper left corner to

close the wizard. See Schedule walk-through feature in the Digi Remote Manager® User Guide for more information.

4. In the Description field, enter a name for the schedule, such "Read Settings."

5. Add the following tasks:

a. Click SM/UDP > SM/UPD Request Connect. A task is added to the dialog.

b. Click Device > RCI Command. A task is added to the dialog.

Change the RCI command to the following:

<rci_request>

<query_setting/>

</rci_request>

c. Click Device > Disconnect. A task is added to the dialog.

6. Click Schedule in the lower right corner of the dialog to schedule the tasks to run. The schedule screen displays.

Note You can also click Save as to save this schedule for future use.

7. Select the device(s) on which you want to run this schedule. You can add more than one device.

8. Click Run Now.

9. Click Device Management > Operations to view information about the operation. See

Operations in the Digi Remote Manager® User Guide for more information about this page.

After your operation completes you can click Response to view the XML for all of the settings that your XBee reports. This XML structure has the same settings that you will use in the set_setting command to configure your XBee as shown in this example: Example: Configure a device from Remote

Manager using XML.

Example: Configure a device from Remote Manager using XML

You can configure each XBee device from Remote Manager, using XML. The devices must be in the Remote Manager inventory device list and be active.

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 82

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

In this configuration example, you are changing the device to poll four times a day instead of just once. In this case, you should change the DF parameter to 360 minutes.

1. Log into Remote Manager.

2. Click Device Management > Schedules.

3. Click New Schedule. The New Schedule page displays.

Note The Steps to schedule a task wizard may display. Click the x in the upper left corner to

close the wizard. See Schedule walk-through feature in the Digi Remote Manager® User Guide for more information.

4. In the Description field, enter a name for the schedule, such as "Configure Reporting Frequency."

5. Add the following tasks:

a. Click SM/UDP > SM/UPD Request Connect. A task is added to the dialog.

b. Click Device > RCI Command. A task is added to the dialog.

Change the RCI command to the following:

<rci_request>

<set_setting>

<remote_manager>

</remote_manager>

</set_setting>

</rci_request>

c. Click Device > Disconnect. A task is added to the dialog.

6. Click Schedule in the lower right corner of the dialog to schedule the tasks to run. The schedule screen displays.

Note You can also click Save as to save this schedule for future use.

7. Select the device(s) on which you want to run this schedule. You can add more than one device.

8. Click Run Now.

9. Click Device Management > Operations to view information about the operation. See

Operations in the Digi Remote Manager® User Guide for more information about this page.

Example: Update XBee firmware using Remote Manager

You can use a scheduled task to update the XBee Cellular firmware. Since the device is configured by default to poll Remote Manager once a day, you need to be able to set up a scheduled task to update the device's firmware to take advantage of new features and fixes. To update the firmware to a new version you will need to obtain the .gbl file for the new firmware from our support site. This file is one of the files in the .zip (for example, XBXC-31011.zip) archive that you can download for the product.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 83

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

To upgrade using a scheduled task perform the following steps:

Step 1:

1. Download the updated firmware file for your device from Digi's support site.

a. Go to the Digi XBee3 Cellular LTE-M support page.

b. Scroll down to the Firmware Updates section.

c. Locate and click Digi XBee3 Cellular LTE-M/NB-IoT Gating Firmware to download

the zip file. If you have already upgraded past the gating firmware, click XBee Cellular LET-M/NB-IoT Firmware to download the zip file.

d. Unzip the file. The file contains either a .ebin or a .gbl file.

2. Log into Remote Manager.

3. Make sure that you have enabled SM/UDP. See Enable SM/UDP.

4. Click Device Management > Schedules.

5. Click New Schedule. The New Schedule page displays.

Note The Steps to schedule a task wizard may display. Click the x in the upper left corner to

close the wizard. See Schedule walk-through feature in the Digi Remote Manager® User Guide for more information.

6. In the Description field, enter a name for the schedule, such as "Update XBee Firmware."

7. Add the following tasks:

a. Click SM/UDP > SM/UDP Request Connect. A task is added to the dialog.

b. Click Device > Gateway Firmware Update.

c. Click Browse and select the .gbl file (for example, XBXC-11411.gbl) for the new

firmware to update.

d. Click Device > Disconnect. A task is added to the dialog.

8. Click Schedule in the lower right corner of the dialog to schedule the tasks to run. The schedule screen displays.

Note You can also click Save as to save this schedule for future use.

9. Select the device(s) on which you want to run this schedule. You can add more than one device.

10. Click Run Now.

11. Click Device Management > Operations to view information about the operation. See

Operations in the Digi Remote Manager® User Guide for more information about this page.

Example: Update MicroPython from Remote Manager using XML

You can use the API Explorer in Remote Manager to create a schedule that enables you to update the MicroPython application. In this example, you want to add FTP client capability to the MicroPython application. You will need to add the library uftp.py and then update the main.py application.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 84

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

This example is done following these steps: upload the MicroPython files to Remote Manager, create

an XML file with the tasks that you want to perform, upload the XML file, and then schedule an operation to upload the files onto your device.

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

Step 1: Upload the MicroPython files

1. Log into Remote Manager.

2. Click Data Services > Data Files.

3. Upload the MicroPython application main.py file.

a. Click New Folder. The New Folder dialog displays.

b. In the Folder name field, enter a descriptive name, such as "MicroPython."

c. Click Create. The new file is added to the list of files.

d. Find the "MicroPython" folder in the folder list.

e. Click Upload Files. The Upload Files dialog displays.

f. Browse for the main.py file. Check with your system administrator for the location

of the application file.

g. Click OK.

4. Upload the MicroPython library uftp.py file.

a. Find the "MicroPython" folder in the folder list.

b. Click Upload Files. The Upload Files dialog displays.

c. Browse for the uftp.py file. The library uftp.py file is found on the GitHub repository:

https://github.com/digidotcom/xbee-micropython

d. Click OK.

Step 2: Create an XML file with the tasks that you want to perform

This XML file will contain a list of commands for the operation that you will schedule in Step 3.

Note The RCI commands to set_settings in the task may fail to execute because of disconnects after

changing the value for MO.

1. Open the editor of your choice.

2. Create a new file named "updatemicropython.xml."

3. Copy the XML below and paste it into the new file.

4. Save the file.

<task>

<description>Update MicroPython</description> <command>

<name>SM/UDP Request Connect</name> <event>

<on_error>

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 85

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

<end_task/>

</on_error> </event> <sci>

<send_message reply="none" >

<sm_udp>

<request_connect/>

</sm_udp>

</send_message> </sci>

</command> <command>

<name>RCI Command</name> <event>

<on_error>

</on_error> </event> <sci>

<send_message cache="false" allowOffline="true" >

<!-- Disable Python Auto-start and enable TCP connection for

remainder of commands-->

<rci_request>

<set_setting>

</set_setting>

</rci_request>

</send_message>

</sci> </command> <command>

<name>Reboot</name> <event>

<on_error>

</on_error> </event> <sci>

</sci>

</command>

<name>Upload Files</name> <event>

<on_error>

</on_error>

</event> <sci>

<file_system allowOffline="true" >

<put_file path="/flash/main.py">

<file>~/MicroPython/main.py</file>

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 86

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

</put_file>

</commands>

</file_system>

</sci> </command> <command>

<name>Upload Files</name>

<event>

<on_error>

</on_error> </event> <sci>

<file_system allowOffline="true" >

<put_file path="/flash/lib/uftp.py">

<file>~/MicroPython/uftp.py</file>

</put_file>

</commands>

</file_system> </sci>

</command> <command>

<name>RCI Command</name> <event>

<on_error>

</on_error> </event> <sci>

<send_message cache="false" allowOffline="true">

<rci_request>

<set_setting>

</set_setting>

</rci_request>

</send_message>

</sci>

</command>

<name>Reboot</name>

<event>

<on_error>

<end_task/>

</on_error> </event> <sci>

</command>

</task>

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 87

Get started with Digi Remote Manager Configure Remote Manager features by scheduling tasks

Step 3: Upload the XML to Remote Manager

In this step you will upload the file you just created (updatemicropython.xml) to Remote Manager.

1. Log into Remote Manager.

2. Click Data Services > Data Files.

3. Upload the XML file you just created: updatemicropython.xml

a. Find the "~/my_tasks" folder in the folder list.

b. Click Upload Files. The Upload Files dialog displays.

c. Browse for the updatemicropython.xml file.

d. Click OK.

Step 4: Schedule an operation to upload the files

1. Log into Remote Manager.

2. Click Documentation > API Explorer.

3. Click SCI Targets. The Select devices to be used in examples dialog appears.

a. From the Add Targets list box, search for the IMEI (device ID) of the device that you

want to update.

b. Click Add. The device is added to the device list.

c. Click OK.

4. Click the Examples drop-down list button.

5. Click Scheduled Operation > Create immediate running schedule.

6. Update the XML to refer to the updatemicropython.xml file you created previously.

<Schedule on="IMMEDIATE">

</Schedule>

7. Click Send to schedule the task.

8. Click Device Management > Operations to view information about the operation. See

Operations in the Digi Remote Manager® User Guide for more information about this page.

Restore persistent connection to a remote XBee

The default connectivity to Remote Manager in the most recent firmware polls once a day using SM/UDP, which means that your XBee will always appear in a disconnected state and will use significantly less data.

If needed, you can restore the default connectivity to use the former behavior, where the device is continually connected using TCP. To do this, you will need to set bit 0 of the MO setting. The suggested value is 7 to connect securely over TLS, or you can use 1 for no security, which is the legacy value.

You can make the change using one of the following methods:

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 88

Get started with Digi Remote Manager Manage data in Remote Manager

n Local access: If you have local access to the device you can use XCTU to change the MO setting

back to the former default value.

n Remote access: If you only have remote access to your XBee you can change the device to

maintain a persistent connection to Remote Manager. To do this you can set up a scheduled operation in Remote Manger for your device, as shown below.

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

To set up a scheduled operation to maintain a persistent connection:

1. Make sure that you have enabled SM/UDP. See Enable SM/UDP.

2. Log into Remote Manager.

3. Click Device Management > Schedules.

4. Click New Schedule. The New Schedule page displays.

Note The Steps to schedule a task wizard may display. Click the x in the upper left corner to

close the wizard. See Schedule walk-through feature in the Digi Remote Manager® User Guide for more information.

5. In the Description field, enter a name for the schedule, such as "Restore Persistent."

6. Add the following tasks:

a. Click SM/UDP > SM/UPD Request Connect. A task is added to the dialog.

b. Click Device > RCI Command. A task is added to the dialog.

Change the RCI command to the following:

<rci_request>

<set_setting/>

<remote_manager>

</remote_manager>

</set_setting>

</rci_request>

7. Click Schedule in the lower right corner of the dialog to schedule the tasks to run. The schedule screen displays.

Note You can also click Save as to save this schedule for future use. The XML for your task is

saved in the ~\my_tasks directory on Data Services > Data Files in Remote Manager.

8. Select the device(s) on which you want to run this schedule. You can add more than one device.

9. Click Run Now. Within the next 24 hours, which is the default polling period for querying Remote Manager, your device will connect and will remain connected, as specified by the change to the MO setting.

10. Click Device Management > Operations to view information about the operation. See

Operations in the Digi Remote Manager® User Guide for more information about this page.

Manage data in Remote Manager

You can view and manage XBee data in Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 89

Get started with Digi Remote Manager Manage data in Remote Manager

Review device status information from Remote Manager

You can view address, BLE, cellular, firmware, and I/O sampling status information for a XBee device in Remote Manager. The device must be in the Remote Manager inventory device list and be active.

Note You must upgrade your device to the latest firmware for this feature to be available. See Update

the firmware from Remote Manager or Update the firmware using web services in Remote Manager.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

1. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:

n Remote Manager: A persistent connection can be set up in Remote Manager. This

option should be used when you have many deployed devices and no local access. See

Restore persistent connection to a remote XBee.

n XCTU: This option allows immediate access, and should be used when you have local

access, such as when using a development kit or in a lab environment.

2. Log into Remote Manager.

3. Click Device Management > Devices.

4. Select the device that you want to configure.

5. Click Properties in the toolbar. As an alternative, click Properties > Edit Device Configuration. The configuration Home page appears.

6. Click Status in the toolbar to display the status sub-menus.

7. Click on the status group that has information you want to display. The status information is related to ATcommands. For information about each ATcommand in the categories, click on the appropriate link below.

n Addressing

n Bluetooth

n Cellular

n Firmware Version/Information

n I/O

8. Click Home to return to the configuration Home page.

9. When all changes are complete, disconnect the device from Remote Manager.

Update the firmware from Remote Manager

XBee Smart Modem supports Remote Manager firmware updates.

If you are upgrading the device firmware to a version listed below, your connection will disconnect and by default, your device will query Remote Manager only once a day. If you wish to restore the persistent connection behavior that was the default in prior firmware versions, see Restore persistent

connection to a remote XBee.

After you have upgraded to the new firmware version, it is recommended that you keep the polling frequency low to reduce data usage. In order to upgrade firmware in the future, refer to Example:

Update XBee firmware using Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 90

Get started with Digi Remote Manager Manage data in Remote Manager

Module Upgrade firmware version

XBee CAT 1 Verizon 1011

XBee 3G 11311

XBee3 LTE-M 11411

XBee3 CAT 1 31011

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

WARNING! The firmware version 1140F reorganizes the product's flash memory and upgrades the product to version 11410. You cannot downgrade to a version earlier than 11410 after installing 1140F/11410.

To perform a firmware update:

1. Download the updated firmware file for your device from Digi's support site.

a. Go to the Digi XBee3 Cellular LTE-M support page.

b. Scroll down to the Firmware Updates section.

c. Locate and click Digi XBee3 Cellular LTE-M/NB-IoT Gating Firmware to download

the zip file.

d. Unzip the file. The file contains either a .ebin or a .gbl file.

2. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:

n Remote Manager: A persistent connection can be set up in Remote Manager. This

option should be used when you have many deployed devices and no local access. See

Restore persistent connection to a remote XBee.

n XCTU: This option allows immediate access, and should be used when you have local

access, such as when using a development kit or in a lab environment.

3. Log into Remote Manager.

4. In your Remote Manager account, click Device Management > Devices.

5. Select the first device you want to update.

6. To select multiple devices (must be of the same type), press the Control key and select additional devices.

7. Click More in the Devices toolbar and select Update Firmware from the Update category of the More menu. The Update Firmware dialog appears.

8. Click Browse to select the downloaded .ebin or .gbl file that you unzipped earlier.

9. Click Update Firmware. The updated devices automatically reboot when the updates are complete.

10. When all changes are complete, disconnect the device from Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 91

Get started with Digi Remote Manager Manage data in Remote Manager

Update the firmware using web services in Remote Manager

Remote Manager supports both synchronous and asynchronous firmware update using web services. The following examples show how to perform an asynchronous firmware update. See the Remote Manager documentation for more details on firmware updates.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

1. Download the updated firmware file for your device from Digi's support site.

a. Go to the Digi XBee3 Cellular LTE-M support page.

b. Scroll down to the Firmware Updates section.

c. Locate and click Digi XBee3 Cellular LTE-M/NB-IoT Gating Firmware to download

the zip file.

d. Unzip the file. The file contains either a .ebin or a .gbl file.

2. Unzip the file and locate the .ebin file inside the unzipped directory.

3. Send an HTTP SCI request to Remote Manager with the contents of the downloaded .ebin or .gbl file converted to base64 data; see the following examples:

Examples for .ebin:

n Example: update the XBee .ebin firmware synchronously with Python 3.0

n Example: use the device's .ebin firmware image to update the XBee firmware

synchronously

Examples for .gbl:

n Example: update the XBee .gbl firmware synchronously with Python 3.0

n Example: use the device's .gbl firmware image to update the XBee firmware

synchronously

Example: update the XBee .ebin firmware synchronously with Python 3.0

import base64 import requests

# Location of firmware image firmware_path = 'XBXC.ebin'

# Remote Manager device ID of the device being updated device_id = '00010000-00000000-03526130-70153378'

# Remote Manager username and password username = "my_Remote_manager_username" password = "my_remote_manager_password"

url = 'https://remotemanager.digi.com/ws/sci'

# Get firmware image

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 92

Get started with Digi Remote Manager Manage data in Remote Manager

fw_file = open(firmware_path, 'rb') fw_data = fw_file.read() fw_data = base64.encodebytes(fw_data).decode('utf-8')

# Form update_firmware request data = """ <sci_request version="1.0">

<update_firmware filename="firmware.ebin">

</update_firmware> </sci_request> """.format(device_id, fw_data)

# Post request r = requests.post(url, auth=(username, password), data=data) if (r.status_code != 200) or ("error" in r.content.decode('utf-8')):

print("firmware update failed")

else:

print("firmware update success")

Example: use the device's .ebin firmware image to update the XBee firmware synchronously

To update the XBee firmware synchronously with Python 3.0, but using the device firmware image already uploaded to Remote Manager, upload the device's *.ebin firmware to Remote Manager:

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 and locate the .ebin inside the unzipped directory.

3. Log in to Remote Manager.

4. Click the Data Services tab.

5. Click Data Files.

6. Click Upload Files; browse and select the *.ebin firmware file to upload it.

7. Send an HTTP SCI request to Remote manager with the path of the .ebin file; see the example below.

import base64 import requests

# Location of firmware image on Remote Manager firmware_path = '~/XBXC.ebin'

# Remote Manager device ID of the device being updated device_id = '00010000-00000000-03526130-70153378'

# Remote Manager username and password username = "my_remote_manager_username" password = "my_remote_manager_password"

url = 'https://remotemanager.digi.com/ws/sci'

# Form update_firmware request

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 93

Get started with Digi Remote Manager Manage data in Remote Manager

data = """ <sci_request version="1.0">

<update_firmware filename="firmware.ebin">

</update_firmware> </sci_request> """.format(device_id, firmware_path)

# Post request r = requests.post(url, auth=(username, password), data=data) if (r.status_code != 200) or ("error" in r.content.decode('utf-8')):

print("firmware update failed")

else:

print("firmware update success")

Example: update the XBee .gbl firmware synchronously with Python 3.0

import base64 import requests

# Location of firmware image firmware_path = 'XBXC.gbl'

# Remote Manager device ID of the device being updated device_id = '00010000-00000000-03526130-70153378'

# Remote Manager username and password username = "my_Remote_manager_username" password = "my_remote_manager_password"

url = 'https://remotemanager.digi.com/ws/sci'

# Get firmware image fw_file = open(firmware_path, 'rb') fw_data = fw_file.read() fw_data = base64.encodebytes(fw_data).decode('utf-8')

# Form update_firmware request data = """ <sci_request version="1.0">

<update_firmware filename="firmware.gbl">

</update_firmware> </sci_request> """.format(device_id, fw_data)

# Post request r = requests.post(url, auth=(username, password), data=data) if (r.status_code != 200) or ("error" in r.content.decode('utf-8')):

print("firmware update failed")

else:

print("firmware update success")

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 94

Get started with Digi Remote Manager Manage data in Remote Manager

Example: use the device's .gbl firmware image to update the XBee firmware synchronously

To update the XBee firmware synchronously with Python 3.0, but using the device firmware image already uploaded to Remote Manager, upload the device's *.gbl firmware to Remote Manager:

1. Download the updated firmware file for your device from Digi's support site. This is a zip file containing .gbl and .mxi files for import.

2. Unzip the file and locate the .gbl file inside the unzipped directory.

3. Log in to Remote Manager.

4. Click the Data Services tab.

5. Click Data Files.

6. Click Upload Files; browse and select the *.gbl firmware file to upload it.

7. Send an HTTP SCI request to Remote manager with the path of the .gbl file; see the example below.

import base64 import requests

# Location of firmware image on Remote Manager firmware_path = '~/XBXC.gbl'

# Remote Manager device ID of the device being updated device_id = '00010000-00000000-03526130-70153378'

# Remote Manager username and password username = "my_remote_manager_username" password = "my_remote_manager_password"

url = 'https://remotemanager.digi.com/ws/sci'

# Form update_firmware request data = """ <sci_request version="1.0">

<update_firmware filename="firmware.gbl">

</update_firmware> </sci_request> """.format(device_id, firmware_path)

# Post request r = requests.post(url, auth=(username, password), data=data) if (r.status_code != 200) or ("error" in r.content.decode('utf-8')):

print("firmware update failed")

else:

print("firmware update success")

Manage secure files in Remote Manager

You can interact with files on the XBee device from Remote Manager, using either the SCI (Server

command interface) or in the File Management view.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 95

Get started with Digi Remote Manager Remote Manager reference

You can securely upload files by appending a hash sign (#) to the end of the file name. After the upload, the hash sign (#) is not retained as part of the file name. For example, you could upload a file named

my-cert.crt appended with a hash sign (#): my-cert.crt#. After the upload is complete, the file is named my-cert.crt.

Note Uploading secure files in Remote Manager has the same result as doing an ATFS XPUT locally.

See Secure files for more information.

SCI(Server command interface)

You can use the SCI (Server command interface) file_system command to securely upload a file. For more information, see the file_system section in the Digi Remote Manager Programming Guide.

File Management view

You can upload and manage files in the Remote Manager File Management view.

1. Prepare the file that you want to upload.

a. Find the file on your hard drive.

b. Rename the file and append a hash sign (#) to the end of the file name.

2. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:

n Remote Manager: A persistent connection can be set up in Remote Manager. This

option should be used when you have many deployed devices and no local access. See

Restore persistent connection to a remote XBee.

n XCTU: This option allows immediate access, and should be used when you have local

access, such as when using a development kit or in a lab environment.

3. Log into Remote Manager.

4. Click Device Management > Devices.

5. Select the device that you want to configure.

6. Click Properties in the toolbar. As an alternative, double-click on the device name. The Properties page appears.

7. Click File Management. The File Management view appears.

8. Click the upload icon. The Upload File dialog appears.

a. Click Browse to browse for the file you want to upload. The selected file displays in

the File field. Make sure that the file name is appended by a hash sign (#).

b. Click OK. The uploaded file displays in the File Management view. Note that the file

name is no longer appended by a hash sign (#).

9. When all changes are complete, disconnect the device from Remote Manager.

Remote Manager reference

Enable SM/UDP

You can use the SM/UDP feature to leverage the very small data footprint of Remote Manager SM protocol over UDP.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 96

Get started with Digi Remote Manager Remote Manager reference

1. Log into Remote Manager.

2. Click Device Management > Devices.

3. Select the device that you want to configure.

4. Click More >SM/UDP > Configure. The SM/UDP dialog appears.

5. Verify that the Battery Operated Mode is not selected.

This mode is not supported with Remote Manager and if enabled, the connectivity between XBee and Remote Manager may not work as expected.

6. Select SM/UDP Service Enabled to enable SM/UDP.

7. Click Save.

Note Do not enable battery-operated mode. This mode is not supported with Remote Manager and if

enabled, the connectivity between XBee and Remote Manager may not work as expected.

Disconnect

The TCP connection remains open and periodic polling occurs until you manually disconnect the TCPconnection. After you have disconnected the TCP connection, Remote Manager is no longer updated.

You can disconnect the TCP connection using either of the following methods:

n From the Devices page in Remote Manager: See Disconnect a device in the Digi Remote

Manager® User Guide.

n Using web services in Remote Manager: See Request connect SM/UDP support in the Digi

Remote Manager® Programming Guide.

Configure XBee settings within Remote Manager

You can configure the device settings to use features with Remote Manager. For more information, see Example: Read settings and state using Remote Manager.

Configure device settings in Remote Manager

You can configure each XBee device from Remote Manager. The devices must be in the Remote Manager inventory device list and be active.

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

1. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:

n Remote Manager: A persistent connection can be set up in Remote Manager. This

option should be used when you have many deployed devices and no local access. See

Restore persistent connection to a remote XBee.

n XCTU: This option allows immediate access, and should be used when you have local

access, such as when using a development kit or in a lab environment.

2. Log into Remote Manager.

3. Click Device Management > Devices.

4. Select the device that you want to configure.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 97

Get started with Digi Remote Manager Remote Manager reference

5. Click Properties in the toolbar. As an alternative, click Properties > Edit Device Configuration. The configuration Home page appears.

6. Click Config in the toolbar to display the settings sub-menus.

7. Click on the settings category that you want to configure. The settings in that category appear.

8. Makethe desired configuration changes. See AT commands for information about each setting in the categories.

9. As you finish configuring in each setting category, click Apply to save the changes. If the changes are valid, Remote Manager writes them to non-volatile memory and applies them.

10. When all changes are complete, disconnect the device from Remote Manager.

Configure Remote Manager keepalive interval

Note Digi Remote Manager requires TCPand will not work with NB-IoT, unless the carrier supports

TCP.

Managing the data usage and the keepalive interval is important if you have the MO (Remote Manager

Options) command bit 0 set to 1 or if you have enabled the Request connect feature in Remote

Manager.

Digi Remote Manager is enabled on the XBee by default and has a 60 second keepalive interval, which can result in excessive cellular data usage, depending on your plan. The K1 and K2 commands can be used to tune the keepalive interval. Your carrier will disconnect an inactive socket automatically if there is no activity, so you need to tune this value based on your carrier’s disconnect timeout.

You can further reduce your data usage by periodically duty cycling your Remote Manager connection, either from MicroPython or your host processor. For example, you could enable the Remote Manager connection for 2 hours a day and then disable the connection for 22 hours. Your host processor or MicroPython program would need to keep track of the time to ensure the time interval.

Configure SMSmessaging in Remote Manager

You can configure a XBee device to use SMS functionality in Remote Manager. This feature uses a "request connect" operation and asks a device to make a full TCP connection to Remote Manager. For a device with SMS capability this can be significantly lower on latency and data cap consumption, as it does not involve polling.

Each device must be individually configured in Remote Manager to use this feature.

Note The SMS provision feature cannot be used. This feature is found by selecting a device and then

choosing More > SMS > Provision. Attempts to enable this feature are ignored.

1. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:

n Remote Manager: A persistent connection can be set up in Remote Manager. This

option should be used when you have many deployed devices and no local access. See

Restore persistent connection to a remote XBee.

n XCTU: This option allows immediate access, and should be used when you have local

access, such as when using a development kit or in a lab environment.

2. Log in to Remote Manager.

3. Select the Device Management tab.

4. Select the device that you want to configure.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 98

Get started with Digi Remote Manager Remote Manager reference

5. In the toolbar, select More > SMS > Configure. The SMS Configuration dialog appears.

6. Select the SIM 1 option. This should be selected by default.

7. In the Phone Number field, enter the device's SIMcard phone number. You can use the PH

(Phone Number) command to discover the device's phone number.

8. Expand the Advanced Options section.

9. From the Server Number for SIM 1 list box, select the appropriate option:

n If the Remote Manager phone number is a domestic number, select a short code. The

default is 32075-idgp.

n If the Remote Manager phone number is an international number, select a long code.

Note The options in the Server Number for SIM 1 list box are determined within Remote

Manager, and are used to ensure an SMS connection between the device and Remote Manager. The option selected from the list box must match the Remote Manager phone number and service ID set for the device. The XBee examines received SMS messages and if the phone number matches and content contains the correct service ID it will be processed internally rather than being delivered as user data. By default, the device is configured with "32075" as the Remote Manger phone number and "idgp" as the Remote Manager service ID. If you need an alternate short (domestic) code or a long (international) code, you can re-configure the device using the DP (Remote Manager

Phone Number) and RI (Remote Manager Service ID) commands.

10. Click Save.

11. When all changes are complete, disconnect the device from Remote Manager.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 99

Technical specifications

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

Page 100

Technical specifications Interface and hardware specifications

Interface and hardware specifications

The following table provides the interface and hardware specifications for the device.

Specification Value

Dimensions 24.38 mm x 32.94 mm (0.960 x 1.297 in)

Weight 5 g (0.18 oz)

Operating temperature

Antenna connector

Digital I/O 13 I/O lines, I2C

ADC 4 10-bit analog inputs

Analog input voltage range 0 - 2.5 V

Cellular chipset u-blox SARA-R410M-028

Form factor Digi XBee 20-pin through-hole

SIM size 4FF Nano

Cellular RF characteristics

The following table provides the RF characteristics for the device.

Specification Value

Transmit power Up to 23 dBm, Power Class 3

Receive sensitivity -105 dBm

-40 to +85 °C

Cellular: U.FL Bluetooth: U.FL

Bluetooth RF characteristics

The following table provides the Bluetooth RF characteristics for the device.

Specification Value

Transmit power Up to 8 dBm

Receive sensitivity, 1 Mb/s data rate -92 dBm

Receive sensitivity, 2 Mb/s data rate -88 dBm

Operating frequency band ISM 2.4 - 2.4835 GHz

Cellular networking specifications

The following table provides the networking and carrier specifications for the device.

Digi XBee3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

100