Digi XBee 3 Cat 1 User guide

Page 1
Digi XBee® 3 Cat 1 Smart Modem User Guide
Smart Modem
User Guide
Page 2

Revision history—90002503

Revision Date Description
A
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.
© 2022 Digi International Inc. All rights reserved.
Disclaimers
Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International. Digi provides this document “as is,” without warranty of any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or merchantability for a particular purpose. Digi may make improvements and/or changes in this manual or in the product(s) and/or the program(s) described in this manual at any time.
Warranty
To view product warranty information, go to the following website:
www.digi.com/howtobuy/terms
Initial release of the document.
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)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
Digi XBee® 3 Cat 1 Smart Modem User Guide
2
Page 3
techcomm@digi.com
Include the document title and part number (Digi XBee® 3 Cat 1 Smart Modem User Guide, 90002503 A) in the subject line of your email.
Digi XBee® 3 Cat 1 Smart Modem User Guide
3
Page 4
Contents
Revision history—90002503 2
Digi XBee® 3 Cat 1 Smart Modem User Guide
Applicable firmware and hardware 16 SIM cards 17 Safety instructions 17
Safety instructions 17
Инструкции за безопасност 17
Sigurnosne upute 18 Bezpečnostní instrukce 19 Sikkerhedsinstruktioner 19 Veiligheidsinstructies 20 Ohutusjuhised 20 Turvallisuusohjeet 21 Consignes de sécurité 21 Sicherheitshinweise 22
Οδηγίες ασφαλείας 22
Biztonsági utasítások 23 Istruzioni di sicurezza 23 Drošības instrukcijas 24 Saugos instrukcijos 25 Sikkerhetsinstruksjoner 25 Instrukcje bezpieczeństwa 26 Instruções de segurança 26 Instructiuni de siguranta 27 Bezpečnostné inštrukcie 27 Varnostna navodila 28 Las instrucciones de seguridad 28 Säkerhets instruktioner 29
Get started with the XBee Smart Modem
Identify the kit contents 31 Determine cellular service and acquire a SIM card 32
UScustomers 32
European customers 32 Connect the hardware 33 Install and upgrade XCTU 34
Add a device to XCTU 34 Update the device and cellular firmware using XCTU 35
Digi XBee® 3 Cat 1 Smart Modem User Guide
4
Page 5
Check for cellular registration and connection 35 Cellular service 36
XBee connection examples
Connect to the Echo server 38 Connect to the ELIZA server 40 Connect to the Daytime server 42 Send an SMS message to a phone 44 Perform a (GET) HTTP request 46 Connect to a TCP/IP address 48 Software libraries 48
Get started with MicroPython
About MicroPython 51
Why use MicroPython 51 MicroPython on the XBee Smart Modem 51 Use XCTU to enter the MicroPython environment 51 Use the MicroPython Terminal in XCTU 52
Troubleshooting 52 Example: hello world 52 Example: Turn on an LED 52 Example: code a request help button 53
Enter MicroPython paste mode 54
Catch a button press 54
Send a text (SMS) when the button is pressed 56
Add the time the button was pressed 57 Example: debug the secondary UART 58 Exit MicroPython mode 58 Other terminal programs 59
Tera Term for Windows 59 Use picocom in Linux 60
Get started with Bluetooth® Low Energy
On XBee 3 Cellular firmware ending in x16 or newer 62 Enable BLE on an XBee device 62 Enable BLEand configure the BLEpassword using XCTU 62 Get the Digi XBeeMobile phone application 63 Connect with BLEand configure your XBee device 64 BLE reference 64
BLE advertising behavior and services 64
Device Information Service 64
XBee API BLEService 64
API Request characteristic 65
API Response characteristic 65
Get started with Digi Remote Manager
Create a Remote Manager account and add devices 66
Create a Remote Manager account 67
Add an XBee Smart Modem to Remote Manager 67
Digi XBee® 3 Cat 1 Smart Modem User Guide
5
Page 6
Verify the connection between a device and Remote Manager 67 Configure Remote Manager features using automations 68
Overview: Create an automation 68 Automation examples 69
Example: Read settings and state using Remote Manager 69
Example: Configure a device from Remote Manager using XML 70
Example: Schedule an automation to update the device firmware using Remote Manager 71
Example: Update MicroPython from Remote Manager using an automation 73 Manage data in Remote Manager 74
Review device status information from Remote Manager 74
Manage secure files in Remote Manager 75 Remote Manager reference 76
Enable SM/UDP 76
TCP connection 76
Disconnect 77
Configure XBee settings within Remote Manager 78
Examples: IOT protocols with transparent mode
Get started with CoAP 81
CoAP terms 81
CoAP quick start example 81
Configure the device 82
Example: manually perform a CoAPrequest 82
Example: Use Python to generate a CoAP message 83 Get started with MQTT 85
Example: MQTT connect 85
Send a connect packet 87
Example: send messages (publish) with MQTT 88
Example: receive messages (subscribe) with MQTT 89
Use MQTT over the XBee Cellular Modem with a PC 90
Update the firmware
Create a plan for device and cellular component firmware updates 95 Update the device and the cellular firmware using XCTU 96
Update the device and cellular firmware using XCTU and USBDirect access 96 Update the device firmware 98
Update the firmware from the Devices page in Remote Manager 98
Update the firmware using web services in Remote Manager 99
Use a host processor to update the device firmware for XBee 3 devices over UART 101 Update the cellular firmware 102
Update the cellular component firmware using Remote Manager 102
Update the cellular firmware using the API 104
Technical specifications
Interface and hardware specifications 108 RF characteristics 108 Networking specifications 109
Bands 109 Power requirements 110 Power consumption 110
Digi XBee® 3 Cat 1 Smart Modem User Guide
6
Page 7
Electrical specifications 111 Regulatory approvals 112
Hardware
Mechanical drawings 113 Pin signals 113
Pin connection recommendations 115 XBee header connector requirements 115 RSSI PWM 116 SIM card 116 GNSS (Global Navigation Satellite System) 116 Associate LED functionality 117 Development boards 118
XBIB-CU-TH reference 118
Interface with the XBIB-C-GPS module 122
Antenna recommendations
Antenna connections 124 Keepout area and design recommendations 124
Through-hole keepout 126 Antenna placement 127 GNSS antennas 127
GNSS antenna requirements 127
GNSS receiver characteristics 128
Installation guidelines for GNSS antennas 128
Design recommendations
Power supply considerations 129 Clean shutdown 129
SD (Shutdown) command 129 Cellular component firmware updates 130 Recommended application circuit 130 Heat considerations and testing 131 Heat sink guidelines 131 Add a fan to provide active cooling 133 Custom configuration: Create a new factory default 133
Set a custom configuration 133
Clear all custom configurations on a device 134 SIMcards 134
Cellular connection process
Connecting 136
Cellular network 136
Data network connection 136 Data communication with remote servers (TCP/UDP) 136 Disconnecting 137
Digi XBee® 3 Cat 1 Smart Modem User Guide
7
Page 8
Modes
Select an operating mode 139 Transparent operating mode 140 API operating mode 140 USB direct mode 140
Connect the hardware for USBDirect mode 140
Enable USB direct mode 141
Configure and use PPP with a Digi XBee 3 Cellular CAT1 AT&T modem 141 Command mode 144
Enter Command mode 144
Troubleshooting 144
Send AT commands 145
Response to AT commands 145
Apply command changes 146
Make command changes permanent 146
Exit Command mode 146 MicroPython mode 146
Sleep modes
About sleep modes 148 Normal mode 148 Pin sleep mode 148 Cyclic sleep mode 148 Cyclic sleep with pin wake up mode 148 The sleep timer 148 MicroPython sleep behavior 148
Power saving features and design recommendations
Airplane mode 151 Low voltage shutdown 151
Serial communication
Serial interface 154 Serial data 154 UART data flow 154 Serial buffers 155 CTS flow control 155 RTS flow control 155 Enable UART or SPI ports 155
SPI operation
SPI communications 158 Full duplex operation 158 Low power operation 159 Select the SPI port 160 Force UART operation 160 Data format 161
Digi XBee® 3 Cat 1 Smart Modem User Guide
8
Page 9
File system
Overview of the file system 163
Directory structure 163
Paths 163
Secure files 163 XCTU interface 164 Encrypt files 164
SMS behaviors
SMS encoding 165
Socket behavior
Supported sockets 167 Best practices when using sockets 167
Sockets and Remote Manager 167
Sockets and API mode 167 Socket timeouts 167 Socket limits in API mode 167 UDP datagram size limits 168 Enable incoming TCP connections 168 API mode behavior for outgoing TCP and TLS connections 168 API mode behavior for outgoing UDP data 169 API mode behavior for incoming TCP connections 169 API mode behavior for incoming UDP data 170 Transparent mode behavior for outgoing TCP and TLS connections 170 Transparent mode behavior for outgoing UDP data 170 Transparent mode behavior for incoming TCP connections 171 Transparent mode behavior for incoming UDP connections 171
Extended Socket frames
Examples 172 Available Extended Socket frames 173 Extended Socket example: Single HTTP Connection 173
Send a Socket Create frame 173
Receive a Socket Create response 174
Send Socket Connect 174
Receive a Socket Connect Response 174
Receive a Socket Status 175
Send HTTP Request using Socket Send frame 175
Receive TX Status 176
Receive one or more Receive Data frames 176
Receive Socket Status indicating closed connection 177 Extended Socket example: UDP 177
Send a Socket Create frame 177
Receive a Socket Create response 178
Bind local source addres 178
Receive Bind/Listen Response 178
Send to Digi echo server 179
Receive TX Status 179
Digi XBee® 3 Cat 1 Smart Modem User Guide
9
Page 10
Receive echoed data 179
Send to Digi time server 180
Receive TX Status 180
Receive daytime value 180
Close the socket 181
Receive close response 181 Extended Socket example: TCPListener 182
Send a Socket Create frame 182
Receive a Socket Create response 182
Designate the socket as a listener 182
Receive a Socket Bind/Listen Response 183
Making a connection to the listener socket 183
Receiving Data from the new socket 184
Receive a Socket Status indicating closed connection 184
Transport Layer Security (TLS)
Specifying TLS keys and certificates 187 Transparent mode and TLS 188 API mode and TLS 188 Key formats 188 Certificate limitations 188 Cipher suites 188 Secure the connection between an XBee and Remote Manager with server authentication 189
Step 1: Get the certificate 189
Step 2: Configure device 189
Step 3: Verify that authentication is being performed 189
AT commands
Special commands 192
AC (Apply Changes) 192
FR (Force Reset) 192
RE (Restore Defaults) 192
SD (Shutdown) 193
WR (Write) 193 Cellular commands 194
PH (Phone Number) 194
S# (ICCID) 194
IM (IMEI) 194
II (Subscriber identity) 194
MN (Operator) 194
MV (Modem Firmware Version) 195
MU (Modem firmware revision number) 195
DB (Cellular Signal Strength) 195
DT (Cellular Network Time) 195
AN (Access Point Name) 196
OA (Operating APN) 196
CP (Carrier Profile) 196
BM (Bandmask) 197
AM (Airplane Mode) 198
DV (Secondary Antenna Function Switch) 198
SQ (Reference Signal Received Quality) 198
SW (Reference Signal Received Power) 199
Digi XBee® 3 Cat 1 Smart Modem User Guide
10
Page 11
PN (SIMPIN) 199
PK (SIMPUK) 200
OT (Operating Technology) 200
FC(Frequency Channel Number) 200 Network commands 201
IP (IP Protocol) 201
TL (TLS Protocol Version) 201
$0 (TLS Profile 0) 201
$1 (TLS Profile 1) 202
$2 (TLS Profile 2) 202
TM (IP Client Connection Timeout) 202
TS (IP Server Connection Timeout) 203
DO (Device Options) 203
PG (Ping) 204 Addressing commands 205
SH (Serial Number High) 205
SL (Serial Number Low) 205
MY (Module IP Address) 205
P# (Destination Phone Number) 205
N1 (DNS Address) 206
N2 (DNS Address) 206
DL (Destination Address) 206
OD (Operating Destination Address) 206
DE (Destination port) 207
C0 (Source Port) 207
LA (Lookup IP Address of FQDN) 207
NI (Node Identifier) 208 Serial interfacing commands 209
BD (Baud Rate) 209
NB (Parity) 209
SB (Stop Bits) 210
RO (Packetization Timeout) 210
TD (Text Delimiter) 210
FT (Flow Control Threshold) 211
AP (API Enable) 211
IB (Cellular Component Baud Rate) 211 I/O settings commands 213
D0 (DIO0/AD0) 213
D1 (DIO1/AD1) 213
D2 (DIO2/AD2) 214
D3 (DIO3/AD3) 214
D4 (DIO4) 214
D5 (DIO5/ASSOCIATED_INDICATOR) 215
D6 (DIO6/RTS) 215
D7 (DIO7/CTS) 216
D8 (DIO8/SLEEP_REQUEST) 216
D9 (DIO9/ON_SLEEP) 217
P0 (DIO10/PWM0 Configuration) 217
P1 (DIO11/PWM1 Configuration) 217
P2 (DIO12 Configuration) 218
P3 (DIO13/DOUT) 218
P4 (DIO14/DIN) 219
PD (Pull Direction) 219
PR (Pull-up/down Resistor Enable) 219
M0 (PWM0 Duty Cycle) 220
Digi XBee® 3 Cat 1 Smart Modem User Guide
11
Page 12
M1 command 221 I/O sampling commands 222
TP (Temperature) 222
IS (Force Sample) 222 Sleep commands 224
SM (Sleep Mode) 224
SP (Sleep Period) 224
ST (Wake Time) 224 Command mode options 225
CC (Command Sequence Character) 225
CT (Command Mode Timeout) 225
CN (Exit Command mode) 225
GT (Guard Times) 225 MicroPython commands 227
PS (Python Startup) 227
PY (MicroPython Command) 227 Firmware version/information commands 229
VR (Firmware Version) 229
VL (Verbose Firmware Version) 229
HV (Hardware Version) 229
HS (Hardware Series) 229
CK (Configuration CRC) 229
AI (Association Indication) 230
FI(FTP OTA Update Indication) 230
FO (FTP OTA command) 231
RJ (Network Reject Cause) 232 Diagnostic interface commands 233
DI (Remote Manager Indicator) 233
CI (Protocol/Connection Indication) 233
AS (Active scan for network environment data) 235 Execution commands 237
NR (Network Reset) 237
!R (Modem Reset) 237 File system commands 238
Error responses 238
ATFS (File System) 238
ATFS PWD 238
ATFS CDdirectory 238
ATFS MDdirectory 238
ATFS LS [directory] 238
ATFS PUTfilename 239
ATFS XPUTfilename 239
ATFS HASHfilename 239
ATFS GETfilename 239
ATFS MVsource_pathdest_path 239
ATFS RMfile_or_directory 239
ATFS INFO 239
ATFSFORMAT confirm 240 BLE commands 241
BI (Bluetooth Identifier) 241
BL (Bluetooth MAC address) 241
BP (Bluetooth Advertisement Power Level) 241
BT (Bluetooth enable) 241
$S (SRPSalt) 242
$V, $W, $X, $Y (SRPpassword verifier) 242
Digi XBee® 3 Cat 1 Smart Modem User Guide
12
Page 13
Remote Manager commands 243
MO (Remote Manager Options) 243
DF (Remote Manager Status Check Interval) 243
EQ (Remote Manager FQDN) 243
K1 (Remote Manager Server Send Keepalive) 244
K2 (Remote Manager Device Send Keepalive) 244
$D (Remote Manager certificate) 244
HF (Health Metrics Reporting Frequency) 244
HM (Health Metrics) 245
ER (Remote Manager TCP Port Override) 246
ES (Remote Manager UDP Port Override) 246
MT (Remote Manager Idle Timeout) 247 System commands 248
KL (Device Location) 248
KC (Contact Information) 248
KP (Device Description) 248 Socket commands 249
SI (Socket Info) 249 GNSS commands 250
GP (GPS) 250
GO (GPS Options) 251 Power measurement commands 251
%V command 251
%L (Low voltage shutdown base threshold) 251
%M (Low voltage shutdown reset offset) 252
Operate in API mode
API mode overview 254 Use the AP command to set the operation mode 254 API frame format 254
API operation (AP parameter = 1) 254
API operation with escaped characters (AP parameter = 2) 255
API frames
AT Command - 0x08 260 AT Command: Queue Parameter Value - 0x09 261 Transmit (TX) SMS - 0x1F 262 Transmit (TX) Request: IPv4 - 0x20 263 Tx Request with TLS Profile - 0x23 265 AT Command Response - 0x88 267 Transmit (TX) Status - 0x89 268 Modem Status - 0x8A 270 Receive (RX) Packet: SMS - 0x9F 271 Receive (RX) Packet: IPv4 - 0xB0 272 User Data Relay - 0x2D 273
Example use cases 273 User Data Relay Output - 0xAD 275 BLE Unlock API - 0x2C 276
Example sequence to perform AT Command XBee API frames over BLE 278 BLEUnlock Response - 0xAC 280 Socket Create - 0x40 281 Socket Create Response - 0xC0 282
Digi XBee® 3 Cat 1 Smart Modem User Guide
13
Page 14
Socket Option Request - 0x41 283 Socket Option Response - 0xC1 284 Socket Connect - 0x42 285 Socket Connect Response - 0xC2 286 Socket Close - 0x43 287 Socket Close Response - 0xC3 288 Socket Send (Transmit) - 0x44 289 Socket SendTo (Transmit Explicit Data): IPv4 - 0x45 290 Socket Bind/Listen - 0x46 291 Socket Listen Response - 0xC6 292 Socket New IPv4 Client - 0xCC 293 Socket Receive - 0xCD 294 Socket Receive From: IPv4 - 0xCE 295 Socket Status - 0xCF 296 GNSS Start Raw NMEA, Stop Raw NMEA, or One Shot Request - 0x3D 296 GNSS Start Raw NMEA, Stop Raw NMEA, or One Shot Response - 0xBD 297 GNSS Raw NMEA Response - 0xBE 297 GNSS One Shot Response - 0xBF 298
File system APIframes
Local File System Request - 0x3B 300
File Open - 0x01 301
File Close - 0x02 302
File Read - 0x03 303
File Write - 0x04 303
File Hash - 0x08 304
Directory Create - 0x10 305
Directory Open - 0x11 305
Directory Close - 0x12 306
Directory Read - 0x13 307
Get Path ID - 0x1C 307
Delete - 0x2F 308
Volume Info - 0x40 308
Volume Format - 0x4F 309 Local File System Response - 0xBB 309
Regulatory firmware
Install the regulatory firmware 312
Install regulatory firmware using XCTU 312
Install regulatory firmware using Remote Manager 313 Configure regulatory firmware for testing the Bluetooth radio 314 Configure regulatory firmware for testing the cellular component 314 Bluetooth DTMprotocol 314
Example 315 Regulatory testing commands 315
%# (Enable/disable test mode) 316
%1 (Start test mode) 316
%2 (Stop test mode) 317
%5 (Start modulated transmit) 317
%6 (Stop transmit) 317
%7 (Set EARFCN) 317
%8 (Get the EARFCN) 318
Digi XBee® 3 Cat 1 Smart Modem User Guide
14
Page 15
%9 (Set transmit power) 318
%A (Get transmit power) 318
%D (Start receive mode) 319
%H (Set channel mapping) 319
%I (Get channel mapping) 319
%? (Query test state) 320
Troubleshooting
Cannot find the serial port for the device 322
Condition 322
Solution 322
Other possible issues 323
Enable Virtual COM port (VCP) on the driver 323 Correct a macOS Java error 324
Condition 324
Solution 324 Unresponsive cellular component in Bypass mode 325
Condition 325
Solution 325 Not on expected network after APN change 326
Condition 326
Solution 326 Syntax error at line 1 326
Solution 326 Error Failed to send SMS 326
Solution 326 Baud rate in Bypass mode 326
Regulatory information
Antenna regulatory information: FCC and ISED 327
Bluetooth antennas 327
Cellular antennas 328
FCC publication 996369 related information 329 Labeling requirements for the host device:FCCand ISED 330 Regulatory Information 332
Modification statement 332
Interference statement 332
FCC Class B digital device notice 332
RF exposure 333
FCC notices 333 Regulatory Information: ISED 334
Modification statement:ISED 334
Interference statement:ISED 334
RF exposure: ISED 334
Digi XBee® 3 Cat 1 Smart Modem User Guide
15
Page 16

