Digi, Digi International, and the Digi logo are trademarks or registered trademarks in the United
States and other countries worldwide. All other trademarks mentioned in this document are the
property of their respective owners.
Information in this document is subject to change without notice and does not represent a
commitment on the part of Digi International. Digi provides this document “as is,” without warranty of
any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or
merchantability for a particular purpose. Digi may make improvements and/or changes in this manual
or in the product(s) and/or the program(s) described in this manual at any time.
Warranty
To view product warranty information, go to the following website:
www.digi.com/howtobuy/terms
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—900025032
Digi XBee® 3 Cat 1 Smart Modem User Guide
Applicable firmware and hardware16
SIM cards17
Safety instructions17
Safety instructions17
Инструкции за безопасност17
Sigurnosne upute18
Bezpečnostní instrukce19
Sikkerhedsinstruktioner19
Veiligheidsinstructies20
Ohutusjuhised20
Turvallisuusohjeet21
Consignes de sécurité21
Sicherheitshinweise22
Οδηγίες ασφαλείας22
Biztonsági utasítások23
Istruzioni di sicurezza23
Drošības instrukcijas24
Saugos instrukcijos25
Sikkerhetsinstruksjoner25
Instrukcje bezpieczeństwa26
Instruções de segurança26
Instructiuni de siguranta27
Bezpečnostné inštrukcie27
Varnostna navodila28
Las instrucciones de seguridad28
Säkerhets instruktioner29
Get started with the XBee Smart Modem
Identify the kit contents31
Determine cellular service and acquire a SIM card32
UScustomers32
European customers32
Connect the hardware33
Install and upgrade XCTU34
Add a device to XCTU34
Update the device and cellular firmware using XCTU35
Digi XBee® 3 Cat 1 Smart Modem User Guide
4
Page 5
Check for cellular registration and connection35
Cellular service36
XBee connection examples
Connect to the Echo server38
Connect to the ELIZA server40
Connect to the Daytime server42
Send an SMS message to a phone44
Perform a (GET) HTTP request46
Connect to a TCP/IP address48
Software libraries48
Get started with MicroPython
About MicroPython51
Why use MicroPython51
MicroPython on the XBee Smart Modem51
Use XCTU to enter the MicroPython environment51
Use the MicroPython Terminal in XCTU52
Troubleshooting52
Example: hello world52
Example: Turn on an LED52
Example: code a request help button53
Enter MicroPython paste mode54
Catch a button press54
Send a text (SMS) when the button is pressed56
Add the time the button was pressed57
Example: debug the secondary UART58
Exit MicroPython mode58
Other terminal programs59
Tera Term for Windows59
Use picocom in Linux60
Get started with Bluetooth® Low Energy
On XBee 3 Cellular firmware ending in x16 or newer62
Enable BLE on an XBee device62
Enable BLEand configure the BLEpassword using XCTU62
Get the Digi XBeeMobile phone application63
Connect with BLEand configure your XBee device64
BLE reference64
BLE advertising behavior and services64
Device Information Service64
XBee API BLEService64
API Request characteristic65
API Response characteristic65
Get started with Digi Remote Manager
Create a Remote Manager account and add devices66
Create a Remote Manager account67
Add an XBee Smart Modem to Remote Manager67
Digi XBee® 3 Cat 1 Smart Modem User Guide
5
Page 6
Verify the connection between a device and Remote Manager67
Configure Remote Manager features using automations68
Overview: Create an automation68
Automation examples69
Example: Read settings and state using Remote Manager69
Example: Configure a device from Remote Manager using XML70
Example: Schedule an automation to update the device firmware using Remote Manager71
Example: Update MicroPython from Remote Manager using an automation73
Manage data in Remote Manager74
Review device status information from Remote Manager74
Manage secure files in Remote Manager75
Remote Manager reference76
Enable SM/UDP76
TCP connection76
Disconnect77
Configure XBee settings within Remote Manager78
Examples: IOT protocols with transparent mode
Get started with CoAP81
CoAP terms81
CoAP quick start example81
Configure the device82
Example: manually perform a CoAPrequest82
Example: Use Python to generate a CoAP message83
Get started with MQTT85
Example: MQTT connect85
Send a connect packet87
Example: send messages (publish) with MQTT88
Example: receive messages (subscribe) with MQTT89
Use MQTT over the XBee Cellular Modem with a PC90
Update the firmware
Create a plan for device and cellular component firmware updates95
Update the device and the cellular firmware using XCTU96
Update the device and cellular firmware using XCTU and USBDirect access96
Update the device firmware98
Update the firmware from the Devices page in Remote Manager98
Update the firmware using web services in Remote Manager99
Use a host processor to update the device firmware for XBee 3 devices over UART101
Update the cellular firmware102
Update the cellular component firmware using Remote Manager102
Update the cellular firmware using the API104
Technical specifications
Interface and hardware specifications108
RF characteristics108
Networking specifications109
Bands109
Power requirements110
Power consumption110
SD (Shutdown) command129
Cellular component firmware updates130
Recommended application circuit130
Heat considerations and testing131
Heat sink guidelines131
Add a fan to provide active cooling133
Custom configuration: Create a new factory default133
Set a custom configuration133
Clear all custom configurations on a device134
SIMcards134
Cellular connection process
Connecting136
Cellular network136
Data network connection136
Data communication with remote servers (TCP/UDP)136
Disconnecting137
Digi XBee® 3 Cat 1 Smart Modem User Guide
7
Page 8
Modes
Select an operating mode139
Transparent operating mode140
API operating mode140
USB direct mode140
Connect the hardware for USBDirect mode140
Enable USB direct mode141
Configure and use PPP with a Digi XBee 3 Cellular CAT1 AT&T modem141
Command mode144
Enter Command mode144
Troubleshooting144
Send AT commands145
Response to AT commands145
Apply command changes146
Make command changes permanent146
Exit Command mode146
MicroPython mode146
Sleep modes
About sleep modes148
Normal mode148
Pin sleep mode148
Cyclic sleep mode148
Cyclic sleep with pin wake up mode148
The sleep timer148
MicroPython sleep behavior148
Power saving features and design recommendations
Airplane mode151
Low voltage shutdown151
Serial communication
Serial interface154
Serial data154
UART data flow154
Serial buffers155
CTS flow control155
RTS flow control155
Enable UART or SPI ports155
SPI operation
SPI communications158
Full duplex operation158
Low power operation159
Select the SPI port160
Force UART operation160
Data format161
Supported sockets167
Best practices when using sockets167
Sockets and Remote Manager167
Sockets and API mode167
Socket timeouts167
Socket limits in API mode167
UDP datagram size limits168
Enable incoming TCP connections168
API mode behavior for outgoing TCP and TLS connections168
API mode behavior for outgoing UDP data169
API mode behavior for incoming TCP connections169
API mode behavior for incoming UDP data170
Transparent mode behavior for outgoing TCP and TLS connections170
Transparent mode behavior for outgoing UDP data170
Transparent mode behavior for incoming TCP connections171
Transparent mode behavior for incoming UDP connections171
Extended Socket frames
Examples172
Available Extended Socket frames173
Extended Socket example: Single HTTP Connection173
Send a Socket Create frame173
Receive a Socket Create response174
Send Socket Connect174
Receive a Socket Connect Response174
Receive a Socket Status175
Send HTTP Request using Socket Send frame175
Receive TX Status176
Receive one or more Receive Data frames176
Receive Socket Status indicating closed connection177
Extended Socket example: UDP177
Send a Socket Create frame177
Receive a Socket Create response178
Bind local source addres178
Receive Bind/Listen Response178
Send to Digi echo server179
Receive TX Status179
Digi XBee® 3 Cat 1 Smart Modem User Guide
9
Page 10
Receive echoed data179
Send to Digi time server180
Receive TX Status180
Receive daytime value180
Close the socket181
Receive close response181
Extended Socket example: TCPListener182
Send a Socket Create frame182
Receive a Socket Create response182
Designate the socket as a listener182
Receive a Socket Bind/Listen Response183
Making a connection to the listener socket183
Receiving Data from the new socket184
Receive a Socket Status indicating closed connection184
Transport Layer Security (TLS)
Specifying TLS keys and certificates187
Transparent mode and TLS188
API mode and TLS188
Key formats188
Certificate limitations188
Cipher suites188
Secure the connection between an XBee and Remote Manager with server authentication189
Step 1: Get the certificate189
Step 2: Configure device189
Step 3: Verify that authentication is being performed189
AS (Active scan for network environment data)235
Execution commands237
NR (Network Reset)237
!R (Modem Reset)237
File system commands238
Error responses238
ATFS (File System)238
ATFS PWD238
ATFS CDdirectory238
ATFS MDdirectory238
ATFS LS [directory]238
ATFS PUTfilename239
ATFS XPUTfilename239
ATFS HASHfilename239
ATFS GETfilename239
ATFS MVsource_pathdest_path239
ATFS RMfile_or_directory239
ATFS INFO239
ATFSFORMAT confirm240
BLE commands241
BI (Bluetooth Identifier)241
BL (Bluetooth MAC address)241
BP (Bluetooth Advertisement Power Level)241
BT (Bluetooth enable)241
$S (SRPSalt)242
$V, $W, $X, $Y (SRPpassword verifier)242
Digi XBee® 3 Cat 1 Smart Modem User Guide
12
Page 13
Remote Manager commands243
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 commands248
KL (Device Location)248
KC (Contact Information)248
KP (Device Description)248
Socket commands249
SI (Socket Info)249
GNSS commands250
GP (GPS)250
GO (GPS Options)251
Power measurement commands251
%V command251
%L (Low voltage shutdown base threshold)251
%M (Low voltage shutdown reset offset)252
Operate in API mode
API mode overview254
Use the AP command to set the operation mode254
API frame format254
API operation (AP parameter = 1)254
API operation with escaped characters (AP parameter = 2)255
API frames
AT Command - 0x08260
AT Command: Queue Parameter Value - 0x09261
Transmit (TX) SMS - 0x1F262
Transmit (TX) Request: IPv4 - 0x20263
Tx Request with TLS Profile - 0x23265
AT Command Response - 0x88267
Transmit (TX) Status - 0x89268
Modem Status - 0x8A270
Receive (RX) Packet: SMS - 0x9F271
Receive (RX) Packet: IPv4 - 0xB0272
User Data Relay - 0x2D273
Example use cases273
User Data Relay Output - 0xAD275
BLE Unlock API - 0x2C276
Example sequence to perform AT Command XBee API frames over BLE278
BLEUnlock Response - 0xAC280
Socket Create - 0x40281
Socket Create Response - 0xC0282
Digi XBee® 3 Cat 1 Smart Modem User Guide
13
Page 14
Socket Option Request - 0x41283
Socket Option Response - 0xC1284
Socket Connect - 0x42285
Socket Connect Response - 0xC2286
Socket Close - 0x43287
Socket Close Response - 0xC3288
Socket Send (Transmit) - 0x44289
Socket SendTo (Transmit Explicit Data): IPv4 - 0x45290
Socket Bind/Listen - 0x46291
Socket Listen Response - 0xC6292
Socket New IPv4 Client - 0xCC293
Socket Receive - 0xCD294
Socket Receive From: IPv4 - 0xCE295
Socket Status - 0xCF296
GNSS Start Raw NMEA, Stop Raw NMEA, or One Shot Request - 0x3D296
GNSS Start Raw NMEA, Stop Raw NMEA, or One Shot Response - 0xBD297
GNSS Raw NMEA Response - 0xBE297
GNSS One Shot Response - 0xBF298
File system APIframes
Local File System Request - 0x3B300
File Open - 0x01301
File Close - 0x02302
File Read - 0x03303
File Write - 0x04303
File Hash - 0x08304
Directory Create - 0x10305
Directory Open - 0x11305
Directory Close - 0x12306
Directory Read - 0x13307
Get Path ID - 0x1C307
Delete - 0x2F308
Volume Info - 0x40308
Volume Format - 0x4F309
Local File System Response - 0xBB309
Regulatory firmware
Install the regulatory firmware312
Install regulatory firmware using XCTU312
Install regulatory firmware using Remote Manager313
Configure regulatory firmware for testing the Bluetooth radio314
Configure regulatory firmware for testing the cellular component314
Bluetooth DTMprotocol314
Example315
Regulatory testing commands315
%# (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 device322
Condition322
Solution322
Other possible issues323
Enable Virtual COM port (VCP) on the driver323
Correct a macOS Java error324
Condition324
Solution324
Unresponsive cellular component in Bypass mode325
Condition325
Solution325
Not on expected network after APN change326
Condition326
Solution326
Syntax error at line 1326
Solution326
Error Failed to send SMS326
Solution326
Baud rate in Bypass mode326
Regulatory information
Antenna regulatory information: FCC and ISED327
Bluetooth antennas327
Cellular antennas328
FCC publication 996369 related information329
Labeling requirements for the host device:FCCand ISED330
Regulatory Information332
Modification statement332
Interference statement332
FCC Class B digital device notice332
RF exposure333
FCC notices333
Regulatory Information: ISED334
Modification statement:ISED334
Interference statement:ISED334
RF exposure: ISED334
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:
SKUDescription
XB3-C-G1-UT-001
XB3-C-N1-UT-001XBee 3 North America LTE Cat 1 without SIM
XB3-C-G1-UT-101
XB3-C-N1-UT-101XBee 3 North America LTE Cat 1 with AT&T SIM
XB3-C-G1-UT-102
XB3-C-N1-UT-102XBee 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 GuideSIM 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 LTECat 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 XBeeFunkgerä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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 GuideSafety 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 ModemIdentify the kit contents
Identify the kit contents
The Developer's kit includes the following:
ItemDescription
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 USBcable
Note This cable is used only with USBDirect
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 ModemDetermine cellular service and acquire a SIM card
ItemDescription
One SIMcard, if the device kit that you purchased
includes a SIMcard.
Note If your kit does not include a SIMcard, 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 SIMcard.
Note If your kit came with a SIMcard, 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
SIMcard in the US and Europe.
UScustomers
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 SIMcard, 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 SIMcard, 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 ModemConnect 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 SIMcard 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 ModemInstall 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 COMport (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 XCTUUpdates to ensure you are using the latest version of XCTU.
3.
Click the Discover radio modules buttonin 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 ModemUpdate 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 USBDirect.
Update the device and cellular firmware using XCTU and USBDirect 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 SIMcard 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 LEDremains solid, registration has not occurred properly.
View commands in XCTU
1.
Launch XCTU.
2.
Click the Configuration working modebutton.
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 IPaddress. 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 ModemCellular service
Hints
n
To search for an ATcommand in XCTU, use the search box.
n
To read a command's value, click the Read buttonnext 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 server38
Connect to the ELIZA server40
Connect to the Daytime server42
Send an SMS message to a phone44
Perform a (GET) HTTP request46
Connect to a TCP/IP address48
Software libraries48
Digi XBee® 3 Cat 1 Smart Modem User Guide
37
Page 38
XBee connection examplesConnect 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 commandValueDescription
IP (IP
Protocol)
TD
(Text
Delimiter)
DL
(Destination
Address)
DE
(Destination
Port)
To communicate with the Echo server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working modebutton.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
1Set the expected transmission mode to TCP communications.
D (0x0D)
52.43.121.77The target IPaddress 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 buttonon 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 buttonto open a serial connection to the device.
Digi XBee® 3 Cat 1 Smart Modem User Guide
38
Page 39
XBee connection examplesConnect 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 examplesConnect to the ELIZA server
Connect to the ELIZA server
You can use the XBee to chat with the ELIZA Therapist Bot. ELIZAis 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 commandValueDescription
IP (IP Protocol)1Set 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 modebutton.
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 ELIZATherapist 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 buttonon 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 buttonto 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.77The target IP address of the ELIZA server.
Digi XBee® 3 Cat 1 Smart Modem User Guide
40
Page 41
XBee connection examplesConnect to the ELIZA server
Digi XBee® 3 Cat 1 Smart Modem User Guide
41
Page 42
XBee connection examplesConnect 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 commandValueDescription
IP (IP
Protocol)
DL
(Destination
Address)
DE
(Destination
Port)
TD (Text
Delimiter)
To communicate with the Daytime server:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working modebutton.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
1Set the expected transmission mode to TCP communications.
52.43.121.77The 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 buttonon 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 buttonto 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 examplesConnect to the Daytime server
Digi XBee® 3 Cat 1 Smart Modem User Guide
43
Page 44
XBee connection examplesSend 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.
CommandValueDescription
AP (APIEnable)
IP (IP Protocol)
P#
(DestinationPhone
Number)
TD (Text Delimiter)
PH (Module's SIM
phone number)
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working modebutton.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
0Set the device's API mode to Transparent mode.
2Set the expected transmission mode to SMScommunication.
<Target
phone
number>
D (0x0D)
Read onlyThe 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 buttonon 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 buttonto open a serial connection to the device.
Digi XBee® 3 Cat 1 Smart Modem User Guide
44
Page 45
XBee connection examplesSend 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 examplesPerform 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 GETrequest:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working modebutton.
4. Select a device from the Radio Modules list. XCTU displays the current firmware settings for
that device.
5. To enter the destination address of the target website, in the DL field, type httpbin.org and
click the Write button.
6. To enter the HTTP request port number, in the DE field, type 50 and click the Write button.
Hexadecimal 50 is 80 in decimal.
7. To switch to TCP communication, in the IP field, select 1 and click the Write button.
8. To move into Transparent mode, in the APfield, select 0 and click the Write button.
9. Wait for the AI (Association Indication) value to change to 0 (Connected to the Internet).
10.
Click the Consoles working mode buttonon the toolbar.
11.
From the AT console, click the Add new packet buttonin 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:
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 examplesPerform a (GET) HTTP request
17. Click Send selected packet.
18. A GETHTTP response from httpbin.org appears in the Console log.
Digi XBee® 3 Cat 1 Smart Modem User Guide
47
Page 48
XBee connection examplesConnect 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/IPserver.
Note For help with debugging, see Debugging.
The following table explains the AT commands that you use in this example.
CommandValueDescription
IP (IP
Protocol)
DL
(Destination
IPAddress)
DE
(Destination
Port)
To connect to a TCP/IP address:
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2. Open XCTU and Add a device to XCTU.
3.
Click the Configuration working modebutton.
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 IPaddress that you send and receive from.
7. In the DE field, type the <target port number>, converted to hexadecimal, and click the Write
button.
8. Exit Command mode.
1Set the expected transmission mode to TCPcommunication.
<Target
IPaddress>
<Target
portnumber>
The target IP address that you send and receive from. For
example, a data logging server’s IP address that you want to send
measurements to.
The target port number that the device sends the transmission to.
This is represented as a hexadecimal value.
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 examplesSoftware 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 MicroPython51
MicroPython on the XBee Smart Modem51
Use XCTU to enter the MicroPython environment51
Use the MicroPython Terminal in XCTU52
Example: hello world52
Example: Turn on an LED52
Example: code a request help button53
Example: debug the secondary UART58
Exit MicroPython mode58
Other terminal programs59
Use picocom in Linux60
Digi XBee® 3 Cat 1 Smart Modem User Guide
50
Page 51
Get started with MicroPythonAbout MicroPython
About MicroPython
MicroPython is an open-source programming language based on Python 3, with much of the same
syntax and functionality, but modified to fit on small devices with limited hardware resources, such as
microcontrollers, or in this case, a cellular modem.
Why use MicroPython
MicroPython enables on-board intelligence for simple sensor or actuator applications using digital and
analog I/O. MicroPython can help manage battery life. Cryptic readings can be transformed into useful
data, excess transmissions can be intelligently filtered out, modern sensors and actuators can be
employed directly, and logic can glue inputs and outputs together in an intelligent way.
For more information about MicroPython, see www.micropython.org.
For more information about Python, see www.python.org.
MicroPython on the XBee Smart Modem
The XBee Smart Modem has MicroPython running on the device itself. You can access a MicroPython
prompt from the XBee Smart Modem when you install it in an appropriate development board (XBDB
or XBIB), and connect it to a computer via a USB cable.
Note MicroPython does not work with SPI.
The examples in this guide assume:
n You have XCTU on your computer. See 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 APfield 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 MicroPythonUse 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 menuand 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 MicroPythonExample: 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 MicroPythonExample: 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 MicroPythonExample: 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 MicroPythonExample: 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
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 MicroPythonExample: code a request help button
Add the time the button was pressed
After you add the ability to send an SMS to the code, add functionality to insert the time at which the
button was pressed into the SMS that is sent. To accomplish this:
1. Create a UDP socket with the socket() method.
2. Save the IP address and port of the time server in the addr variable.
3. Connect to the time server with the connect() method.
4. Send hello to the server to prompt it to respond with the current date and time.
5. Receive and store the date/time response in the buf variable.
6. Send an SMSin the same manner as before using the sms_send() method, except that you add
the time into the SMS message, such that the message reads: [Button pressed at: YYYY-MM-
DD HH:MM:SS]
To verify that your phone number is still in the memory, at the MicroPython >>> prompt, type ph and
press Enter.
If MicroPython responds with your number, copy the following code and enter it into MicroPython
using paste mode and then run it. If it returns an error, enter your number again as shown in Send a
text (SMS) when the button is pressed. With your phone number in memory in the ph variable, copy
the code below and enter it into MicroPython using paste mode (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:
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 MicroPythonExample: 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 MicroPythonOther 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/npatefault/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 MicroPythonUse 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 MicroPythonUse 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
BLEdevice 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 BLEService.
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 BLEon your XBee 3 device and verify the connection.
1. Set up your XBee device. See Get started with the XBee Smart Modem.
2. Enable BLEand configure the BLEpassword using XCTU.
3. Get the Digi XBeeMobile phone application.
4. Connect with BLEand 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 BLEand configure the BLEpassword 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 BLEconfiguration 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 EnergyGet the Digi XBeeMobile phone application
Before you begin, you should determine the password you want to use for BLEon 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 BLEpassword 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 XBeeMobile phone application
To see the nearby devices that have BLEenabled, 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 EnergyConnect with BLEand configure your XBee device
Connect with BLEand configure your XBee device
You can use the Digi XBee Mobileapplication to verify that BLEis enabled on your XBee device.
1. Get the Digi XBeeMobile 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 BLEenabled 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 BLEService
Device Information Service
The standard Device Information Service is used. The Manufacturer, Model, and Firmware Revision
characters are provided inside the service.
XBee API BLEService
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 BLEUnlock 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 EnergyBLE 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.
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.
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 ManagerCreate 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 DAYFREETRIAL/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 XCTUto 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 ManagerConfigure 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/UDPRequest 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/UDPis 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 ManagerAutomation 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 ManagerAutomation 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 ShowDetails. 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 ManagerAutomation 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 ManagerAutomation 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 ManagerAutomation 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/UDPis 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 FTPsample 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 ManagerManage 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 ManagerManage 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 ATcommands. For information about each ATcommand 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 ManagerRemote 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.
ModuleUpgrade firmware version
XBee 3 CAT 131011
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
TCPconnection 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 ManagerRemote 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
TCPconnection. 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 ManagerRemote 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. Makethe 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 SMSmessaging 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 ManagerRemote 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 SIMcard 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 CoAP81
Get started with MQTT85
Digi XBee® 3 Cat 1 Smart Modem User Guide
80
Page 81
Examples: IOT protocols with transparent modeGet started with CoAP
Get started with CoAP
Constrained Application Protocol (CoAP) is based on UDP connection and consumes low power to
deliver similar functionality to HTTP. This guide contains information about sending GET, POST, PUT
and DELETE operations by using the Coap Protocol with XCTU and Python code working with the XBee
Smart Modem and Coapthon library (Python 2.7 only).
The Internet Engineering Task Force describes CoAP as:
The protocol is designed for machine-to-machine (M2M) applications such as smart energy and
building automation. CoAP provides a request/response interaction model between application
endpoints, supports built-in discovery of services and resources, and includes key concepts of
the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP
for integration with the Web while meeting specialized requirements such as multicast
support, very low overhead, and simplicity for constrained environments (source).
CoAP terms
When describing CoAP, we use the following terms:
TermMeaning
MethodCOAP's method action is similar to the HTTP method. This guide discusses the GET,
POST, PUT and DELETE methods. With these methods, the XBee Smart Modem can
transport data and requests.
URIURI is a string of characters that identifies a resource served at the server.
TokenAtoken is an identifier of a message. The client uses the token to verify if the
received message is the correct response to its query.
PayloadThe message payload is associated with the POST and PUT methods. It specifies the
data to be posted or put to the URI resource.
MessageIDThe 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:
Examples: IOT protocols with transparent modeGet started with CoAP
The following table describes the fields in the GETrequest.
FieldHEXBitsMeaning
Ver4401Version 01, which is mandatory here.
T00Type 0: confirmable.
TKL0100Token length: 4.
Code01000 00001Code: 0.01, which indicates the GET method.
Message IDC4 092 Bytes equal
to hex at left
Token74 65 73 74 4 Bytes equal
to hex at left
Option deltaB71011Delta option: 11 indicates the option data is Uri-
Optionlength0111Delta length: 7 indicates there are 7 bytes of data
Option value65 78 61 6D
70 6C 65
7 Bytes equal
to hex at left
Message ID. The response message will have the
same ID. This can help out identification.
Token. The response message will have the same
token. This can help out identification.
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 modebutton.
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 UDPcommunication, 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 DEfield, type 1633
and click the Write button.
8. To move into Transparent mode, in the APfield, select 0 and click the Write button.
9. Wait for the AI (Association Indication) value to change to 0 (Connected to the Internet). You
can click Readto get an update on the AI value.
Example: manually perform a CoAPrequest
Follow the steps in Configure the device prior to this example. This example performs the CoAP
GETrequest:
Digi XBee® 3 Cat 1 Smart Modem User Guide
82
Page 83
Examples: IOT protocols with transparent modeGet started with CoAP
n Method: GET
n URI: example
n Given message token: test
1.
Click the Consoles working mode buttonon the toolbar to add a customized packet.
2.
From the AT console, click the Add new packet buttonin 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 modeGet 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.
XCTUprovides the current baud rate in the BD Baud Rate field. In this example you would type
9600.
8. Press Y if you want an auto-generated example. Press Enter to build your own CoAP request.
9. If you press Y it generates a message with:
n Method: POST
n URI: example
n payload:hello world
n token: test
The send and receive message must match the same token and message id. Otherwise, the client reattempts the connection by sending out the request.
In the following figure, the payload contains the server response to the query. It shows the results for
when you press Enter rather than Y.
Digi XBee® 3 Cat 1 Smart Modem User Guide
84
Page 85
Examples: IOT protocols with transparent modeGet started with MQTT
Get started with MQTT
MQ Telemetry Transport (MQTT) is a messaging protocol that is ideal for the Internet of Things (IoT)
due to a light footprint and its use of the publish-subscribe model. In this model, a client connects to a
broker, a server machine responsible for receiving all messages, filtering them, and then sending
messages to the appropriate clients.
The first two MQTTexamples do not involve the XBee Smart Modem. They demonstrate using the
MQTTlibraries because those libraries are required for Use MQTT over the XBee Cellular Modem with
a PC.
The examples in this guide assume:
n Some knowledge of Python.
n An integrated development environment (IDE)such as PyCharm, IDLE or something similar.
The examples require:
n An XBee Smart Modem.
n A compatible development board.
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:
DescriptionHex value
CONNECT packet fixed header
byte 1Control packet type0x10
byte 2Remaining length0x10
CONNECT packet variable header
Protocol name
Digi XBee® 3 Cat 1 Smart Modem User Guide
85
Page 86
Examples: IOT protocols with transparent modeGet started with MQTT
DescriptionHex value
byte 1Length MSB (0)0x00
byte 2Length LSB (4)0x04
byte 3(M)0x4D
byte 4(Q)0x51
byte 5(T)0x54
byte 6(T)0x54
Protocol level
byte 7Level (4)0x04
Connect flags
byte 8
Keep alive
byte 9Keep Alive MSB (0)0x00
byte 10Keep Alive LSB (60)0x3C
Client ID
byte 11Length MSB (0)0x00
byte 12Length LSB (4)0x04
byte 13(D)0x44
byte 14(I)0x49
byte 15(G)0x47
byte 16(I)0x49
The following table describes the fields in the packet:
FieldnameDescription
ProtocolNameThe connect packet starts with the protocol name, which is MQTT. The length of
CONNECT flags byte, see the table below for the bits.
the protocol name (in bytes) is immediately before the name itself.
0x02
ProtocolLevelRefers to the version of MQTT in use, in this case a value of 4 indicates MQTT
version 3.1.1.
Connect FlagsIndicate certain aspects of the packet. For simplicity, this example only sets the
Clean Session flag, which indicates to the client and broker to discard any
previous session and start a new one.
Keep AliveHow often the client pings the broker to keep the connection alive; in this
example it is set to 60 seconds.
Digi XBee® 3 Cat 1 Smart Modem User Guide
86
Page 87
Examples: IOT protocols with transparent modeGet started with MQTT
FieldnameDescription
Client IDThe length of the ID (in bytes) precedes the ID itself. Each client connecting to a
broker must have a unique client ID. In the example, the ID is DIGI. When using
the Paho MQTT Python libraries, a random alphanumeric ID is generated if you do
not specify an ID.
The following table provides the CONNECT flag bits from byte 8, the CONNECT flags byte.
Now that you know what a connect packet looks like, you can send a connect packet to a broker and
view the response. Open XCTU and click the Configuration working mode button.
1. Ensure that the device is set up correctly with the SIM card installed and the antennas
connected as described in Connect the hardware.
2.
Open XCTU and click the Configuration working modebutton.
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 APfield, set Transparent Mode to [0] if it is not already and click the Write button.
6. In the DL field, type the IP address 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 buttonon 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 buttonto open a serial connection to the device.
11.
From the AT console, click the Add new packet buttonin 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 modeGet 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):
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-
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 modeGet started with 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 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 modeGet 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 modeGet 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 modeGet 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 modeGet 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 updates95
Update the device and the cellular firmware using XCTU96
Update the device firmware98
Update the cellular firmware102
Digi XBee® 3 Cat 1 Smart Modem User Guide
94
Page 95
Update the firmwareCreate 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 firmwareUpdate 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 USBDirect 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 USBDirect
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 USBDirect, which is accessible using an XBIBCU-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 firmwareUpdate 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 theCellular modem update option, a prompt displays.
11. Click OK to continue with the update process. XCTUperforms 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 firmwareUpdate 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 TCPconnection. 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 LTECat1 support page.
b. Scroll down to the Firmware Updates section.
c. Locate and click Digi XBee 3 NA/Global LTECat1 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 firmwareUpdate 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 TCPconnection. 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 LTECat1 support page.
b. Scroll down to the Firmware Updates section.
c. Locate and click Digi XBee 3 NA/Global LTECat1 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'
# 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'