Digi XBee® 3 Cat 1 Smart Modem User Guide

The XBee Smart Modem is an embedded Long-Term Evolution (LTE) Category 1 cellular module that provides original equipment manufacturers (OEMs) with a simple way to integrate cellular connectivity into their devices.
The XBee Smart Modem enables OEMs to quickly integrate cutting edge 4G cellular technology into their devices and applications without dealing with the painful, time-consuming, and expensive FCC and carrier end-device certifications.
With the full suite of standard XBee API frames and AT commands, existing XBee customers can seamlessly transition to this new device with only minor software adjustments. When OEMs add the XBee Smart Modem to their product, they create a future-proof design with flexibility to switch between wireless protocols or frequencies as needed.
You can read some frequently asked questions here.

Applicable firmware and hardware

This manual supports the following firmware:
n 118xx and above
Note This manual uses the placeholder value "xx" in the firmware versions listed above, as the
manual documents the released features as of the time of its writing. Digi International periodically releases new firmware containing bug fixes and new features. As new firmware is released and distributor stock is refreshed, the new firmware will gradually become available without the need to update. However, no guarantees can be made that a specific version of the firmware will be populated on any given XBee as delivered. If a specific revision is desired, it is the user's responsibility to ensure that version is loaded onto all XBees purchased.
This device supports the following hardware:
SKU Description
XB3-C-G1-UT-001
XB3-C-N1-UT-001 XBee 3 North America LTE Cat 1 without SIM
XB3-C-G1-UT-101
XB3-C-N1-UT-101 XBee 3 North America LTE Cat 1 with AT&T SIM
XB3-C-G1-UT-102
XB3-C-N1-UT-102 XBee 3 North America LTE Cat 1 with Verizon SIM
Digi XBee® 3 Cat 1 Smart Modem User Guide
XBee 3 Global LTE Cat 1 without SIM
XBee 3 Global LTE Cat 1 with AT&T SIM
XBee 3 Global LTE Cat 1 with Verizon SIM
16
Page 17
Digi XBee® 3 Cat 1 Smart Modem User Guide SIM cards
The device uses the following Thales (formerly Cinterion) cellular modem modules:
n Thales Global LTE Cat 1 module: PLS63-W n Thales North America LTECat 1 module: PLS63-X

SIM cards

The XBee Smart Modem requires a 4FF nano-SIM card, which is the size normally used in most Smart phones. The SIM interface supports both 1.8 V and 3.3 V SIM types.

Safety instructions

Safety instructions

XBee adapter, gateways, and routers
n The XBee Adapter, Gateway, or Router products cannot be guaranteed operation due to the
radio link and so should not be used for interlocks in safety critical devices such as machines or automotive applications.
n The XBee Adapter, Gateway, or Router products have not been approved for use in (this list is
not exhaustive):
l medical devices l nuclear applications l explosive or flammable atmospheres
n There are no user serviceable components inside the XBee Adapter, Gateway, or Router
product. Do not remove the product covers or modify the Gateway or Router in any way. Modifications may exclude the product from any warranty and can cause the gateway or router to operate outside of regulatory compliance for a given country, leading to the possible illegal operation of the product.
n Use industry standard ESD protection when handling the XBee Adapter, Gateway, or Router
product.
n Take care while handling to avoid electrical damage to the PCB and components. n Do not expose the XBee Adapter, Gateway, or Router products to water or moisture. n Use this product with the antennas specified in the XBee Adapter, Gateway, or Router product
user guides.
n The end user must be told how to remove power from the XBee Adapter, Gateway, or Router
product or to locate the antennas 20 cm from humans or animals.

Инструкции за безопасност

XBee модули
n Радио модулът XBee не може да бъде гарантиран за работа поради радиовръзката и
затова не трябва да се използва за блокировки в к ритични за безопасността устройства като машини или автомобилни приложения.
Digi XBee® 3 Cat 1 Smart Modem User Guide
17
Page 18
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n Радио модулът XBee не е одобрен за използване в (този списък не е изчерпателен):
l медицински изделия
l ядрени приложения
l експлозивна или запалима атмосфера
n В радиомодула XBee няма к омпоненти, които могат да се обслужват от потребителя. Не
премахвайте щита и не модифицирайте XBee по ник акъв начин. Модификациите могат да изключат модула от всякаква гаранция и да накарат радиото XBee да работи извън регулаторното съответствие за дадена държава, което води до възможна незаконна работа на радиото.
n Използвайте стандартна ESD защита при работа с XBee модула. n Внимавайте, докато боравите, за да избегнете електрически повреди на печатната
платка и к омпонентите.
n Не излагайте радиомодулите XBee на вода или влага. n Използвайте този продукт с антените, посочени в ръководствата за потребителя на
модула XBee.
n Крайният потребител трябва да бъде к азано как да премахне захранването от
радиомодула XBee или да разположи антените на 20 смот хора или животни.

Sigurnosne upute

XBee moduli
n Radio modulu XBee ne može se jamčiti rad zbog radio veze i stoga se ne smije koristiti za
blokade u sigurnosnim kritičnim uređajima kao što su strojevi ili automobilske aplikacije.
n XBee radio modul nije odobren za upotrebu u (ovaj popis nije konačan):
l medicinskih uređaja l nuklearne primjene l eksplozivne ili zapaljive atmosfere
n Unutar XBee radio modula nema komponenti koje može servisirati korisnik. Nemojte uklanjati
štit i ni na koji način modificirati XBee. Izmjene mogu isključiti modul iz bilo kakvog jamstva i mogu uzrokovati rad XBee radija izvan usklađenosti s propisima za određenu zemlju, što može dovesti do mogućeg nezakonitog rada radija.
n Koristite standardnu ESD zaštitu pri rukovanju XBee modulom. n Budite oprezni tijekom rukovanja kako biste izbjegli električna oštećenja PCB-a i komponenti. n Ne izlažite XBee radio module vodi ili vlazi. n Koristite ovaj proizvod s antenama navedenim u korisničkim vodičima za XBee modul. n Krajnjem korisniku se mora reći kako da isključi napajanje iz XBee radio modula ili da locira
antene 20 cm od ljudi ili životinja.
Digi XBee® 3 Cat 1 Smart Modem User Guide
18
Page 19
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions

Bezpečnostní instrukce

moduly XBee
n Rádiový modulXBee nemůže zaručit provoz kvůli rádiovému spojení, a proto by neměl být
používán pro blokování v zařízeních kritických z hlediska bezpečnosti, jako jsou stroje nebo automobilové aplikace.
n Rádiový modulXBee nebyl schválen pro použití v (tento seznam není vyčerpávající):
l zdravotnické prostředky l jaderné aplikace l výbušné nebo hořlavé atmosféry
n Uvnitř rádiového modulu XBee nejsou žádné uživatelsky opravitelné součásti. Neodstraňujte
štít ani nijak neupravujte XBee. Úpravy mohou vyjmout modul z jakékoli záruky a mohou způsobit, že rádio XBee bude fungovat mimo zákonnou shodu pro danou zemi, což povede k možnému nezákonnému provozu rádia.
n Při manipulaci s modulem XBee používejte standardní ochranu ESD. n Při manipulaci buďte opatrní, aby nedošlo k elektrickému poškození desky plošných spojů a
součástí.
n Nevystavujte rádiové moduly XBee vodě nebo vlhkosti. n Používejte tento produkt s anténami uvedenými v uživatelských příručkách modulu XBee. n Koncový uživatel musí být informován, jak odpojit napájení rádiového modulu XBee nebo jak
umístit antény 20 cm od lidí nebo zvířat.

Sikkerhedsinstruktioner

XBee moduler
n XBee-radiomodulet kan ikke garanteres drift på grund af radioforbindelsen og bør derfor ikke
bruges til aflåsninger i sikkerhedskritiske enheder såsom maskiner eller bilapplikationer.
n XBee-radiomodulet er ikke godkendt til brug i (denne liste er ikke udtømmende):
l medicinsk udstyr l nukleare applikationer l eksplosive eller brandfarlige atmosfærer
n Der er ingen komponenter, der kan repareres af brugeren, inde i XBee-radiomodulet. Fjern ikke
skjoldet eller modificer XBee på nogen måde. Ændringer kan udelukke modulet fra enhver garanti og kan få XBee-radioen til at fungere uden for lovgivningsoverholdelse for et givet land, hvilket kan føre til den mulige ulovlige drift af radioen.
n Brug industristandard ESD-beskyttelse, når du håndterer XBee-modulet. n Vær forsigtig under håndteringen for at undgå elektrisk beskadigelse af printet og
komponenterne.
n Udsæt ikke XBee-radiomoduler for vand eller fugt. n Brug dette produkt med de antenner, der er specificeret i XBee-modulets brugervejledninger.
Digi XBee® 3 Cat 1 Smart Modem User Guide
19
Page 20
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n Slutbrugeren skal fortælles, hvordan man fjerner strømmen fra XBee-radiomodulet eller
placerer antennerne 20 cm fra mennesker eller dyr.

Veiligheidsinstructies

XBee-modules
n De werking van de XBee-radiomodule kan niet worden gegarandeerd vanwege de
radioverbinding en mag daarom niet worden gebruikt voor vergrendelingen in veiligheidskritieke apparaten zoals machines of autotoepassingen.
n De XBee-radiomodule is niet goedgekeurd voor gebruik in (deze lijst is niet uitputtend):
l o medische apparaten l o nucleaire toepassingen l o explosieve of ontvlambare atmosferen
n Er zijn geen door de gebruiker te onderhouden componenten in de XBee-radiomodule.
Verwijder het schild niet en wijzig de XBee op geen enkele manier. Modificaties kunnen de module uitsluiten van enige garantie en kunnen ertoe leiden dat de XBee-radio werkt buiten de regelgeving voor een bepaald land, wat kan leiden tot de mogelijke illegale werking van de radio.
n Gebruik industriestandaard ESD-bescherming bij het hanteren van de XBee-module. n Wees voorzichtig bij het hanteren om elektrische schade aan de printplaat en componenten te
voorkomen.
n Stel XBee-radiomodules niet bloot aan water of vocht. n Gebruik dit product met de antennes die zijn gespecificeerd in de gebruikershandleidingen van
de XBee-module.
n De eindgebruiker moet worden verteld hoe de voeding van de XBee-radiomodule moet worden
losgekoppeld of hoe de antennes op 20 cm van mensen of dieren moeten worden geplaatst.

Ohutusjuhised

XBee moodulid
n XBee raadiomooduli tööd ei saa raadiolingi tõttu garanteerida ja seetõttu ei tohiks seda
kasutada ohutuse seisukohalt oluliste seadmete (nt masinad või autorakendused) blokeerimiseks.
n XBee raadiomoodulit ei ole heaks kiidetud kasutamiseks (see loetelu ei ole ammendav):
l meditsiiniseadmed l tuumarakendused l plahvatusohtlik või tuleohtlik keskkond
n XBee raadiomoodulis ei ole kasutaja poolt hooldatavaid komponente. Ärge eemaldage kaitset
ega muutke XBee mingil viisil. Muudatused võivad mooduli garantiist välja jätta ja XBee raadio töötab väljaspool antud riigi regulatiivseid vastavusi, põhjustades raadio võimaliku ebaseadusliku kasutamise.
n Kasutage XBee mooduli käsitsemisel tööstusharu standardset ESD-kaitset.
Digi XBee® 3 Cat 1 Smart Modem User Guide
20
Page 21
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n Olge käsitsemisel ettevaatlik, et vältida PCB ja komponentide elektrikahjustusi. n Ärge jätke XBee raadiomooduleid vee või niiskuse kätte. n Kasutage seda toodet XBee mooduli kasutusjuhendis kirjeldatud antennidega. n Lõppkasutajale tuleb öelda, kuidas XBee raadiomoodulilt toide eemaldada või antennid
inimestest või loomadest 20 cm kaugusele paigutada.

Turvallisuusohjeet

XBee moduulit
n XBee-radiomoduulin toimintaa ei voida taata radiolinkin vuoksi, joten sitä ei tule käyttää
turvallisuuden kannalta kriittisten laitteiden, kuten koneiden tai autosovellusten, lukitsemiseen.
n XBee-radiomoduulia ei ole hyväksytty käytettäväksi (tämä luettelo ei ole tyhjentävä):
l lääketieteelliset laitteet l ydinvoimasovellukset l räjähdysvaarallisiin tai syttyviin tiloihin
n XBee-radiomoduulin sisällä ei ole käyttäjän huollettavia osia. Älä poista suojusta tai muokkaa
XBeetä millään tavalla. Muutokset voivat sulkea moduulin takuun ulkopuolelle ja aiheuttaa sen, että XBee-radio toimii tietyn maan säädöstenmukaisuuden ulkopuolella, mikä johtaa radion mahdolliseen laittomaan käyttöön.
n Käytä alan standardia ESD-suojausta käsitellessäsi XBee-moduulia. n Ole varovainen käsitellessäsi, jotta vältät piirilevyn ja komponenttien sähkövauriot. n Älä altista XBee-radiomoduuleja vedelle tai kosteudelle. n Käytä tätä tuotetta XBee-moduulin käyttöoppaissa määriteltyjen antennien kanssa. n Loppukäyttäjälle on kerrottava, kuinka XBee-radiomoduulin virta katkaistaan tai antennit
sijoitetaan 20 cm:n etäisyydelle ihmisistä tai eläimistä.

Consignes de sécurité

Modules XBee
n Le fonctionnement du module radio XBee ne peut pas être garanti en raison de la liaison radio
et ne doit donc pas être utilisé pour les verrouillages dans des dispositifs critiques pour la sécurité tels que des machines ou des applications automobiles.
n Le module radio XBee n'a pas été approuvé pour une utilisation dans (cette liste n'est pas
exhaustive) :
l dispositifs médicaux l applications nucléaires l atmosphères explosives ou inflammables
n Il n'y a aucun composant réparable par l'utilisateur à l'intérieur du module radio XBee. Ne
retirez pas la protection et ne modifiez en aucune façon le XBee. Les modifications peuvent exclure le module de toute garantie et peuvent entraîner le fonctionnement de la radio XBee
Digi XBee® 3 Cat 1 Smart Modem User Guide
21
Page 22
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
en dehors de la conformité réglementaire pour un pays donné, ce qui peut entraîner un fonctionnement illégal de la radio.
n Utilisez la protection ESD standard de l'industrie lors de la manipulation du module XBee. n Soyez prudent lors de la manipulation afin d'éviter des dommages électriques au circuit
imprimé et aux composants.
n N'exposez pas les modules radio XBee à l'eau ou à l'humidité. n Utilisez ce produit avec les antennes spécifiées dans les guides d'utilisation du module XBee. n L'utilisateur final doit savoir comment couper l'alimentation du module radio XBee ou placer les
antennes à 20 cm des humains ou des animaux.

Sicherheitshinweise

XBee-Module
n Der Betrieb des XBee-Funkmoduls kann aufgrund der Funkverbindung nicht garantiert werden
und sollte daher nicht für Verriegelungen in sicherheitskritischen Geräten wie Maschinen oder Automobilanwendungen verwendet werden.
n Das XBee-Funkmodul ist nicht zugelassen für den Einsatz in (diese Liste ist nicht vollständig):
l Medizinprodukte l nukleare Anwendungen l explosive oder brennbare Atmosphären
n Das XBee-Funkmodul enthält keine vom Benutzer zu wartenden Komponenten. Entfernen Sie
nicht die Abschirmung oder modifizieren Sie das XBee in irgendeiner Weise. Modifikationen können das Modul von jeglicher Garantie ausschließen und dazu führen, dass das XBee­Funkgerät außerhalb der gesetzlichen Vorschriften für ein bestimmtes Land betrieben wird, was zu einem möglichen illegalen Betrieb des Funkgeräts führen kann.
n Verwenden Sie beim Umgang mit dem XBee-Modul ESD-Schutz nach Industriestandard. n Seien Sie vorsichtig bei der Handhabung, um elektrische Schäden an der Leiterplatte und den
Komponenten zu vermeiden.
n XBee-Funkmodule nicht Wasser oder Feuchtigkeit aussetzen. n Verwenden Sie dieses Produkt mit den in den Benutzerhandbüchern des XBee-Moduls
angegebenen Antennen.
n Dem Endbenutzer muss mitgeteilt werden, wie er das XBee-Funkmodul von der
Stromversorgung trennt oder die Antennen 20 cm von Menschen oder Tieren entfernt aufstellt.

Οδηγίες ασφαλείας

Μονάδες XBee
n Η μονάδα ραδιοφώνου XBee δεν μπορεί να εγγυηθεί τη λειτ ουργία της λόγωτης ραδιοζεύξης και
επομένως δεν πρέπει ναχρησιμοποιείται για ασφάλειες σε κρίσιμες για την ασφάλεια συσκευές, όπως μηχανήματα ή εφαρμογές αυτοκινήτου.
n Η μονάδα ραδιοφώνου XBee δεν έχει εγκριθεί για χρήση σε (αυτή η λίστα δεν είναι εξαντλητική):
Digi XBee® 3 Cat 1 Smart Modem User Guide
22
Page 23
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
l ιατροτεχνολογικά προϊόντα l πυρηνικές εφαρμογές
l εκρηκτικές ή εύφλεκτες ατμόσφαιρες
n Δεν υπάρχουν εξαρτήματα που να μπορούν να επισκευαστούν από το χρήστη μέσα στη μονάδα
ραδιοφώνου XBee. Μην αφαιρείτε την ασπίδα και μην τροποποιείτε το XBee με κανέναν τρόπο. Οι τροποποιήσεις ενδέχεται να αποκλείουν τη μονάδα από οποιαδήποτε εγγύηση και μπορεί να προκαλέσουν τη λειτουργία του ραδιοφώνου XBee εκτός της συμμόρφωσης με τους κανονισμούς για μια δεδομένη χώρα, οδηγώντας σε πιθανή παράνομη λειτουργία του ραδιοφώνου.
n Χρησιμοποιήστε βιομηχανική προστασία ESD κατά το χειρισμό της μονάδας XBee. n Προσέχετε κατά το χειρισμό για νααποφύγετε ηλεκτρική βλάβη στο PCB και στα εξαρτήματα. n Μηνεκθέτετε τις μονάδες ραδιοφώνου XBee σε νερό ή υγρασία. n Χρησιμοποιήστε αυτό το προϊόνμε τις κεραίες που καθορίζονται στους οδηγούς χρήσης της
μονάδας XBee.
n Πρέπει να ενημερωθεί ο τελικός χρήστης πώς να αφαιρέσει την τροφοδοσία από τη μονάδα
ραδιοφώνου XBee ή να εντοπίσει τις κεραίες σε απόσταση 20 cm από ανθρώπους ή ζώα.

Biztonsági utasítások

XBee modulok
n Az XBee rádiómodul működése nem garantálható a rádiókapcsolat miatt, ezért nem
használható biztonsági szempontból kritikus eszközök, például gépek vagy autóipari alkalmazások reteszelésére.
n Az XBee rádiómodul nem engedélyezett a következő területeken való használatra (ez a lista
nem teljes):
l orvosi eszközök l nukleáris alkalmazások l robbanásveszélyes vagy gyúlékony légkör
n Az XBee rádiómodulban nincsenek felhasználó által javítható alkatrészek. Ne távolítsa el a
pajzsot, és semmilyen módon ne módosítsa az XBee-t. A módosítások kizárhatják a modult a jótállásból, és az XBee rádió működését az adott ország jogszabályi előírásaitól eltérően okozhatják, ami a rádió esetleges illegális működéséhez vezethet.
n Az XBee modul kezelésekor használjon ipari szabványos ESD védelmet. n A kezelés során ügyeljen arra, hogy elkerülje a PCB és az alkatrészek elektromos károsodását. n Ne tegye ki az XBee rádiómodulokat víznek vagy nedvességnek. n Használja ezt a terméket az XBee modul használati útmutatójában meghatározott
antennákkal.
n A végfelhasználót tájékoztatni kell arról, hogyan távolítsa el az XBee rádiómodul
áramellátását, vagy hogyan helyezze el az antennákat az emberektől vagy állatoktól 20 cm-re.

Istruzioni di sicurezza

Moduli XBee
Digi XBee® 3 Cat 1 Smart Modem User Guide
23
Page 24
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n Il funzionamento del modulo radio XBee non può essere garantito a causa del collegamento
radio e quindi non deve essere utilizzato per gli interblocchi in dispositivi critici per la sicurezza come macchine o applicazioni automobilistiche.
n Il modulo radio XBee non è stato approvato per l'uso in (questo elenco non è esaustivo):
l dispositivi medici l applicazioni nucleari l atmosfere esplosive o infiammabili
n Non ci sono componenti riparabili dall'utente all'interno del modulo radio XBee. Non rimuovere
lo scudo o modificare in alcun modo l'XBee. Le modifiche possono escludere il modulo da qualsiasi garanzia e possono causare il funzionamento della radio XBee al di fuori della conformità normativa per un determinato paese, portando al possibile funzionamento illegale della radio.
n Utilizzare la protezione ESD standard del settore durante la manipolazione del modulo XBee. n Prestare attenzione durante la manipolazione per evitare danni elettrici al PCB e ai
componenti.
n Non esporre i moduli radio XBee all'acqua o all'umidità. n Utilizzare questo prodotto con le antenne specificate nelle guide per l'utente del modulo XBee. n L'utente finale deve sapere come togliere l'alimentazione al modulo radio XBee o come
posizionare le antenne a 20 cm da persone o animali.

Drošības instrukcijas

XBee moduļi
n Radio moduļa XBee darbība nevar tikt garantēta radio savienojuma dēļ, tāpēc to nevajadzētu
izmantot bloķēšanai drošības ziņā kritiskās ierīcēs, piemēram, mašīnās vai automobiļos.
n XBee radio modulis nav apstiprināts lietošanai (šis saraksts nav pilnīgs):
l medicīniskās ierīces l kodolprogrammas l sprādzienbīstamā vai uzliesmojošā vidē
n XBee radio moduļa iekšpusē nav neviena komponenta, ko lietotājs varētu apkopt. Nenoņemiet
vairogu un nekādā veidā nepārveidojiet XBee. Modifikācijas rezultātā modulis var tikt izslēgts no jebkādas garantijas un var izraisīt XBee radio darbību, kas neatbilst noteiktās valsts normatīvajiem aktiem, izraisot iespējamu nelegālu radio darbību.
n Strādājot ar XBee moduli, izmantojiet nozares standarta ESD aizsardzību. n Rīkojoties, rīkojieties uzmanīgi, lai izvairītos no PCB un komponentu elektriskiem bojājumiem. n Nepakļaujiet XBee radio moduļus ūdens vai mitruma iedarbībai. n Izmantojiet šo izstrādājumu ar antenām, kas norādītas XBee moduļa lietotāja rokasgrāmatās. n Galalietotājam ir jāpaskaidro, kā atvienot XBee radio moduļa strāvu vai novietot antenas 20 cm
attālumā no cilvēkiem vai dzīvniekiem.
Digi XBee® 3 Cat 1 Smart Modem User Guide
24
Page 25
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions

Saugos instrukcijos

XBee moduliai
n Negalima garantuoti, kad „XBee“ radijo modulis veiks dėl radijo ryšio, todėl jo neturėtų būti
naudojamas blokuoti saugai svarbiuose įrenginiuose, pvz., mašinose ar automobiliuose.
n XBee radijo modulis nebuvo patvirtintas naudoti (šis sąrašas nėra baigtinis):
l medicinos prietaisai l branduolinės programos l sprogioje ar degioje aplinkoje
n XBee radijo modulio viduje nėra komponentų, kuriuos vartotojas galėtų prižiūrėti. Jokiu būdu
nenuimkite skydo ir nekeiskite XBee. Dėl modifikacijų moduliui gali būti netaikoma jokia garantija, o „XBee“ radijas gali veikti ne pagal tam tikros šalies norminius reikalavimus, o tai gali sukelti neteisėtą radijo naudojimą.
n Dirbdami su XBee moduliu naudokite pramonės standartinę ESD apsaugą. n Dirbdami būkite atsargūs, kad nepažeistumėte PCB ir komponentų. n Saugokite XBee radijo modulius nuo vandens ar drėgmės. n Naudokite šį gaminį su antenomis, nurodytomis XBee modulio vartotojo vadove. n Galutiniam vartotojui turi būti paaiškinta, kaip atjungti XBee radijo modulio maitinimą arba
nustatyti antenas 20 cm atstumu nuo žmonių ar gyvūnų.

Sikkerhetsinstruksjoner

XBee-moduler
n XBee-radiomodulen kan ikke garanteres drift på grunn av radiolinken, og bør derfor ikke
brukes til forriglinger i sikkerhetskritiske enheter som maskiner eller bilapplikasjoner.
n XBee-radiomodulen er ikke godkjent for bruk i (denne listen er ikke uttømmende):
l medisinsk utstyr l kjernefysiske applikasjoner l eksplosive eller brennbare atmosfærer
n Det er ingen komponenter som kan repareres av brukeren inne i XBee-radiomodulen. Ikke
fjern skjoldet eller modifiser XBee på noen måte. Endringer kan ekskludere modulen fra enhver garanti og kan føre til at XBee-radioen fungerer utenfor regelverket for et gitt land, noe som kan føre til ulovlig drift av radioen.
n Bruk industristandard ESD-beskyttelse når du håndterer XBee-modulen. n Vær forsiktig ved håndtering for å unngå elektrisk skade på PCB og komponenter. n Ikke utsett XBee radiomoduler for vann eller fuktighet. n Bruk dette produktet med antennene spesifisert i XBee-modulens brukerveiledninger. n Sluttbrukeren må bli fortalt hvordan man fjerner strømmen fra XBee-radiomodulen eller
plasserer antennene 20 cm fra mennesker eller dyr.
Digi XBee® 3 Cat 1 Smart Modem User Guide
25
Page 26
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions

Instrukcje bezpieczeństwa

Moduły XBee
n Modułradiowy XBee nie może zagwarantować działania ze względu na łącze radiowe, dlatego
nie należy go używać do blokad w urządzeniach o krytycznym znaczeniu dla bezpieczeństwa, takich jak maszyny lub aplikacje motoryzacyjne.
n Modułradiowy XBee nie został dopuszczony do użytku w (lista ta nie jest wyczerpująca):
l wyroby medyczne l zastosowania nuklearne l atmosferach wybuchowych lub łatwopalnych
n Wewnątrz modułu radiowego XBee nie ma żadnych elementów, które mogłyby być
serwisowane przez użytkownika. Nie zdejmuj osłony ani nie modyfikuj XBee w żaden sposób. Modyfikacje mogą wykluczyć moduł z jakiejkolwiek gwarancji i spowodować, że radio XBee będzie działać niezgodnie z przepisami obowiązującymi w danym kraju, co może prowadzić do nielegalnego działania radia.
n Podczas obsługi modułu XBee należy stosować standardową ochronę ESD. n Podczas obsługi należy zachować ostrożność, aby uniknąć uszkodzeń elektrycznych PCB i
komponentów.
n Nie wystawiaj modułów radiowych XBee na działanie wody lub wilgoci. n Używaj tego produktu z antenami określonymi w podręcznikach użytkownika modułu XBee. n Użytkownik końcowy musi zostać poinformowany, jak odłączyć zasilanie modułu radiowego
XBee lub zlokalizować anteny w odległości 20 cm od ludzi lubzwierząt.

Instruções de segurança

Módulos XBee
n O módulo de rádio XBee não pode ter operação garantida devido ao link de rádio e, portanto,
não deve ser usado para intertravamentos em dispositivos críticos de segurança, como máquinas ou aplicações automotivas.
n O módulo de rádio XBee não foi aprovado para uso em (esta lista não é exaustiva):
l o dispositivos médicos l o aplicações nucleares l o atmosferas explosivas ou inflamáveis
n Não há componentes que possam ser reparados pelo usuário dentro do módulo de rádio XBee.
Não remova a blindagem nem modifique o XBee de forma alguma. As modificações podem excluir o módulo de qualquer garantia e fazer com que o rádio XBee opere fora da conformidade regulatória de um determinado país, levando à possível operação ilegal do rádio.
n Use proteção ESD padrão da indústria ao manusear o módulo XBee. n Tome cuidado ao manusear para evitar danos elétricos à PCB e aos componentes. n Não exponha os módulos de rádio XBee à água ou umidade. n Use este produto com as antenas especificadas nos guias do usuário do módulo XBee.
Digi XBee® 3 Cat 1 Smart Modem User Guide
26
Page 27
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n O usuário final deve ser informado sobre como remover a energia do módulo de rádio XBee ou
localizar as antenas a 20 cm de humanos ou animais.

Instructiuni de siguranta

module XBee
n Nu se poate garanta funcționarea modulului radio XBee din cauza conexiunii radio și, prin
urmare, nu trebuie utilizat pentru interblocări în dispozitive critice pentru siguranță, cum ar fi mașini sau aplicații auto.
n Modulul radio XBee nu a fost aprobat pentru utilizare în (această listă nu este exhaustivă):
l dispozitive medicale l aplicații nucleare l atmosfere explozive sau inflamabile
n Nu există componente care să poată fi reparate de utilizator în interiorul modulului radio XBee.
Nu îndepărtați scutul și nu modificați XBee în niciun fel. Modificările pot exclude modulul din orice garanție și pot face ca radioul XBee să funcționeze în afara conformității cu reglementările pentru o anumită țară, ceea ce duce la o posibilă funcționare ilegală a radioului.
n Folosiți protecția ESD standard în industrie când manipulați modulul XBee. n Aveți grijă în timpul manipulării pentru a evita deteriorarea electrică a PCB-ului și a
componentelor.
n Nu expuneți modulele radio XBee la apă sau umezeală. n Utilizați acest produs cu antenele specificate în ghidurile utilizatorului modulului XBee. n Utilizatorului final trebuie să i se spună cum să scoată alimentarea de la modulul radio XBee
sau să găsească antenele la 20 cm de oameni sau animale.

Bezpečnostné inštrukcie

moduly XBee
n Rádiový modulXBee nemôže byť zaručený kvôli rádiovému spojeniu, a preto by sa nemal
používať na blokovanie v zariadeniach kritických z hľadiska bezpečnosti, ako sú stroje alebo automobilové aplikácie.
n Rádiový modulXBee nebol schválený na použitie v (tento zoznam nie je úplný):
l zdravotnícke pomôcky l jadrové aplikácie l výbušné alebo horľavé atmosféry
n Vo vnútri rádiového modulu XBee sa nenachádzajú žiadne používateľsky opraviteľné
komponenty. Neodstraňujte štít ani žiadnym spôsobom neupravujte XBee. Úpravy môžu vyňať modul zo záruky a môžu spôsobiť, že rádio XBee bude fungovať mimo zhody s predpismi pre danú krajinu, čo vedie k možnej nezákonnej prevádzke rádia.
n Pri manipulácii s modulom XBee používajte štandardnú ochranu pred ESD.
Digi XBee® 3 Cat 1 Smart Modem User Guide
27
Page 28
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
n Pri manipulácii buďte opatrní, aby ste predišli elektrickému poškodeniu dosky plošných spojov
a komponentov.
n Rádiové moduly XBee nevystavujte vode ani vlhkosti. n Tento produkt používajte s anténami špecifikovanými v používateľských príručkách modulu
XBee.
n Koncový používateľ musí byť informovaný o tom, ako odpojiť napájanie rádiového modulu XBee
alebo ako umiestniť antény 20 cm od ľudí alebo zvierat.

Varnostna navodila

XBee moduli
n Radijskega modula XBee ni mogoče zagotoviti delovanja zaradi radijske povezave in ga zato ne
smete uporabljati za zaklepanje v varnostno kritičnih napravah, kot so stroji ali avtomobilske aplikacije.
n Radijski modulXBee ni bil odobren za uporabo v (ta seznam ni izčrpen):
l medicinskih pripomočkov l jedrske aplikacije l eksplozivne ali vnetljive atmosfere
n V radijskem modulu XBee ni komponent, ki bi jih lahko popravil uporabnik. Ne odstranjujte ščita
in na noben način ne spreminjajte XBee. Spremembe lahko modul izključijo iz kakršne koli garancije in lahko povzročijo, da radio XBee deluje zunaj zakonske skladnosti za dano državo, kar vodi do možnega nezakonitega delovanja radia.
n Pri ravnanju z modulom XBee uporabite standardno industrijsko zaščito pred ESD. n Pri rokovanju pazite, da se izognete električnim poškodbam tiskanega vezja in komponent. n Radijskih modulov XBee ne izpostavljajte vodi ali vlagi. n Ta izdelek uporabljajte z antenami, navedenimi v uporabniških priročnikih modula XBee. n Končnemu uporabniku je treba povedati, kako odstraniti napajanje z radijskega modula XBee
ali naj locira antene 20 cm od ljudi ali živali.

Las instrucciones de seguridad

Módulos XBee
n No se puede garantizar el funcionamiento del módulo de radio XBee debido al enlace de radio
y, por lo tanto, no debe usarse para enclavamientos en dispositivos críticos para la seguridad, como máquinas o aplicaciones automotrices.
n El módulo de radio XBee no ha sido aprobado para su uso en (esta lista no es exhaustiva):
l dispositivos médicos l aplicaciones nucleares l atmósferas explosivas o inflamables
n No hay componentes reparables por el usuario dentro del módulo de radio XBee. No quite el
escudo ni modifique el XBee de ninguna manera. Las modificaciones pueden excluir el módulo
Digi XBee® 3 Cat 1 Smart Modem User Guide
28
Page 29
Digi XBee® 3 Cat 1 Smart Modem User Guide Safety instructions
de cualquier garantía y pueden hacer que la radio XBee funcione fuera del cumplimiento normativo de un país determinado, lo que puede provocar una operación ilegal de la radio.
n Utilice la protección ESD estándar de la industria al manipular el módulo XBee. n Tenga cuidado al manipularlo para evitar daños eléctricos en la PCB y los componentes. n No exponga los módulos de radio XBee al agua ni a la humedad. n Utilice este producto con las antenas especificadas en las guías de usuario del módulo XBee. n Se debe indicar al usuario final cómo desconectar la alimentación del módulo de radio XBee o
ubicar las antenas a 20 cm de personas o animales.

Säkerhets instruktioner

XBee-moduler
n XBee-radiomodulen kan inte garanteras funktion på grund av radiolänken och bör därför inte
användas för förreglingar i säkerhetskritiska enheter som maskiner eller biltillämpningar.
n XBee-radiomodulen har inte godkänts för användning i (denna lista är inte uttömmande):
l medicinsk utrustning l kärnkraftstillämpningar l explosiv eller brandfarlig atmosfär
n Det finns inga komponenter som användaren kan reparera inuti XBee-radiomodulen. Ta inte
bort skölden eller modifiera XBee på något sätt. Ändringar kan utesluta modulen från alla garantier och kan göra att XBee-radion fungerar utanför bestämmelserna för ett visst land, vilket kan leda till att radion kan användas olagligt.
n Använd industristandard ESD-skydd när du hanterar XBee-modulen. n Var försiktig vid hanteringen för att undvika elektriska skador på kretskortet och
komponenterna.
n Utsätt inte XBee radiomoduler för vatten eller fukt. n Använd den här produkten med antennerna som specificeras i XBee-modulens användarguider. n Slutanvändaren måste informeras om hur man kopplar bort strömmen från XBee-
radiomodulen eller för att placera antennerna 20 cm från människor eller djur.
Digi XBee® 3 Cat 1 Smart Modem User Guide
29
Page 30

Get started with the XBee Smart Modem

This section describes how to connect the hardware in the XBee, 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. Determine cellular service and acquire a SIM card
3. Connect the hardware
4. Install and upgrade XCTU
5. Use one of the following methods to verify your cellular connection. You must have a SIM card
installed.
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
Digi XBee® 3 Cat 1 Smart Modem User Guide
30
Page 31
Get started with the XBee Smart Modem Identify the kit contents

Identify the kit contents

The Developer's kit includes the following:
Item Description
One XBIB-CU-TH board
Two cellular antennas with U.FL connectors
One GNSS antenna
For information about GNSS, see GNSS (Global
Navigation Satellite System).
One USB-C cable
Note This cable is used to power the
development board.
One Micro USBcable
Note This cable is used only with USBDirect
mode.
Note This cable will not power the development
board.
One XBee Smart Modem
Note When purchased as a kit, the XBee Smart
Modem comes pre-installed in the XBIB-U-C in an ESD-safe bag.
Digi XBee® 3 Cat 1 Smart Modem User Guide
31
Page 32
Get started with the XBee Smart Modem Determine cellular service and acquire a SIM card
Item Description
One SIMcard, if the device kit that you purchased includes a SIMcard.
Note If your kit does not include a SIMcard, you
can purchase your own. See Determine cellular
service and acquire a SIM card.

Determine cellular service and acquire a SIM card

You need cellular service to use your XBee. Depending on the device that you purchased, your kit may not include a SIMcard.
Note If your kit came with a SIMcard, you can skip this section. If you are interested in purchasing a
Cellular Bundled Service plan from Digi, see Cellular service.
If your kit does not include a SIM card, the following sections below explain how to purchase a SIMcard in the US and Europe.
UScustomers
In the US, Digi XBee® 3 LTE Cat 1 Smart Modem works with AT&T and Verizon (pending carrier approval). 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.

European customers

If you are using the LTE Cat 1 Smart Modem European kit, you must purchase a SIM card before you can connect the hardware. Contact your 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 your 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.
Ensure that you choose a carrier and plan that supports the technologies and bands supported by the LTE Cat 1 smart modem. Your carrier may require you to enter the APN when configuring the smart modem.
Digi XBee® 3 Cat 1 Smart Modem User Guide
32
Page 33
Get started with the XBee Smart Modem Connect the hardware

Connect the hardware

1. The XBee Smart Modem should already be plugged into the development board. For more
information about development boards, see Development boards.
2. If a SIM card is included with the kit, the card is already inserted into the XBee. If a SIM card is
not included, install the SIMcard into the XBee. You may need to remove the XBee from the carrier board to get clear access to the SIM socket.
Note Some kits do not include a SIM card. Contact your mobile carrier provider to obtain a SIM
card and service. See Determine cellular service and acquire a SIM card.
3. Connect the antennas.
Align the U.FL connectors carefully, then firmly press straight down to seat the connector. You should hear or feel a click when the antenna attaches correctly. Caution should be used when connecting or removing the U.FL. Digi recommends using a U.FL removal tool.
Digi XBee® 3 Cat 1 Smart Modem User Guide
33
Page 34
Get started with the XBee Smart Modem Install and upgrade XCTU
a. Connect the cellular antennas. b. Connect the GNSS antenna. For information about this antenna, see Antenna
recommendations.
4. Connect the USB-C 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.
Note The USB-C cable must be plugged into a port that will supply a minimum of 1 Amp of
current for the device to work as expected.

Install and upgrade XCTU

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. You can use XCTU to update the device firmware, and if needed, XCTU will attempt to update your
cellular firmware. Firmware is the program code stored in the device's persistent memory that provides the control program for the device.
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.
Step 1: Install and upgrade XCTU
You can use XCTU to update the device 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 the latest version. This step is required.
Step 2: Add a device to XCTU
You must add a device to XCTU before you can update the device's firmware or configure the device from XCTU.

Add a device to XCTU

These instructions show you how to add the XBee to XCTU. If XCTU does not find your serial port, see Cannot find the serial port for the device and Enable Virtual
COM port (VCP) on the driver.
1.
Launch XCTU .
Note XCTU's Update the radio module firmware dialog box may open and will not allow you
to continue until you click Update or Cancel on the dialog.
2. Click Help > Check for XCTUUpdates to ensure you are using the latest version of XCTU.
3.
Click the Discover radio modules button in the upper left side of the XCTU screen.
Digi XBee® 3 Cat 1 Smart Modem User Guide
34
Page 35
Get started with the XBee Smart Modem Update the device and cellular firmware using XCTU
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 the device and cellular firmware using XCTU

You should use XCTU to update the device firmware on your XBee 3 to the most recent version. This ensures that you can take advantage of all the latest fixes and features. XCTU will update the device firmware, and if needed, XCTU will attempt to update your cellular modem firmware. Upgrading the cellular modem component firmware requires USBDirect.
Update the device and cellular firmware using XCTU and USBDirect access.

Check for cellular registration and connection

The cellular network registration and address assignment must occur successfully. To verify the network connection, you can view the LED on the development board or check the status of the relevant commands in XCTU.
Registration can take several minutes.
Before you begin
n A working SIMcard is required. See Determine cellular service and acquire a SIM card. n Make sure you have added the device to XCTU. See Add a device to XCTU. n Make sure you are in an area with adequate cellular network reception. n Verify that the antennas are connected properly to the device.
View LED action
The LED on the development board blinks when the XBee is registered to the cellular network; see
Associate LED functionality. If the LEDremains solid, registration has not occurred properly.
View commands in XCTU
1.
Launch XCTU .
2.
Click the Configuration working mode button.
3. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
4. Verify the status of your network connection using the following commands:
n AI (Association Indication) reads 0 when the device successfully registers to the
cellular network and the LED is blinking. 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 XBee® 3 Cat 1 Smart Modem User Guide
35
Page 36
Get started with the XBee Smart Modem Cellular service
Hints
n
To search for an ATcommand in XCTU, use the search box .
n
To read a command's value, click the Read button next to the command.

Cellular service

Digi now offers Cellular Bundled Service plans, where you can choose to purchase a subscription for cell service, and/or a Digi Remote Manager package.
To shop online, go to: shop.digi.com 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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
36
Page 37

XBee connection examples

The following examples provide some additional scenarios you can try to get familiar with the XBee. 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 38 Connect to the ELIZA server 40 Connect to the Daytime server 42 Send an SMS message to a phone 44 Perform a (GET) HTTP request 46 Connect to a TCP/IP address 48 Software libraries 48
Digi XBee® 3 Cat 1 Smart Modem User Guide
37
Page 38
XBee connection examples Connect to the Echo server

Connect to the Echo server

This server echoes back the messages you type.
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)
TD
(Text
Delimiter)
DL
(Destination Address)
DE
(Destination Port)
To communicate with the Echo server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
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.
D (0x0D)
52.43.121.77 The target IPaddress of the echo server.
2329 (0x2329) The target port number of the echo server.
The text delimiter to be used for Transparent mode, as an ASCII hex code. No information is sent until this character is entered, unless the maximum number of characters has been reached. Set to 0 to disable text delimiter checking. Set to D for a carriage return.
5.
To switch to TCP communication, in the IP field, select 1 and click the Write button .
6. To enable the XBee 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.
9.
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 XBee® 3 Cat 1 Smart Modem User Guide
38
Page 39
XBee connection examples Connect to the Echo server
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 XBee® 3 Cat 1 Smart Modem User Guide
39
Page 40
XBee connection examples Connect to the ELIZA server

Connect to the ELIZA server

You can use the XBee 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) 1 Set the expected transmission mode to TCP
communications.
DL (Destination Address)
DE (Destination Port) 2328 (0x2328) The target port number of the ELIZA server.
To communicate with the ELIZA Therapist Bot:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
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 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.
8.
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.
9.
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.
52.43.121.77 The target IP address of the ELIZA server.
Digi XBee® 3 Cat 1 Smart Modem User Guide
40
Page 41
XBee connection examples Connect to the ELIZA server
Digi XBee® 3 Cat 1 Smart Modem User Guide
41
Page 42
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)
DL
(Destination Address)
DE
(Destination Port)
TD (Text Delimiter)
To communicate with the Daytime server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
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.
232A (0x232A) The target port number of the Daytime server.
0
The text delimiter to be used for Transparent mode, as an ASCII hex code. No information is sent until this character is entered, unless the maximum number of characters has been reached. Set to zero to disable text delimiter checking.
5.
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.
9.
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 query the Daytime server. The following screenshot provides an example of this chat.
Digi XBee® 3 Cat 1 Smart Modem User Guide
42
Page 43
XBee connection examples Connect to the Daytime server
Digi XBee® 3 Cat 1 Smart Modem User Guide
43
Page 44
XBee connection examples Send an SMS message to a phone

Send an SMS message to a phone

The XBee Smart Modem can send and receive Short Message Service (SMS) transmissions (text messages) while in Transparent mode. This allows you to send and receive text messages to and from an SMS capable device such as a mobile phone.
Note For help with debugging, see Debugging.
The following table explains the AT commands that you use in this example.
Command Value Description
AP (APIEnable)
IP (IP Protocol)
P#
(DestinationPhone Number)
TD (Text Delimiter)
PH (Module's SIM
phone number)
1. Ensure that the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working mode button.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for that device.
0 Set the device's API mode to Transparent mode.
2 Set the expected transmission mode to SMScommunication.
<Target phone number>
D (0x0D)
Read only The value that represents your device's phone number as
The target phone number that you send to, for example, your cellular phone. See P# (Destination Phone Number) for instructions on using this command.
The text delimiter to be used for Transparent mode, as an ASCII hex code. No information is sent until this character is entered, unless the maximum number of characters has been reached. Set to 0 to disable text delimiter checking. Set to D for a carriage return.
supplied by the SIM card. This is used to send text messages to the device from another cellular device.
5.
To switch to SMS communication, in the IP field, select 2 and click the Write button .
6. To enter your cell phone number, in the P# field, type the <target phone number> and click the Write button. Type the phone number using only numbers, with no dashes. You can use the + prefix if necessary. The target phone number is the phone number you wish to send a text to.
7. In the TD field, type D and click the Write button.
8. Note the number in the PH field; it is the XBee Smart Modem phone number, which you see when it sends an SMS to your phone.
9.
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 XBee® 3 Cat 1 Smart Modem User Guide
44
Page 45
XBee connection examples Send an SMS message to a phone
11. Click in the left pane of the Console log, type hello world and press Enter. The XBee Smart Modem sends the message to the destination phone number set by the P# command.
Note If you are receiving individual characters, verify that you set TD correctly.
12. When the phone receives the text, you can see that the sender's phone number matches the value reported by the XBee Smart Modem with the PH command.
13. On the phone, reply with the text connect with confidence and the XBee Smart Modem outputs this reply from the UART.
Digi XBee® 3 Cat 1 Smart Modem User Guide
45
Page 46
XBee connection examples Perform a (GET) HTTP request

Perform a (GET) HTTP request

You can use the XBee 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 to XCTU.
3.
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 XBee® 3 Cat 1 Smart Modem User Guide
46
Page 47
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 XBee® 3 Cat 1 Smart Modem User Guide
47
Page 48
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)
DL
(Destination IPAddress)
DE
(Destination Port)
To connect to a TCP/IP address:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
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.
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.
<Target IPaddress>
<Target portnumber>
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.

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:
Digi XBee® 3 Cat 1 Smart Modem User Guide
48
Page 49
XBee connection examples Software libraries
n XBee Java library n XBee Python library n XBee ANSI C 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 XBee® 3 Cat 1 Smart Modem User Guide
49
Page 50

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 51 MicroPython on the XBee Smart Modem 51 Use XCTU to enter the MicroPython environment 51 Use the MicroPython Terminal in XCTU 52 Example: hello world 52 Example: Turn on an LED 52 Example: code a request help button 53 Example: debug the secondary UART 58 Exit MicroPython mode 58 Other terminal programs 59 Use picocom in Linux 60
Digi XBee® 3 Cat 1 Smart Modem User Guide
50
Page 51
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 Install and upgrade XCTU. n You have a terminal program installed on your computer. We recommend using the Use the
MicroPython Terminal in XCTU. This requires XCTU 6.3.7 or higher.
n You have an XBee Smart Modem installed in an appropriate development board, such as an
XBIB-U-DEV.
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.

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 Install and upgrade XCTU and Add a device to XCTU.
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. Put the XBee Smart Modem into MicroPython mode, in the APfield select MicroPython REPL
[4] and click the Write button .
5. 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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
51
Page 52
Get started with MicroPython Use the MicroPython Terminal in XCTU

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:
1.
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.
3.
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 to XCTU.
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

Note This example is only for kits that use the XBIB-CU-TH development board. For an example that
uses the XBIB-U-DEV development board, see Example: Turn on an LED.
1
See Other terminal programs if you do not use the MicroPython Terminal in XCTU.
Digi XBee® 3 Cat 1 Smart Modem User Guide
52
Page 53
Get started with MicroPython Example: code a request help button
1. Note the DIO10 LED on the XBIB board. The following image highlights it in a red box. The LED is normally off.
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.
from machine import Pin led = Pin("D10", Pin.OUT, value=1) # Makes a pin object set to output 1.
3. To turn it off, type the following and press Enter:
led.value(0)
You have successfully controlled an LED on the board using basic I/O.

Example: code a request help button

This example provides a fast, deep dive into MicroPython designed to let you see some of the powerful things it can do with minimal code. It is not meant as a tutorial; for in-depth examples refer to the Digi
MicroPython Programming Guide.
Many stores have help buttons in their aisles that a customer can press to alert the store staff that assistance is required in that aisle. You can implement this type of system using the Digi XBee Smart Modem, and this example provides the building blocks for such a system. This example, based on SMS paging, can have many other uses such as alerting someone with a text to their phone if a water sensor in a building detects water on the floor, or if a temperature sensor reports a value that is too hot or cold relative to normal operation.
Digi XBee® 3 Cat 1 Smart Modem User Guide
53
Page 54
Get started with MicroPython Example: code a request help button

Enter MicroPython paste mode

In the following examples it is helpful to know that MicroPython supports paste mode, where you can copy a large block of code from this user guide and paste it instead of typing it character by character. To use paste mode:
1. Copy the code you want to run. For this example, copy the following code that is the code from the previous LED (Example: Turn on an LED) example:
from machine import Pin led = Pin("D10", Pin.OUT, value=1)
Note You can easily copy and paste code from the online version of this guide. Use caution with the
PDF version, as it may not maintain essential indentations.
2. Paste the copied code. Press CTRL +Shift + V or right-click in the Terminal and select Paste.
3. In the terminal, at the MicroPython >>> prompt type Ctrl+E to enter paste mode. The terminal displays paste mode; Ctrl-C to cancel, Ctrl-D to finish.
4. The code appears in the terminal occupying multiple lines, where each line starts with its line number and three = symbols. For example line 1 starts with 1===.
5. If the code is correct, press Ctrl+D to run the code and you should once again see the DIO10 LED turn on. If you get a Line 1 SyntaxError: invalid syntax error, see Syntax error at line 1. Additionally, if you want to exit paste mode without running the code, for example, or if the code did not copy correctly, press Ctrl+C to cancel and return to the normal MicroPython >>> prompt.
6. Next turn the LED off. Copy the code below:
from machine import Pin led = Pin("D10", Pin.OUT, value=1) print("DIO10 LED now OFF!") print("Paste Mode Successful!")
7. Press Ctrl+E to enter paste mode.
8. Press Ctrl + Shift + V or right-click in the Terminal and select Paste to paste the copied code.
9. If the code is correct, press Ctrl+D to run it. The LED should turn off and you should see two confirmation messages print to the screen.

Catch a button press

For this part of the example, you write code that responds to a button press on the XBIB-CU-TH-DEV board that comes with the XBee Smart Modem Development Kit. The code monitors the pin connected to the button on the board labeled Comm.
Digi XBee® 3 Cat 1 Smart Modem User Guide
54
Page 55
Get started with MicroPython Example: code a request help button
On the board you see DIO0 written below Comm, to the left of the button. This represents the pin that the button is connected to.
In MicroPython, you will create a pin object for the pin that is connected to the Comm button. When you create the pin object, the DIO0 pin is called D0 for short.
The loop continuously checks the value on that pin and once it goes to 0 (meaning the button has been pressed) a print() call prints the message Button pressed! to the screen.
At the MicroPython >>> prompt, copy the following code and enter it into MicroPython using paste
mode (Ctrl+E), right-click in the Terminal, select Paste to paste the copied code, and press Ctrl+D to
run the code.
# Import the Pin module from machine, for simpler syntax. from machine import Pin
# Create a pin object for the pin that the button "DIO0" is connected to. dio0 = Pin("D0", Pin.IN, Pin.PULL_UP) # Give feedback to inform user a button press is needed. print("Waiting for DIO0 press...") # Create a WHILE loop that checks for a button press. while (True):
if (dio0.value() == 0): # Once pressed.
print("Button pressed!") # Print message once pressed. break # Exit the WHILE loop.
# When you press DIO0, you should see "Button pressed!" printed to the screen. # You have successfully performed an action in response to a button press!
Note You can easily copy and paste code from the online version of this guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.
Digi XBee® 3 Cat 1 Smart Modem User Guide
55
Page 56
Get started with MicroPython Example: code a request help button

Send a text (SMS) when the button is pressed

After creating a while loopthat checks for a button press, add sending an SMS to your code. Instead of printing Button pressed! to the screen, this code sends Button pressed to a cell phone as a text (SMS) message.
To accomplish this, use the sms_send() method, which sends a string to a given phone number. It takes the arguments in the following order:
1. <phone number>
2. <message-to-be-sent>
Before you run this part of the example, you must create a variable that holds the phone number of the cell phone or mobile device you want to receive the SMS.
1. To do this, at the MicroPython >>> prompt, type the following command, replacing 1123456789 with the full phone number (no dashes, spaces, or other symbols) and press Enter:
ph = 1123456789
2. After you create this ph variable with your phone number, copy the code below and enter it into MicroPython using paste mode (Ctrl+E) and then run it.
from machine import Pin import network # Import network module import time
c = network.Cellular() # initialize cellular network parameter dio0 = Pin("D0", Pin.IN, Pin.PULL_UP) while not c.isconnected(): # While no network connection.
print("Waiting for connection to cell network...")
time.sleep(5) print("Connected.") # Give feedback to inform user a button press is needed. print(Waiting for DIO0 press...") while (True):
if (dio0.value() == 0)
# When DIO0 is pressed, the module will send an SMS # message saying "Button pressed" to the given target cell phone
number.
try:
c.sms_send(ph, 'Button Pressed') print("Sent SMS successfully.")
except OSError:
print("ERROR- failed to send SMS.") # Exit the WHILE loop. break
Note You can easily copy and paste code from the online version of this guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.
Digi XBee® 3 Cat 1 Smart Modem User Guide
56
Page 57
Get started with MicroPython Example: code a request help button

Add the time the button was pressed

After you add the ability to send an SMS to the code, add functionality to insert the time at which the button was pressed into the SMS that is sent. To accomplish this:
1. Create a UDP socket with the socket() method.
2. Save the IP address and port of the time server in the addr variable.
3. Connect to the time server with the connect() method.
4. Send hello to the server to prompt it to respond with the current date and time.
5. Receive and store the date/time response in the buf variable.
6. Send an SMSin the same manner as before using the sms_send() method, except that you add the time into the SMS message, such that the message reads: [Button pressed at: YYYY-MM-
DD HH:MM:SS]
To verify that your phone number is still in the memory, at the MicroPython >>> prompt, type ph and press Enter.
If MicroPython responds with your number, copy the following code and enter it into MicroPython using paste mode and then run it. If it returns an error, enter your number again as shown in Send a
text (SMS) when the button is pressed. With your phone number in memory in the ph variable, copy
the code below and enter it into MicroPython using paste mode (Ctrl+E) and then run it.
from machine import Pin import network import usocket import time
c = network.Cellular() dio0 = Pin("D0", Pin.IN, Pin.PULL_UP) while not c.isconnected(): # While no network connection.
print("Waiting for connection to cell network...")
time.sleep(5) print("Connected.") # Give feedback to inform user a button press is needed. print ("Waiting for DIO0 press...") while (1):
if (dio0.value() == 0):
# When button pressed, now the module will send "Button Press" AND # the time at which it was pressed in an SMS message to the given # target cell phone number. socketObject = usocket.socket(usocket.AF_INET, usocket.SOCK_DGRAM) # Connect the socket object to the web server specified in
"address".
addr = ("52.43.121.77", 10002) socketObject.connect(addr) bytessent = socketObject.send("hello") print("Sent %d bytes on socket" % bytessent) buf = socketObject.recv(1024) # Send message to the given number. Handle error if it occurs. try:
c.sms_send(ph, 'Button Pressed at: ' + str(buf)) print("Sent SMS successfully.")
except OSError:
print("ERROR- failed to send SMS.") # Exit the WHILE loop. break
Digi XBee® 3 Cat 1 Smart Modem User Guide
57
Page 58
Get started with MicroPython Example: debug the secondary UART
Note You can easily copy and paste code from the online version of this guide. Use caution with the
PDF version, as it may not maintain essential indentations.
Now you have a system based on the XBee Smart Modem that sends an SMS in response to a certain input, in this case a simple button press.
Note If you have problems pasting the code, see Syntax error at line 1. For SMS failures, see Error
Failed to send SMS.

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.
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:
1.
In the XCTU MicroPython Terminal, click the green Close button .
2. Click Close at the bottom of the terminal to exit the terminal.
3.
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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
58
Page 59
Get started with MicroPython Other terminal programs

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 PuTTY for Windows n Picocom for Linux. See https://developer.ridgerun.com/wiki/index.php/Setting_up_Picocom_-_
Ubuntu and for the source code and in-depth information https://github.com/npat­efault/picocom.

Tera Term for Windows

With the XBee Smart Modem in MicroPython mode (AP = 4), you can access the MicroPython prompt using a terminal.
1. Open Tera Term. The Tera Term: New connection window appears.
2. Click the Serial radio button to select a serial connection.
3. From the Port: drop-down menu, select the COM port that the XBee Smart Modem is connected to.
4. Click OK. The COMxx - Tera Term VT terminal window appears and Tera Term attempts to connect to the device at a baud rate of 9600 b/s.
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:9600 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:
Digi XBee® 3 Cat 1 Smart Modem User Guide
59
Page 60
Get started with MicroPython Use picocom in Linux
a. In Tera Term, click Setup and select Terminal. b. In the New-line area of the Tera Term: Serial port setup window, click the Receive drop-
down menu and select CR if it does not already show that value.
c. Make sure the Local echo box is not checked.
9. Click OK.
10. Press Ctrl+B to get the MicroPython version banner and prompt.
Now you can type MicroPython commands at the >>> prompt.

Use picocom in Linux

With the XBee Smart Modem in MicroPython mode (AP = 4), you can access the MicroPython prompt using a terminal.
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 9600 /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 XBee® 3 Cat 1 Smart Modem User Guide
60
Page 61
Get started with MicroPython Use picocom in Linux
Now you can type MicroPython commands at the >>> prompt.
Digi XBee® 3 Cat 1 Smart Modem User Guide
61
Page 62

Get started with Bluetooth® Low Energy

BLE (Bluetooth® Low Energy) is an RF protocol that enables you to connect your XBee (server) device to another (client) device. he latest Digi XBee products include a dual-mode radio that allows the device to communicate through the BLE interface and the RF/Cellular network at the same time.
The XBee acts as a BLE GATT server and allows client devices, such as a cellphone or a third-party BLEdevice such as the Nordic nRF and SiLabs BGM, to configure the XBee or transfer data with the User Data Relay frame using the XBee API BLEService.
The XBee does not support modifying the XBee's GATT database. This means that the XBee cannot be configured to appear as something else, such as a temperature sensor.

On XBee 3 Cellular firmware ending in x16 or newer

The XBee supports the following BLE features:
n BLE pairing and bonding support for GATT client connections. n Ability to authenticate and communicate as a BLE client to other XBee3 devices using the Digi
BLE service.

Enable BLE on an XBee device

This process explains how to enable BLEon your XBee 3 device and verify the connection.
1. Set up your XBee device. See Get started with the XBee Smart Modem.
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. To ensure that BLE is always enabled,
you can create a custom configuration that is used as a new factory default. See Custom
configuration: Create a new factory default.
Enable BLEand configure the BLEpassword using XCTU
Some of the latest XBee 3 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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
62
Page 63
Get started with Bluetooth® Low Energy Get the Digi XBeeMobile phone application
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 Bitwarden 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.
1.
Launch XCTU .
2.
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.
5.
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.
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
Digi XBee® 3 Cat 1 Smart Modem User Guide
63
Page 64
Get started with Bluetooth® Low Energy Connect with BLEand configure your XBee device
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.
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.
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 n User Data Relay - 0x2D
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:
Digi XBee® 3 Cat 1 Smart Modem User Guide
64
Page 65
Get started with Bluetooth® Low Energy BLE reference
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.
After connecting, you must perform the unlock process to authenticate the client. If the unlock process has not been completed successfully, allother API frames will be silently ignored and not processed.

API Response characteristic

UUID: f9279ee9-2cd0-410c-81cc-adf11e4e5aea Permissions: Readable, Indicate
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 XBee® 3 Cat 1 Smart Modem User Guide
65
Page 66

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.
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 the Devices page in 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:
o
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
using automations.
o
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.
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
Digi XBee® 3 Cat 1 Smart Modem User Guide
66
Page 67
Get started with Digi Remote Manager Create a Remote Manager account and add devices

Create a Remote Manager account

Digi Remote Manager is an on-demand service with no infrastructure requirements. Remote devices and enterprise business applications connect to Remote Manager through standards-based web services. This section describes how to configure and manage an XBee using Remote Manager. For detailed information on using Remote Manager, refer to the Remote Manager User Guide, available via the Documentation tab in Remote Manager.
Before you can manage an XBee with Remote Manager, you must create a Remote Manager account. To create a Remote Manager account:
1. Go to https://www.digi.com/products/iot-software-services/digi-remote-manager.
2. Click 90 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.
To add an XBee to your Remote Manager account inventory, follow these steps:
1. Log into Remote Manager.
2. Click Devices.
3. Click Add.
4. In the Device ID, MAC Address or IMEI field, type or paste the IMEI number of the XBee you want to add.
5. Click Add Device to add the device. The XBee is added to your inventory.

Verify the connection between a device and Remote Manager

By default, the XBee is configured to enable communication with Remote Manager. The communication between XBee and Remote Manager is achieved using periodic UDP operations.
You should verify the default settings to ensure that communcation will work as desired.
1.
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.
5. To ensure that the device is connected to Remote Manager, you must send an SM/UDP request.
a. Log into Remote Manager. b. Click Devices in the left pane.
Digi XBee® 3 Cat 1 Smart Modem User Guide
67
Page 68
Get started with Digi Remote Manager Configure Remote Manager features using automations
c. Select the device that you want to work with. d. From the right pane, click Actions and then SM/UDPRequest Connect. e. If you would like a response, enable Request Response.
f. Click Request Connect. When the connection is made, the Connection Status icon next to
the device on the Devices page turns green.

Configure Remote Manager features using automations

Remote Manager provides tools to perform common management and maintenance tasks on your XBee device. Remote Manager automations are a sequence of commands that can be performed on one or more XBee Cellular devices. When an automation 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 all features to be available. See Update
the firmware.
Some typical examples of useful things that can be done with automations s 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
Automations can be created and performed through the following methods:
n Remote Manager Automations 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 an automation

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 Automations.
Digi XBee® 3 Cat 1 Smart Modem User Guide
68
Page 69
Get started with Digi Remote Manager Automation examples
4. Click Create to launch the wizard.
5. In the Details section: a. In the Name field, enter a descriptive name for the automation, such as "Connect devices". b. Click Save and Continue.
6. In the Steps section: a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Add other steps as needed. For examples, refer to the Automation examples section. d. Click + to add a step, and select Disconnect. e. Click Save and Continue.
7. In the Targets section, click Skip to skip this section.
8. In the Triggers section, click Skip to skip this section.
9. Start the automation on a set of devices. a. Click Automations to show the list of available automations. b. Select the automation that you just created.
c. Click Action > Run Automation. The Run Automations window displays. d. Click the Devices tab. e. Select all of the devices you want to run the automation on.
f. Click Confirm to start the automation.

Automation examples

The examples in the following sections assume you are using the Digi Remote Manager Automations 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.
Note You must upgrade your device to the latest firmware for all features to be available. See Update
the firmware.
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 Automations.
3. Click Create to launch the wizard.
4. In the Details section: a. In the Name field, enter a descriptive name for the automation, such as "Read Settings". b. Click Save and Continue.
Digi XBee® 3 Cat 1 Smart Modem User Guide
69
Page 70
Get started with Digi Remote Manager Automation examples
5. In the Steps section: a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Click + again to add another step, and select RCI.
i. In the RCI Payload field, enter:
<query_setting/>
ii. Enable Allow Offline. d. Click + to add a step, and select Disconnect. e. Click Save and Continue.
6. In the Targets section, click Skip to skip this section.
7. In the Triggers section, click Skip to skip this section.
8. Start the automation on a set of devices. a. Click Automations to show the list of available automations. b. Select the automation that you just created.
c. Click Action > Run Automation. The Run Automations window displays. d. Click the Devices tab. e. Select all of the devices you want to run the automation on.
f. Click Confirm to start the automation.
9. Verify the results of running the automation. a. Click Automations to show the list of automations. b. Click on the name of the automation you just ran to display the status window.
c. Click the Runs tab to see all of the runs for this automation. d. Click on the run you are interested in to display a details for each device. e. For the device you are interested in, click the Status link under the Summary column to
see more details and the responses.
If the status was successful, you can to see the response of the RCI query by clicking Show Details. 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 all features to be available. See Update
the firmware.
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 Automations.
3. Click Create to launch the wizard.
Digi XBee® 3 Cat 1 Smart Modem User Guide
70
Page 71
Get started with Digi Remote Manager Automation examples
4. In the Details section: a. In the Name field, enter a descriptive name for the automation, such as "Set Settings". b. Click Save and Continue.
5. In the Steps section: a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Click + again to add another step, and select RCI.
i. In the RCI Payload field, enter:
<set_setting>
<remote_manager>
<DF>360</DF>
</remote_manager>
</set_setting>
ii. Enable Allow Offline. d. Click + to add a step, and select Disconnect. e. Click Save and Continue.
6. In the Targets section, click Skip to skip this section.
7. In the Triggers section, click Skip to skip this section.
8. Start the automation on a set of devices. a. Click Automations to show the list of available automations. b. Select the automation that you just created.
c. Click Action > Run Automation. The Run Automations window displays. d. Click the Devices tab. e. Select all of the devices you want to run the automation on.
f. Click Confirm to start the automation.
9. Verify the results of running the automation. a. Click Automations to show the list of automations. b. Click on the name of the automation you just ran to display the status window.
c. Click the Runs tab to see all of the runs for this automation. d. Click on the run you are interested in to display a details for each device. e. For the device you are interested in, click the Status link under the Summary column to
see more details and the responses.
Example: Schedule an automation to update the device firmware using Remote Manager
You can use an automation 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 XBee® 3 Cat 1 Smart Modem User Guide
71
Page 72
Get started with Digi Remote Manager Automation examples
Note You must upgrade your device to the latest firmware for all features to be available. See Update
the firmware.
To upgrade using an automation, perform the following steps:
1. Log into Remote Manager.
2. Make sure that you have enabled SM/UDP. See Enable SM/UDP.
3. Click Automations.
4. Click Create to launch the wizard.
5. In the Details section: a. In the Name field, enter a descriptive name for the automation, such as "Firmware
update".
b. Click Save and Continue.
6. In the Steps section: a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Click + again to add another step, and select Update Firmware.
i. From the Device Type list box, select the device type.
ii. From the Firmware Version list box, select the version of the firmware to which you
want to update the device. d. Click + to add a step, and select Disconnect. e. Click Save and Continue.
7. In the Targets section, click Skip to skip this section.
8. In the Triggers section, click Skip to skip this section.
9. Start the automation on a set of devices. a. Click Automations to show the list of available automations. b. Select the automation that you just created.
c. Click Action > Run Automation. The Run Automations window displays. d. Click the Devices tab. e. Select all of the devices you want to run the automation on.
f. Click Confirm to start the automation.
10. Verify the results of running the automation. a. Click Automations to show the list of automations. b. Click on the name of the automation you just ran to display the status window.
c. Click the Runs tab to see all of the runs for this automation. d. Click on the run you are interested in to display a details for each device. e. For the device you are interested in, click the Status link under the Summary column to
see more details and the responses.
Digi XBee® 3 Cat 1 Smart Modem User Guide
72
Page 73
Get started with Digi Remote Manager Automation examples

Example: Update MicroPython from Remote Manager using an automation

You can create an automation 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.
1. Log into Remote Manager.
2. Make sure that SM/UDPis enabled. See Enable SM/UDP.
3. Click Automations.
4. Click Create to launch the wizard.
5. In the Details section: a. In the Name field, enter a descriptive name for the automation, such as "Update
application".
b. Click Save and Continue.
6. In the Steps section: a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Click + again to add another step, and select RCI.
i. In the RCI Payload field, enter:
<set_setting>
<remote_manager>
<MO>7</MO>
</remote_manager>
</set_setting>
ii. Enable Allow Offline.
iii. From the On Error list box, select Continue.
This step disables the MicroPython application so the MicroPython files can be updated, and configures the device to keep the connection open to remote manager.
d. Click + again to add another step, and select Reboot.
i. Enable Allow Offline.
ii. From the On Error list box, select Continue.
e. Click + again to add another step, and select Upload Files.
i. From the Choose File list box, select main.py from the FTPsample application.
ii. In the Destination File Path field, enter: ~/MicroPython/main.py iii. Enable Allow Offline. iv. From the On Error list box, select Continue.
f. Click + again to add another step, and select Upload Files.
i. From the Choose File list box, select the uftp.py file from the FTP sample application.
ii. In the Destination File Path field, enter: ~/MicroPython/uftp.py iii. Enable Allow Offline. iv. From the On Error list box, select Continue.
g. Click + again to add another step, and select RCI.
Digi XBee® 3 Cat 1 Smart Modem User Guide
73
Page 74
Get started with Digi Remote Manager Manage data in Remote Manager
i. In the RCI Payload field, enter:
<set_setting>
<micrpython>
<PS>1<//PS> </micropython> <remote_manager>
<MO>6</MO>
</remote_manager>
</set_setting>
ii. Enable Allow Offline.
iii. From the On Error list box, select Continue.
h. Click + again to add another step, and select Reboot.
i. Enable Allow Offline.
ii. From the On Error list box, select Continue. i. Click + to add a step, and select Disconnect. j. Click Save and Continue.
7. In the Targets section, click Skip to skip this section.
8. In the Triggers section, click Skip to skip this section.
9. Start the automation on a set of devices. a. Click Automations to show the list of available automations. b. Select the automation that you just created.
c. Click Action > Run Automation. The Run Automations window displays. d. Click the Devices tab. e. Select all of the devices you want to run the automation on.
f. Click Confirm to start the automation.
10. Verify the results of running the automation. a. Click Automations to show the list of automations. b. Click on the name of the automation you just ran to display the status window.
c. Click the Runs tab to see all of the runs for this automation. d. Click on the run you are interested in to display a details for each device. e. For the device you are interested in, click the Status link under the Summary column to
see more details and the responses.

Manage data in Remote Manager

You can view and manage XBee 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.
1. Set up a persistent connection to connect the device to Remote Manager using one of the following methods:
Digi XBee® 3 Cat 1 Smart Modem User Guide
74
Page 75
Get started with Digi Remote Manager Manage data in Remote Manager
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
Set up a 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 Devices.
4. Select the device that you want to configure.
5. Click Settings and expand Config.
6. Click on the setting group that has information you want to display. The setting 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
7. When all changes are complete, disconnect the device from Remote Manager.

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.
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.
Device Files view
You can upload and manage files in the Remote Manager Device Files view.
1. Log into Remote Manager.
2. Click Devices.
3. Select the device for which you want to manage files.
4. Click Files to open file management view. From this view you can add or remove files on your device.
Digi XBee® 3 Cat 1 Smart Modem User Guide
75
Page 76
Get started with Digi Remote Manager Remote Manager reference

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.
Note Battery Operated Mode may be enabled in Digi Remote Manager. Review the Battery Operated
Mode section to determine the impact of enabling this mode on SM/UDP.
1. Log into Remote Manager.
2. Click Devices.
3. Select the device that you want to configure.
4. Click Details.
5. From the Actions list box, choose Configure SM/UDP.
6. Click Enable.

TCP connection

The TCP connection between an XBee and Remote Manager is dependent on the device's firmware version. Options are to query Remote Manager once a day or to maintain a persistent TCP connection.
To determine which connection method is being used, refer to the version listed below.
Module Upgrade firmware version
XBee 3 CAT 1 31011
n At or above the listed version: If your firmware version is at or above the listed version, your
device queries Remote Manager only once a day. The device connects to Remote Manager, queries Remote Manager for updates and then receives updates. When the update is complete, the device disconnects from Remote Manager.
If you upgrade 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: Schedule an automation to update the device firmware using Remote Manager.
Note If you wish to restore the persistent connection behavior that was the default in prior
firmware versions, see Set up a persistent connection to a remote XBee.
n Below the listed version: If your firmware version is below the listed version, a persistent
TCPconnection is used by default. The device is continually connected to Remote Manager using TCP.
Set up a persistent connection to a remote XBee
The default connectivity to Remote Manager 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 set up a persistent connection, 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 for MO is 7 to connect securely over TLS, or you can use 1 for no security, which is the legacy value.
Digi XBee® 3 Cat 1 Smart Modem User Guide
76
Page 77
Get started with Digi Remote Manager Remote Manager reference
You can make the change using one of the following methods:
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.
To set up an automation to enable a persistent connection:
1. Log into Remote Manager.
2. Make sure that you have enabled SM/UDP. See Enable SM/UDP.
3. Click Automations.
4. Click Create to launch the wizard.
5. In the Details section:
a. In the Name field, enter a descriptive name for the automation, such as "Enable persistent
connection."
b. Click Save and continue.
6. In the Steps section:
a. Click the garbage icon to delete any existing steps. b. Click + to add a step, and select SM/UDP Request Connect.
c. Click + again to add another setp, and select RCI.
d. In the RCI Payload field, enter:
<set_setting>
<remote_manager>
<MO>7</MO>
</remote_manager>
</set_setting>
e. Enable Allow Offline.
f. Click Save and continue.
7. In the Targets section, click Skip to skip this section.
8. In the Triggers section, click Skip to skip this section.

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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
77
Page 78
Get started with Digi Remote Manager Remote Manager reference

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.
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
Set up a 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. See DO (Device
Options) and MO (Remote Manager Options). Both must be enabled.
2. Log into Remote Manager.
3. Click Devices.
4. Select the device that you want to configure.
5. Click Settings > Config.
6. Click on the settings category that you want to configure. The settings in that category appear.
7. Makethe desired configuration changes. See AT commands for information about each setting in the categories.
8. 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.
9. When all changes are complete, disconnect the device from Remote Manager.
Configure Remote Manager keepalive interval
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.
Digi XBee® 3 Cat 1 Smart Modem User Guide
78
Page 79
Get started with Digi Remote Manager Remote Manager reference
When the device receives an SMS message, it examines the message. If the phone number matches and content contains the correct service ID, it is 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.
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
Set up a 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. See DO (Device
Options) and MO (Remote Manager Options). Both must be enabled.
2. Log in to Remote Manager.
3. Click Devices.
4. Select the device that you want to configure.
5. Click Details.
6. Click Action > Configure SMS.
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 More Options section.
n If you are using SMS in the United States only, make sure the Server Phone is 32075
and the Server Keyword is idgp. These are the default values allowed by the device.
n If you are using SMS outside of the United States, enter the following:
l Server Phone: 447537431797 l Server Keyword: idgp .
Because Server Phone is not the default used by the device, you must also update the DP (Remote Manager Phone Number) setting and RI (Remote Manager Service
ID) setting on the device so that they match the Server Phone and Server Keyword
settings.
9. Click Save.
Digi XBee® 3 Cat 1 Smart Modem User Guide
79
Page 80

Examples: IOT protocols with transparent mode

The following examples provide some additional scenarios you can use to get familiar with the XBee. If you are interested in using the intelligence built into the XBee, see Get started with MicroPython.
Get started with CoAP 81 Get started with MQTT 85
Digi XBee® 3 Cat 1 Smart Modem User Guide
80
Page 81
Examples: IOT protocols with transparent mode 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:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 Ver T TKL Code Message ID Token (if any, TKL bytes) ... Options (if any) ... 1 1 1 1 1 1 1 1 Payload (if any) ...
This is an example GET request:
44 01 C4 09 74 65 73 74 B7 65 78 61 6D 70 6C 65
Digi XBee® 3 Cat 1 Smart Modem User Guide
81
Page 82
Examples: IOT protocols with transparent mode 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-
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.
Path.
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.
2.
Open XCTU and click the Configuration working mode button.
3. Add the XBee Smart Modem to XCTU; see Add a device to XCTU.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for that device.
5.
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 XBee® 3 Cat 1 Smart Modem User Guide
82
Page 83
Examples: IOT protocols with transparent mode Get started with CoAP
n Method: GET n URI: example n Given message token: test
1.
Click the Consoles working mode button on the toolbar to add a customized packet.
2.
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.
6.
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 XBee® 3 Cat 1 Smart Modem User Guide
83
Page 84
Examples: IOT protocols with transparent mode 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 re­attempts 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 XBee® 3 Cat 1 Smart Modem User Guide
84
Page 85
Examples: IOT protocols with transparent mode 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. n XCTU. See Install and upgrade XCTU. n That you install Python on your computer. You can download Python from:
https://www.python.org/downloads/.
n That you install the pyserial and paho-mqtt libraries to the Python environment. If you use
Python 2, install these libraries from the command line with pip install pyserial and pip install paho-mqtt. If you use Python 3, use pip3 install pyserial and pip3 install paho-mqtt.
n The full MQTT library source code, which includes examples and tests, which is available in the
paho-mqtt github repository at https://github.com/eclipse/paho.mqtt.python. To download this repository you must have Git installed.

Example: MQTT connect

This example provides insight into the structure of packets in MQTT as well as the interaction between the client and broker. MQTT uses different packets to accomplish tasks such as connecting, subscribing, and publishing. You can use XCTU to perform a basic example of sending a broker a connect packet and receiving the response from the server, without requiring any coding. This is a good way to see how the client interacts with the broker and what a packet looks like. The following table is an example connect packet:
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 XBee® 3 Cat 1 Smart Modem User Guide
85
Page 86
Examples: IOT protocols with transparent mode 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 XBee® 3 Cat 1 Smart Modem User Guide
86
Page 87
Examples: IOT protocols with transparent mode 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.
2.
Open XCTU and click the Configuration working mode button.
3. Add the XBee Smart Modem to XCTU. See Add a device to XCTU.
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.
9.
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 XBee® 3 Cat 1 Smart Modem User Guide
87
Page 88
Examples: IOT protocols with transparent mode 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 XBee® 3 Cat 1 Smart Modem User Guide
88
Page 89
Examples: IOT protocols with transparent mode 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 TLS). 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 XBee® 3 Cat 1 Smart Modem User Guide
89
Page 90
Examples: IOT protocols with transparent mode 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 TLS) 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 XBee® 3 Cat 1 Smart Modem User Guide
90
Page 91
Examples: IOT protocols with transparent mode 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 XBee® 3 Cat 1 Smart Modem User Guide
91
Page 92
Examples: IOT protocols with transparent mode 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 XBee® 3 Cat 1 Smart Modem User Guide
92
Page 93
Examples: IOT protocols with transparent mode Get started with MQTT
The thread that reads the serial port forwards any data received onward to the client socket, and the thread reading the client socket forwards any data received onward to the serial port. This is represented in the figure above.
The proxy script needs to be running before running an MQTT publish or subscribe script.
1. With the proxy script running, run the subscribe example from Example: receive messages
(subscribe) with MQTT, but change the connect line from client.connect("m2m.eclipse.org",
1883, 60) to client.connect("127.0.0.1", port=17300, keepalive=20). This connects the MQTT client to the proxy script, which in turn connects to a broker via the XBee Smart Modem’s internet connection.
2. Run the publish example from Example: send messages (publish) with MQTT in a third Python instance (while the publish script is running you will have three Python scripts running at the same time).
The publish script runs over your computer’s normal Internet connection, and does not use the XBee Smart Modem. You are able to see your published message appear in the subscribe script’s output once it is received from the broker via the XBee Smart Modem. If you watch the output of the proxy script during this process you can see the receptions and transmissions taking place.
The proxy script must be running before you run the subscribe and publish scripts. If you stop the subscribe script, the socket closes, and the proxy script shows an error. If you try to start the proxy script after starting the subscribe script, you may also see a socket error. To avoid these errors, it is best to start the scripts in the correct order: proxy, then subscribe, then publish.
Digi XBee® 3 Cat 1 Smart Modem User Guide
93
Page 94

Update the firmware

You should update your XBee to the latest firmware to take advantage of all the latest fixes and features. Refer to the topics below for information about the available update methods.
Digi strongly recommends that you devise a plan to update the firmware after initial deployment. For more information, see Create a plan for device and cellular component firmware updates.
Create a plan for device and cellular component firmware updates 95 Update the device and the cellular firmware using XCTU 96 Update the device firmware 98 Update the cellular firmware 102
Digi XBee® 3 Cat 1 Smart Modem User Guide
94
Page 95
Update the firmware Create a plan for device and cellular component firmware updates

Create a plan for device and cellular component firmware updates

You should update your XBee to the latest firmware to take advantage of all the latest fixes and features. Changes to the cellular network, security issues, or software bugs may be identified which require firmware updates to resolve. In addition, Digi periodically releases new device firmware which includes new features and improves reliability and performance of existing features. You should evaluate and test the new releases and update your firmware to take advantage of the improvements and new features.
Note Digi will not accept responsibility for customers who have not planned to update their units.
Please review the information provided below.
Please review the suggestions below:
n Always test device and any cellular component firmware updates before deploying these
updates to units in the field.
n If updates will be performed using a PC, XCTU version 6.5.10 or later is able to perform
complete firmware updates on all device cellular modems, including updating the cellular component firmware.
n f updates will be performed using a host processor, see Use a host processor to update the
device firmware for XBee 3 devices over UART.
n If updates will be performed over-the-air (OTA):
l If your XBee application is using API mode, monitor for Modem Status (0x8A) API frames
with status codes 0x38 through 0x3A. These modem status frames inform the XBee's host application about ongoing and completed or failed firmware updates.
l If your XBee application is using Transparent mode, test your application to determine
whether it is tolerant to over-the-air firmware updates of the cellular component and XBee firmware. If your application cannot tolerate the network connection being non-functional for up to 30 minutes (for example, if the XBee will be reset in a shorter time than that), do not use over-the-air updates, and be aware that firmware updates to the XBee require user intervention.
o
If the XBee firmware is updated over-the-air using Digi Remote Manager: After the new firmware image has been downloaded and validated, the XBee modem reboots automatically to install the firmware. The XBee then resets into the new firmware once the update is complete, which may take up to 60 seconds.
o
If the cellular component firmware is being updated: After the cellular firmware update image has been downloaded, the XBee modem disconnects from the network and the cellular component will be updated. This update will take up to 30 minutes. After the update completes (or fails), the XBee will reconnect to the cellular network automatically.
IMPORTANT
Future cellular component updates may require the use of USB Direct access. Ensure your hardware design permits USB Direct functionality, either by designing in a USB port and
options for enabling and disabling USB Direct, or by allowing the XBee 3 cellular modem to be removed from its socket and placed on a development board, such as the Digi XBIB-CU-TH.
Digi XBee® 3 Cat 1 Smart Modem User Guide
95
Page 96
Update the firmware Update the device and the cellular firmware using XCTU

Update the device and the cellular firmware using XCTU

Use XCTU to update the device firmware, and if needed, XCTU will attempt to update your cellular firmware.
Update the device and cellular firmware using XCTU and USBDirect access
Note Before you begin, make sure you have XCTU installed and the device is added to the utility. See
Install and upgrade XCTU.
Update the device and cellular firmware using XCTU and USBDirect access
You can use XCTU to update the device and cellular firmware. XCTU updates the device firmware to the version you select, and then, if needed, XCTU will attempt to update your cellular firmware. Upgrading the cellular component firmware requires USBDirect, which is accessible using an XBIB­CU-TH development board or from your board design.
Prerequisites
n Windows PC n Digi XCTU version 6.5.10 or newer. You should upgrade XCTU to the latest version. n The device is added to XCTU. See Add a device to XCTU. n Digi XBIB-CU-TH development board, or your own hardware which enables USB Direct access n USB cable for USB Direct access is connected to the PC n Cellular component USB drivers are installed
To update the device and cellular firmware:
1.
Launch XCTU .
2.
Click the Configuration working modes button .
3. From the Radio Modules list, select the device that you want to update.
4. Verify the following configuration. The cellular component firmware update may not work if any of these settings are enabled. Ensure the following:
n Airplane mode is disabled: ATAM set to 0 n Bypass mode is disabled: ATAP not 5 n USB Direct Mode is disabled: ATP1 not 7
5. Click Update firmware. The Update the radio module firmware dialog appears and displays the available and compatible device firmware for the selected XBee module.
6. Select the product family of the XBee module, the function set, and the latest firmware version for the device.
7. Make sure you check the Force the module to maintain its current configuration to ensure you do not lose any changes to your configuration.
8. If desired, you can select the Force the Cellular modem update option. When selected, the cellular component is updated even if it is already on the newest firmware version. This step is optional.
Digi XBee® 3 Cat 1 Smart Modem User Guide
96
Page 97
Update the firmware Update the device and the cellular firmware using XCTU
9. Click Update to update the device firmware.
10. If the cellular component firmware requires an update or if you selected the Force the Cellular modem update option, a prompt displays.
11. Click OK to continue with the update process. XCTUperforms the following:
n XCTU applies and updates the device firmware. n If the cellular firmware is being updated, XCTU reconfigures the XBee for USB Direct
access and updates the new cellular firmware on the device.
Digi XBee® 3 Cat 1 Smart Modem User Guide
97
Page 98
Update the firmware Update the device firmware

Update the device firmware

You should update the device firmware on your XBee to the latest version to take advantage of all the latest fixes and features. Security issues or software bugs may be identified which require firmware updates to resolve. In addition, Digi periodically releases new firmware which includes new features and improves reliability and performance of existing features.
n For information about updating the cellular firmware, see Update the cellular firmware.
n For information about using XCTU to update both the device firmware and, if needed, the
cellular firmware, see Update the device and the cellular firmware using XCTU.
The table below lists update methods you can use and the instructions for each method.
Method
FOTA (DRM)
Instructions
n Update the firmware from the Devices page in
Remote Manager
n Update the firmware using web services in Remote
Manager
n Schedule a task to update the device firmware
using Remote Manager
UART
n Use a host processor to update the modem
firmware for XBee 3 devices over UART

Update the firmware from the Devices page in Remote Manager

You can update the device firmware for one or multiple devices from the Devices page in Remote Manager.
Before you begin, verify the TCP connection method your device uses to connect to Remote Manager: query once a day or use a persistent TCPconnection. See TCP connection.
To perform a firmware update:
1. Download the updated firmware file for your device from Digi's support site. a. Go to the Digi XBee 3 NA/Global LTECat1 support page. b. Scroll down to the Firmware Updates section.
c. Locate and click Digi XBee 3 NA/Global LTECat1 firmware release 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. See Set up a
persistent connection to a remote XBee.
3. Log into Remote Manager.
4. Click Devices in the left pane.
5. Select the first device you want to update. To select multiple devices (all devices must be of the
same type), press the Control key and select additional devices.
Digi XBee® 3 Cat 1 Smart Modem User Guide
98
Page 99
Update the firmware Update the device firmware
6. From the toolbar at the top of the screen, click Actions. Scroll down and click Update
Firmware. The Update Firmware dialog appears.
7. Make sure Update Firmware File is selected in the list box. This is the default.
8. Click Choose File to select the .gbl file that you unzipped earlier.
9. Click Update. The updated devices automatically reboot when the updates are complete.
Note The update is immediately rejected and an error is returned if the device is going into
sleep mode or is being shut down. See Clean shutdown.
10. When all changes are complete, disconnect the device from 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.
Before you begin, verify the TCP connection method your device uses to connect to Remote Manager: query once a day or use a persistent TCPconnection. See TCP connection.
1. Download the updated firmware file for your device from Digi's support site. a. Go to the Digi XBee 3 NA/Global LTECat1 support page. b. Scroll down to the Firmware Updates section.
c. Locate and click Digi XBee 3 NA/Global LTECat1 firmware release to download the zip
file.
d. Unzip the file and locate the .gbl file in the unzipped directory.
2. Send an HTTP SCI request to Remote Manager with the contents of the downloaded .gbl file
converted to base64 data. Refer to the the following examples: 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 .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
Digi XBee® 3 Cat 1 Smart Modem User Guide
99
Page 100
Update the firmware Update the device firmware
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">
<targets>
<device id="{}"/> </targets> <data>{}</data>
</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 .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 zip file contains the firmware image.
2. Unzip the file and locate the .gbl file inside the unzipped directory.
3. Log into Remote Manager.
4. Click the arrow next to you your user name, and click Open Classic Remote Manager.
5. Click the Data Services tab.
6. Click Data Files.
7. Click Upload Files; browse and select the *.gbl firmware file to upload it.
8. 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'
Digi XBee® 3 Cat 1 Smart Modem User Guide
100
Loading...