manualshive.com logo in svg

Digi XBee 3 Cellular LTE-M, User Manual, Page: 247 / 331

Share
Download
Digi XBee 3 Cellular LTE-M User Manual Download Page 247

Operate in API mode

API mode overview

Digi XBee® 3 Cellular LTE-M/NB-IoT Global Smart Modem User Guide

247

API mode overview

As an alternative to Transparent operating mode, you can use API operating mode. API mode provides
a structured interface where data is communicated through the serial interface in organized packets
and in a determined order. This enables you to establish complex communication between devices
without having to define your own protocol. The API specifies how commands, command responses
and device status messages are sent and received from the device using the serial interface or the
SPI interface.

We may add new frame types to future versions of firmware, so build the ability to filter out additional
API frames with unknown frame types into your software interface.

Use the AP command to set the operation mode

Use

AP (API Enable)

to specify the operation mode:

AP command
setting

Description

AP

= 0

Transparent operating mode, UART serial line replacement with API modes
disabled. This is the default option.

AP

= 1

API operation.

AP

= 2

API operation with escaped characters (only possible on UART).

AP

= 3

N/A

AP

= 4

MicroPython REPL

AP

= 5

Bypass mode. This mode is for direct communication with the underlying chip and
is only for advanced users.

The API data frame structure differs depending on what mode you choose.

API frame format

An API frame consists of the following:

n

Start delimeter

n

Length

n

Frame data

n

Checksum

API operation (AP parameter = 1)

This is the recommended API mode for most applications. The following table shows the data frame
structure when you enable this mode:

Summary of Contents for XBee 3 Cellular LTE-M

Page 1: ...Digi XBee 3 Cellular LTE M NB IoT Smart Modem User Guide...

Page 2: ...ample to include information about Allow Offline option Updated prerequisites Update an XBee module cellular component using FOTA over the air Updated maximum baud rates Updated Enable SM UDP Added PG...

Page 3: ...e 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 3...

Page 4: ...24 Configure your module for cellular connectivity 24 US customers 24 European customers 25 Check for cellular registration and connection 25 XBee connection examples Connect to the Echo server 28 Co...

Page 5: ...Remote Manager Create a Remote Manager account and add devices 49 Create a Remote Manager account 50 Add an XBee Smart Modem to Remote Manager 50 Verify the connection between a device and Remote Man...

Page 6: ...over UART prior to 10 87 Use a host processor to update the device firmware for XBee 3 devices over UART after 10 89 Update the cellular firmware 91 Update an XBee module cellular component using FOT...

Page 7: ...TCP UDP 123 Disconnecting 124 Modes Select an operating mode 126 Transparent operating mode 127 API operating mode 127 Command mode 127 Enter Command mode 127 Troubleshooting 128 Send AT commands 128...

Page 8: ...munication Serial interface 146 Serial data 146 UART data flow 146 Serial buffers 147 CTS flow control 147 RTS flow control 147 Enable UART or SPI ports 147 I2C 148 SPI operation SPI communications 15...

Page 9: ...equest using Socket Send frame 166 Receive TX Status 167 Receive one or more Receive Data frames 167 Receive Socket Status indicating closed connection 168 Extended Socket example UDP 168 Send a Socke...

Page 10: ...ular Network Time 187 AN Access Point Name 188 CP Carrier Profile 188 BM Bandmask LTE M 189 BN Bandmask NB IoT 189 AM Airplane Mode 190 N Preferred Network Technology 190 SQ Reference Signal Received...

Page 11: ...IO7 CTS 209 D8 DIO8 SLEEP_REQUEST 209 D9 DIO9 ON_SLEEP 209 P0 DIO10 PWM0 Configuration 210 P1 DIO11 PWM1 Configuration 210 P2 DIO12 Configuration 211 P3 DIO13 DOUT 211 P4 DIO14 DIN 212 PD Pull Directi...

Page 12: ...path 233 ATFS RM file_or_directory 233 ATFS INFO 233 ATFS FORMAT confirm 234 BLE commands 235 BI Bluetooth Identifier 235 BL Bluetooth MAC address 235 BP Bluetooth Advertisement Power Level 235 BT Blu...

Page 13: ...Receive RX Packet SMS 0x9F 263 Receive RX Packet IPv4 0xB0 264 User Data Relay 0x2D 265 Example use cases 265 User Data Relay Output 0xAD 267 BLE Unlock API 0x2C 268 Example sequence to perform AT Co...

Page 14: ...testing the cellular component 303 Bluetooth DTM protocol 304 Example 304 Regulatory testing commands 304 Enable disable test mode 305 1 Start test mode 306 2 Stop test mode 306 5 Start modulated tra...

Page 15: ...Regulatory information United States FCC 318 OEM labeling requirements 318 FCC notices 318 FCC approved antennas 319 RF exposure 320 FCC publication 996369 related information 320 Innovation Science a...

Page 16: ...ent mode n Command mode n Bypass to the raw cellular modem n SMS Some carriers do not support SMS on LTE M and or NB IoT Check with your carrier for details n TCP UDP up to six sockets n TLS up to six...

Page 17: ...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 Note You must upgrade your device to the latest firmware...

Page 18: ...cho 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 Micro...

Page 19: ...Item Description One XBIB CU TH board One cellular antenna with a U FL connector One Bluetooth Low Energy BLE antenna One USB C cable Note This cable is used to power the development board One Micro...

Page 20: ...i XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 20 Item Description One SIM card Note NB IoT kits do not include a SIM card Contact your NB IoT mobile carrier provider to obtain a SIM car...

Page 21: ...ard and service n Vodafone www vodafone com n Deutsche Telekom www telekom com en After you have purchased your SIM card you can get the APN if needed by your carrier network bands and supported chann...

Page 22: ...For more information about development boards see Development boards 2 If a SIM card is included with the kit the card is inserted into the XBee If a SIM card is not included install the SIM card int...

Page 23: ...h 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...

Page 24: ...ot 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 a...

Page 25: ...ick the Write button 8 Reset the module with either the reset button or issue the FR command 9 Wait for a connection You may wait for up to 5 6 minutes n If you have a connection This process is compl...

Page 26: ...ot occurred properly View commands in SCTU 1 Launch XCTU 2 Click the Configuration working mode button 3 Select a device from the Radio Modules list XCTU displays the current firmware settings for tha...

Page 27: ...arted 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...

Page 28: ...mode to UDP communications TD Text Delimiter D 0x0D 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 n...

Page 29: ...age 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...

Page 30: ...t 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 Configuratio...

Page 31: ...XBee connection examples Connect to the ELIZA server Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 31...

Page 32: ...r 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...

Page 33: ...on the toolbar to open a serial console to the device For instructions on using the Console see the AT console topic in the XCTU User Guide 10 Click the Open button to open a serial connection to the...

Page 34: ...P communication in the IP field select 1 and click the Write button 7 To move into Transparent mode in the AP field select 0 and click the Write button 8 Wait for the AI Association Indication value t...

Page 35: ...hat the device sends the transmission to This is represented as a hexadecimal value To connect to a TCP IP address 1 Ensure that the device is set up correctly with the SIM card installed and the ante...

Page 36: ...nicate with the XBee device is by using a software library The libraries available for use with the XBee Smart Modem include n XBee Java library n XBee Python library n XBee ANSI C library The XBee Ja...

Page 37: ...l components Note For in depth information and more complex code examples refer to the Digi MicroPython Programming Guide About MicroPython 38 MicroPython on the XBee Smart Modem 38 Use XCTU to enter...

Page 38: ...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 termin...

Page 39: ...dicating 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 recei...

Page 40: ...ily 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...

Page 41: ...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 L...

Page 42: ...ow 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 e...

Page 43: ...g 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 lis...

Page 44: ...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 On XBee 3 Cellular firmware ending...

Page 45: ...tion Create a new factory default Enable BLE and configure the BLE password using XCTU Some of the latest XBee 3 modules support Bluetooth Low Energy BLE as an extra interface for configuration If you...

Page 46: ...on 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...

Page 47: ...alues 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...

Page 48: ...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 characteristi...

Page 49: ...ce 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 task...

Page 50: ...ate a Remote Manager account 1 Go to https www digi com products cloud digi remote manager 2 Click 30 DAY FREE TRIAL LOGIN 3 Follow the online instructions to complete account registration You can upg...

Page 51: ...tes 24 hours 4 Enable the SM UDP feature in Remote Manager for each device See Enable SM UDP Configure Remote Manager features by scheduling tasks Remote Manager provides tools to perform common manag...

Page 52: ...pper left corner to close the wizard See Schedule walk through feature in the Digi Remote Manager User Guide for more information 5 In the Description field enter a name for the schedule such Read Set...

Page 53: ...i_request query_setting rci_request c Make sure that the Allow Offline option is selected This ensures that the schedule runs even if the device is offline d Click Device Disconnect A task is added to...

Page 54: ...e following tasks a Click SM UDP SM UPD Request Connect A task is added to the dialog b Click Device RCI Command A task is added to the dialog Change the RCI command to the following rci_request set_s...

Page 55: ...le contains either a ebin or a gbl file 2 Log into Remote Manager 3 Make sure that you have enabled SM UDP See Enable SM UDP 4 Click Device Management Schedules 5 Click New Schedule The New Schedule p...

Page 56: ...2 Click Data Services Data Files 3 Upload the MicroPython application main py file a Click New Folder The New Folder dialog displays b In the Folder name field enter a descriptive name such as MicroP...

Page 57: ...e RCI Command name event on_error continue on_error event sci send_message cache false allowOffline true Disable Python Auto start and enable TCP connection for remainder of commands rci_request set_s...

Page 58: ...i file_system allowOffline true commands put_file path flash lib uftp py file MicroPython uftp py file put_file commands file_system sci command command name RCI Command name event on_error continue o...

Page 59: ...be used in examples dialog appears a From the Add Targets list box search for the IMEI device ID of the device that you want to update b Click Add The device is added to the device list c Click OK 4...

Page 60: ...The configuration Home page appears 6 Click Status in the toolbar to display the status sub menus 7 Click on the status group that has information you want to display The status information is relate...

Page 61: ...5 Select the device that you want to configure 6 Click Properties in the toolbar As an alternative double click on the device name The Properties page appears 7 Click File Management The File Managem...

Page 62: ...a remote XBee n Below the listed version If your firmware version is below the listed version a persistent TCP connection is used by default The device is continually connected to Remote Manager usin...

Page 63: ...vices Data Files in Remote Manager 8 Select the device s on which you want to run this schedule You can add more than one device 9 Click Run Now Within the next 24 hours which is the default polling p...

Page 64: ...he settings in that category appear 8 Make the desired configuration changes See AT commands for information about each setting in the categories 9 As you finish configuring in each setting category c...

Page 65: ...Management tab 4 Select the device that you want to configure 5 In the toolbar select More SMS Configure The SMS Configuration dialog appears 6 Select the SIM 1 option This should be selected by defa...

Page 66: ...additional scenarios you can use to get familiar with the XBee If you are interested in using the intelligence built into the XBee see Get started with MicroPython Get started with CoAP 67 Get started...

Page 67: ...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 u...

Page 68: ...that the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware 2 Open XCTU and click the Configuration working mode button 3 Add the X...

Page 69: ...l 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 usi...

Page 70: ...vice s current baud rate XCTU provides the current baud rate in the BD Baud Rate field In this example you would type 9600 8 Press Y if you want an auto generated example Press Enter to build your own...

Page 71: ...s 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...

Page 72: ...0x44 byte 14 I 0x49 byte 15 G 0x47 byte 16 I 0x49 The following table describes the fields in the packet Field name Description Protocol Name The connect packet starts with the protocol name which is...

Page 73: ...talled and the antennas connected as described in Connect the hardware 2 Open XCTU and click the Configuration working mode button 3 Add the XBee Smart Modem to XCTU See Add a device to XCTU 4 Select...

Page 74: ...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...

Page 75: ...e 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 broke...

Page 76: ...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...

Page 77: ...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...

Page 78: ...e 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 essent...

Page 79: ...t 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 r...

Page 80: ...mends 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 cell...

Page 81: ...TA 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...

Page 82: ...10 You cannot downgrade to a version earlier than 11410 after installing 1140F 11410 You also need to use XCTU version 6 4 2 or later Prerequisites n Windows PC n Digi XCTU version 6 5 0 or newer You...

Page 83: ...cted the cellular component is updated even if it is already on the newest firmware version This step is optional 9 Click Update to update the device firmware 10 If the cellular component firmware req...

Page 84: ...e the firmware using web services in Remote Manager n Schedule a task to update the device firmware using Remote Manager API n Use a host processor to update the modem firmware for XBee 3 devices over...

Page 85: ...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 examp...

Page 86: ...d fw_data base64 encodebytes fw_data decode utf 8 Form update_firmware request data sci_request version 1 0 update_firmware filename firmware gbl targets device id targets data data update_firmware sc...

Page 87: ...evice id targets file file update_firmware sci_request format device_id firmware_path Post request r requests post url auth username password data data if r status_code 200 or error in r content decod...

Page 88: ...n 3 d Reset the module pin 5 e Release the break on DIN pin 3 The module should now be in bootloader at 38400 baud 3 Once the module is in programming bootloader mode configure the local serial port t...

Page 89: ...er each block is transfered wait for a response Options are n 0x55 ACK This is the expected answer n 0x12 Checksum CRC16 error n 0x13 Flash write verify error Note If an error occurs you may try to tr...

Page 90: ...hrough the UART interface 1 Look for the bootloader prompt BL to ensure the bootloader is active 2 Send an ASCII 1 character to initiate a firmware update 3 After sending a 1 the device waits for an X...

Page 91: ...t using FOTA over the air You can update an XBee 3 Cellular LTE M NB IoT module from any of the released modem version to the latest version over the air An example script is included in this section...

Page 92: ...server is not accessible on a private APN or by direction of Digi Technical Support usage fota py h type auto es2 ip ftp_server FTP_SERVER ftp_port FTP_PORT ftp_user FTP_USER ftp_password FTP_PASSWOR...

Page 93: ...p csv where timestamp is the time of the run The file lists each IMEI whether the update for that IMEI was successful and any error message if the update failed 8 A successful update appears as SUCCES...

Page 94: ...mmand Script usage The arguments and default values for the script are shown below By default Digi hosts the update files on a public FTP server and the script attempts to apply the appropriate update...

Page 95: ...o to the Digi XBee 3 Cellular LTE M support page b Scroll down to the Firmware Updates section c Look at the links that begin with u blox Over the Wire Update Script d Click the appropriate links to d...

Page 96: ...7 16 06 28 502 update py INFO Cellular component update successful 2019 06 27 16 06 28 503 update py INFO Restoring previous baud rate and RTS CTS configuration 2019 06 27 16 06 28 743 update py INFO...

Page 97: ...Cellular RF characteristics 98 Bluetooth RF characteristics 98 Cellular networking specifications 98 Power requirements 99 Power consumption 100 Electrical specifications 101 Regulatory approvals 102...

Page 98: ...ge 0 2 5 V Cellular chipset u blox SARA R410M 028 Form factor Digi XBee 20 pin through hole SIM size 4FF Nano Cellular RF characteristics The following table provides the RF characteristics for the de...

Page 99: ...19 850 MHz n Band 8 900 MHz n Band 4 1700 MHz n Band 3 1800 Mhz n Band 2 1900 MHz n Band 25 1900 MHz 1 n Band 1 2100 MHz LTE TDD bands n Band 39 1900 MHz Security Digi Trustfence Downlink uplink speed...

Page 100: ...State Using serial interface VCC 3 3 V Using USB direct mode VCC 3 3 V Peak transmit current Bluetooth disabled 550 mA 550 mA Bluetooth enabled 610 mA 610 mA Average connected mode current TX RX 23 dB...

Page 101: ...VI Other XBee pins 0 3 VDD_IO 0 3 V Voltage on XBee pin 6 5 V tolerant 0 3 5 25 or VDD_IO 2 whichever is lower1 VIL Input low voltage 0 3 VDD_ IO V VIH Input high voltage 0 7 VDD_IO V VOL Voltage out...

Page 102: ...cation Value Model XB3M1 United States FCC ID MCQ XB3M1 FCC ID XPY2AGQN4NNN Innovation Science and Economic Development Canada ISED IC 1846A XB3M1 IC 8595A 2AGQN4NNN RoHS Lead free and RoHS compliant...

Page 103: ...l drawings 104 Pin signals 104 XBee header connector requirements 106 RSSI PWM 106 SIM card 107 Associate LED functionality 107 Development boards 109 Digi XBee 3 Cellular LTE M NB IoT Global Smart Mo...

Page 104: ...T Global Smart Modem User Guide 104 Mechanical drawings The following figures show the mechanical drawings for the XBee Smart Modem All dimensions are in inches For XBee header information see XBee he...

Page 105: ...igital I O 10 7 PWM1 DIO11 USB D I2C_SDA Either Disabled PWM Output 1 Digital I O 11 or USB Direct D line I2C SDA See the I2C note below for more information 8 USB D USB Direct D line 9 DTR SLEEP_RQ D...

Page 106: ...information see Class I2C in the Digi MicroPython Programming Guide Pin connection recommendations To ensure compatibility with future updates make USB D and D pin 7 and pin 8 available in your design...

Page 107: ...on the XBIB CU TH development board see number 5 on the XBIB CU TH reference LED status Blink timing Meaning On solid Not joined to a mobile network Double blink second The last TCP UDP attempt faile...

Page 108: ...Hardware Associate LED functionality Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 108...

Page 109: ...s Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 109 Development boards XBIB CU TH reference This picture shows the XBee CU TH development board and the table that follows explains th...

Page 110: ...n or if XBEE is not configured to enable USB communications See ATP1 command This USB port is not designed to power the module or the board A USB C cable or battery port is required to power the board...

Page 111: ...ernal power or for when the XBee and the USB C connector is not powering the UART Note Power supply outputs 3 3 V to XBee regardless of input voltage as long as current requirement can be met to achie...

Page 112: ...Bee in the board for this functionality to be used Move both USB direct connect switches to the right closed position and disconnect the USB micro port for correct operation of the I2C to connector Pi...

Page 113: ...reference This picture shows the XBIB C GPS module and the table that follows explains the callouts in the picture Note This GPS module is sold separately and requires an XBIB CU TH development board...

Page 114: ...th the board laying flat with the GPS module having a clear view of the sky Interface with the XBIB C GPS module The XBee Smart Modem can interface with the XBIB C GPS board through the 40 pin header...

Page 115: ...te to the XBIB C GPS module see Class UART Run the MicroPython GPS demo The Digi MicroPython github repository contains a GPS demo program that parses the GPS NMEA data from the UART and prints them N...

Page 116: ...ntly Metal objects between the transmitter and receiver can also block the radiation path or reduce the transmission distance Some objects that are often overlooked are n Metal poles n Metal studs or...

Page 117: ...118 Power supply considerations 118 Minimum connection diagram 118 Heat considerations and testing 119 Custom configuration Create a new factory default 119 Clean shutdown 120 SIM cards 121 Digi XBee...

Page 118: ...ing zero ohm resistors Power supply considerations Note XBee LTE M parts with an early revision of the microcontroller unit MCU may experience an issue recovering from brownouts under rare conditions...

Page 119: ...a steady state 3 Convert the returned value from hex format to decimal If the reading is greater than 5 C above the ambient temperature we recommend either de rating the maximum ambient temperature or...

Page 120: ...C Clean shutdown WARNING Improper shutdown of the modem may result in the underlying cellular module becoming irrecoverably unresponsive Digi strongly recommends performing a clean shutdown procedure...

Page 121: ...13 is low power may safely be removed 1 Initiate sleep Assert SLEEP_RQ 2 Wait for sleep state to be entered SLEEP pin pin 13 low 3 Power off the device Airplane mode Change the XBee configuration to u...

Page 122: ...Cellular connection process Connecting 123 Data communication with remote servers TCP UDP 123 Disconnecting 124 Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 122...

Page 123: ...device receives its IP configuration and address 4 The AI Association Indication command now returns a 0 and the sockets become available Data communication with remote servers TCP UDP Once the data...

Page 124: ...em is put into Airplane mode deep sleep is requested or ATSD shutdown command is executed 1 Sockets are closed cleanly if possible 2 The cellular connection is shut down 3 The cellular component is po...

Page 125: ...mode 126 Transparent operating mode 127 API operating mode 127 Command mode 127 MicroPython mode 129 USB direct mode 130 Bypass operating mode DEPRECATED 135 Digi XBee 3 Cellular LTE M NB IoT Global S...

Page 126: ...rough a logic level asynchronous serial port It uses a UART for serial communication with those devices The XBee Smart Modem supports three operating modes Transparent operating mode API operating mod...

Page 127: ...n set using AT commands When you want to read or set any parameter of the XBee Smart Modem using this mode you have to send an AT command Every AT command starts with the letters AT followed by the tw...

Page 128: ...ice s baud rate to 9600 and return an OK on the UART to indicate that Command mode is active When Command mode exits the device returns to normal operation at the baud rate that BD is set to Send AT c...

Page 129: ...ctory defaults Note You still have to use WR to save the changes enacted with RE Exit Command mode 1 Send CN Exit Command mode followed by a carriage return or 2 If the device does not receive any val...

Page 130: ...if you wish to enable and disable USB mode based on an external source While in USB mode the cellular modem is not able to communicate serially with the XBee MCU All communication with the cellular mo...

Page 131: ...en DO Device Options bit 2 and P0 being set to 6 have no effect on the USB VBUS state Enable USB direct mode You can enable USB direct mode in two ways 1 Enable via software Set DO Device Options bit...

Page 132: ...1 Set up USB direct mode 2 Issue the WR command to save the settings Once USB direct is configured an additional USB device should be attached to the Linux machine In order to have a consistent devic...

Page 133: ...oipdefault Accept new IP addresses from IPCP negotiations default ipcp accept local ipcp accept remote Lock the serial device lock Let the remote designate the name servers usepeerdns Enable IPv6 and...

Page 134: ...he PPP connection and shut down the modem 1 Terminate PPPD by sending a terminate signal Ctrl C 2 Issue the shutdown command to the modem over the USB connection AT CPWROFF 3 Wait for an OK response 4...

Page 135: ...e the device acts as a serial line replacement to the cellular component In this mode the XBee Smart Modem exposes all control of the cellular component s AT port through the UART If you use this mode...

Page 136: ...come active Leave Bypass operating mode To configure a device to leave Bypass operating mode 1 Set AP API Enable to something other than 5 2 Send WR Write to write the changes 3 Send FR Force Reset to...

Page 137: ...138 Pin sleep mode 138 Cyclic sleep mode 138 Cyclic sleep with pin wake up mode 138 SPI mode and sleep pin functionality 138 The sleep timer 139 MicroPython sleep behavior 139 Digi XBee 3 Cellular LT...

Page 138: ...the D7 command to enable hardware flow control the CTS pin asserts low when the device wakes and can receive serial data and de asserts high when the device sleeps Cyclic sleep with pin wake up mode...

Page 139: ...ical sleep operation This can take several seconds and this added time in the case of an unintended sleep request may not be acceptable The sleep timer The sleep timer starts when the device wakes and...

Page 140: ...g features and design recommendations Airplane mode 141 Power Saving Mode PSM 141 PSM behavior 143 Low voltage shutdown 143 Deep Sleep mode 144 Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem Use...

Page 141: ...nt off entirely to ensure readiness when exiting sleep The cellular component wakes to participate in maintaining the network state periodically based on timers negotiated with the cell tower It is al...

Page 142: ...datapoints to Digi Remote Manager XBee 3 cellular device features that periodically wake up the cellular component Features of the XBee 3 Cellular device which will automatically wake up the cellular...

Page 143: ...m the network The network is free to assign values other than those which have been requested See the LTE M Deployment Guide from GSMA for a description of what the PSM timers are and what functions t...

Page 144: ...hreshold set in the L command plus the value of the reset offset set in the M command Example The graph shown below demonstrates this feature In this example AT L Base Threshold is set to 0xC1C 3100 m...

Page 145: ...Serial interface 146 Serial data 146 UART data flow 146 Serial buffers 147 CTS flow control 147 RTS flow control 147 Enable UART or SPI ports 147 I2C 148 Digi XBee 3 Cellular LTE M NB IoT Global Smart...

Page 146: ...significant bit first and a stop bit high The following diagram illustrates the serial bit pattern of data passing through the device The diagram shows UART data packet 0x1F decimal number 31 as tran...

Page 147: ...e Serial flow control is not possible when using the SPI port RTS flow control If you set D6 DIO6 RTS to enable RTS flow control the device does not send data in the serial transmit buffer out the DOU...

Page 148: ...em User Guide 148 If both ports are disabled on reset the device uses the UART in spite of the wrong configuration so that at least one serial port is operational I2C For I2C see the Class I2C two wir...

Page 149: ...ion SPI communications 150 Full duplex operation 150 Low power operation 151 Select the SPI port 152 Force UART operation 153 Data format 153 Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User...

Page 150: ...available to send to the SPI master and it remains asserted until the SPI master has clocked out all available data In this mode n SPI clock rates up to 4 8 MHz are possible n Data is most significant...

Page 151: ...ring this time the master and slave must simultaneously transmit valid data at the clock speed so that no invalid bytes appear within an API frame causing the whole frame to be discarded An example fo...

Page 152: ...ation is complete the device queues a modem status frame to the SPI port which causes the SPI_ATTN line to assert The host can use this to determine that the SPI port is configured properly This metho...

Page 153: ...time DIN CONFIG forces a default configuration on the UART at 9600 baud and brings up the device in Command mode on the UART port You can then send the appropriate commands to the device to configure...

Page 154: ...n about using MicroPython on the XBee Smart Modem refer to the Digi MicroPython Programming Guide Overview of the file system 155 XCTU interface 156 Encrypt files 156 Digi XBee 3 Cellular LTE M NB IoT...

Page 155: ...y it is interpreted as follows n Paths starting with a forward slash are absolute and must start with flash to be valid n All other paths are relative to the current working directory n The directory...

Page 156: ...ation while it is stored on the XBee Smart Modem 2 Protection for user s MicroPython applications Use ATFS XPUT filename to place encrypted files on the file system The XPUT operation is otherwise ide...

Page 157: ...incoming TCP sockets in API mode 159 API mode behavior for outgoing TCP and TLS connections 159 API mode behavior for outgoing UDP data 160 API mode behavior for incoming TCP connections 160 API mode...

Page 158: ...s called or the MicroPython REPL is restarted using Ctrl D See Supported sockets for more information on the total number of sockets supported by the device Sockets and API mode When using API mode to...

Page 159: ...ry again later The Resource Error resolves when a Transmit TX Request that is pending on the socket is transmitted this is indicated by the Transmit TX Status frame for the request Enable incoming TCP...

Page 160: ...number of sockets so if you need to send to many destinations 1 The socket must be closed after use or 2 You must use the socket specified by the C0 Source Port setting To use the socket specified by...

Page 161: ...port as a Receive RX Packet IPv4 0xB0 frame To send data from the XBee Smart Modem to the remote destination use the Transmit TX Request IPv4 0x20 frame with the corresponding address fields received...

Page 162: ...nd protocol used for incoming connections TCP and incoming data UDP in Transparent mode TLS is not currently supported for incoming connections Note For NB IoT TCP support is dependent on the network...

Page 163: ...ep In addition for diagnostic purposes you can use the Socket Info SI AT command to retrieve information regarding all open sockets currently active in the system This can be queried during developmen...

Page 164: ...en Response 0xC6 Socket New IPv4 Client 0xCC Socket Receive 0xCD Socket Receive From IPv4 0xCE Socket Status 0xCF Extended Socket example Single HTTP Connection This example demonstrates a complete re...

Page 165: ...ee perform DNS look up during the connection process Note To adapt this example for TLS use destination port 0x01 0xbb decimal 443 Be aware that many HTTPS servers use SNI Server Name Identification w...

Page 166: ...cted status after the socket has connected Field Value Frame type 0xCF Socket Status Socket ID 0x00 Status 0x00 Connected Socket Status received from XBee with connected status 7E 00 03 CF 00 00 30 Se...

Page 167: ...eceive one or more Receive Data frames The server will respond with an interesting fact about a number The following information is a sample response Multiple frames may be needed to contain the full...

Page 168: ...58 2D 4E 75 6D 62 65 72 73 2D 41 50 49 2D 54 79 70 65 3A 20 74 72 69 76 69 61 0D 0A 50 72 61 67 6D 61 3A 20 6E 6F 2D 63 61 63 68 65 0D 0A 43 61 63 68 65 2D 43 6F 6E 74 72 6F 6C 3A 20 6E 6F 2D 63 61 63...

Page 169: ...ion is necessary prior to transmit in order to assign a known source address to all data sent from this socket Field Value Frame type 0x46 Socket Bind Listen Frame ID 0x01 Socket ID 0x00 Source Port 0...

Page 170: ...imal 10001 Transmit Options 0x00 Payload echo this Socket SendTo frame data 7E 00 13 45 01 00 34 2B 79 4D 27 11 00 65 63 68 6F 20 74 68 69 73 E5 Receive TX Status Extended sockets use the existing TX...

Page 171: ...h will reply with the time when it receives a packet Field Value Frame type 0x45 Socket SendTo Frame ID 0x01 Socket ID 0x00 Destination Address 0x34 0x2B 0x79 0x4D 52 43 121 77 Destination Port 0x27 0...

Page 172: ...4D 27 12 00 32 30 31 39 2D 30 37 2D 31 38 20 31 38 3A 35 32 3A 34 33 0A 08 Close the socket When the socket is no longer needed it should be closed to return resources to the system Field Value Frame...

Page 173: ...stener Send a Socket Create frame Note The XBee Cellular does not support incoming TLS sockets Field Value Frame type 0x40 Socket Create Frame ID 0x01 Protocol 0x01 TCP Socket Create frame data 7E 00...

Page 174: ...en Frame ID 0x01 Socket ID 0x00 Status 0x00 Success Socket Bind Listen frame received from XBee 7E 00 04 C6 01 00 00 38 Making a connection to the listener socket The IP of the XBee can be acquired th...

Page 175: ...new socket After the connection is established data received from the new socket is contained in a Socket Receive frame just like any other TCP socket Field Value Frame type 0xCD Socket Status Frame I...

Page 176: ...ener Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 176 When a Socket Status indicating a connection close is received the socket ID will have been de allocated by the XBee and no fur...

Page 177: ...Contact your network provider for details Specifying TLS keys and certificates 178 Transparent mode and TLS 179 API mode and TLS 179 Key formats 179 Certificate formats 179 Certificate limitations 179...

Page 178: ...ndicates the certificate presented to servers when requested for client authentication If client_cert is empty no certificate is presented to the server should it request one This may result in mutual...

Page 179: ...uration specified by 0 TLS Profile 0 is used to form the TLS connection Tx Request with TLS Profile 0x23 lets you choose the IP setting for the serial data Note For NB IoT TCP support is dependent on...

Page 180: ...s To work around this you have to change the certificates before making the connection or in the case of API mode specify a different authentication profile Cipher suites Note For NB IoT TCP support i...

Page 181: ...be set This enables the use of Digi Remote Manager within the firmware MO Bit 1 mask 0x2 must be set When this value is set the Remote Manager TCP connection will be secured with TLS D By default will...

Page 182: ...h server authentication Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 182 command is set to 6 to verify that the server was correctly authenticated n 0 Connected without TLS n 5 Conn...

Page 183: ...215 Sleep commands 217 Command mode options 219 MicroPython commands 221 Firmware version information commands 223 Diagnostic interface commands 227 Execution commands 231 File system commands 232 BLE...

Page 184: ...ebooted or you issue the CN Exit AT Command Mode or AC commands Parameter range N A Default N A FR Force Reset Resets the device The device responds immediately with an OK and performs a reset 100 ms...

Page 185: ...er you issue the SD command and a response has been returned either OK or ERROR issue the AI command If the shutdown was successful 2D is returned Parameter range Parameter Description 0 Shuts down th...

Page 186: ...SIM card S ICCID Reads the Integrated Circuit Card Identifier ICCID of the inserted SIM Parameter range N A Default Set by the SIM card IM IMEI Reads the device s International Mobile Equipment Ident...

Page 187: ...not when read Parameter range Parameter Description 0 Returns the most recent cached RSSI signal value received 1 Returns a fresh uncached RSSI signal value Returned values 0x71 0x33 113 dBm to 51 dB...

Page 188: ...ld be used if the module is not able to join the network because the underlying cellular modem does not have a predefined profile that supports the inserted SIM card The 1 No Profile setting does not...

Page 189: ...FFFFFFFFFF bit field Example 0x080080 bits 7 and 19 enable LTE Bands 8 and 20 Bit LTE Band 0 1 127 128 Default 0xFFFFFFFFFFFFFFFF bands 1 64 enabled BN Bandmask NB IoT Note This command is for use wit...

Page 190: ...ogy Allows the XBee 3 Cellular LTE M NB IoT module to select the preferred network technology A reboot or power cycle is required for any parameter changes to become active Note For the N command conf...

Page 191: ...Returns the Reference Signal Received Power RSRP value The value returned is in hex and should be converted by the user with the following formula RSRP hex_value 0xA Example The value returned from t...

Page 192: ...20 A single ASCII space that indicates there is no cellular user name CW Cellular password Specifies the password used when authenticating to the cellular network This command is write only Parameter...

Page 193: ...security layer profile manager USECPRF heading Parameter range 0 4 Value Description 0x00 UDP 0x01 TCP 0x02 SMS Transparent mode 0x03 Reserved 0x04 TLS over TCP Default 0x01 TL TLS Protocol Version Se...

Page 194: ...ASCII characters Default N A 1 TLS Profile 1 Specifies the TLS certificate s to use for Tx Request with TLS Profile 0x23 transmissions with profile set to 1 Note For NB IoT TCP support is dependent o...

Page 195: ...s Default 0xBB8 5 minutes TS IP Server Connection Timeout The IP server connection timeout If no activity for this timeout then the connection is closed When set to 0 the connection is closed immediat...

Page 196: ...scription 0 Enable Remote Manager 2 Enable USB Direct 3 Enable PSM 4 Enable the Low Voltage Shutdown feature 5 Enable eDRX Note We strongly recommend that you clear bit 0 Enable Remote Manager if you...

Page 197: ...e or registration with the network has not yet been achieved an empty response is returned Parameter range N A Default N A PG Ping Sends an ICMP Echo Request to the specified host and reports round tr...

Page 198: ...assigned by the mobile network In API mode the address is represented as the binary four byte big endian numeric value representing the IPv4 address In Transparent or Command mode the address is repre...

Page 199: ...N2 DNS Address Displays the IPv4 address of the secondary domain name server Parameter Range Read only Default 0 0 0 0 waiting on cellular connection DL Destination Address The destination IPv4 addre...

Page 200: ...sparent mode This command reads all input as hexadecimal All values must be entered in hexadecimal with no leading 0x For example the destination port 9001 has the hexadecimal value of 0x2329 The comm...

Page 201: ...ess of FQDN Performs a DNS lookup of the given fully qualified domain name FQDN and outputs its IP address When you issue LA in API mode the IP address is formatted in binary four byte big endian nume...

Page 202: ...e device interprets any value between 0x4B0 and 0x0EC400 as a custom baud rate Custom baud rates are not guaranteed and the device attempts to find the closest achievable baud rate After setting a non...

Page 203: ...cter silence required before transmission begins when operating in Transparent mode RF transmission also starts after the maximum packet size for the selected protocol is received in the UART receive...

Page 204: ...led the UART data must be formatted as API frames because Transparent mode is disabled See Modes for more information Parameter range 0x00 0x05 Parameter Description 0x00 API disabled operate in Trans...

Page 205: ...T Global Smart Modem User Guide 205 Parameter range Parameter Description 0x0 1200 b s 0x1 2400 b s 0x2 4800 b s 0x3 9600 b s 0x4 19200 b s 0x5 38400 b s 0x6 57600 b s 0x7 115200 b s 0x8 230400 b s 0x...

Page 206: ...firmware versions ending in 17 and newer When D0 is set to 6 the DIO0 pin mirrors the state of the cellular component s power monitoring pin V_INT DIO0 is driven low 0V when the cellular component is...

Page 207: ...plays the DIO2 AD2 configuration pin 18 Parameter range 0 5 Description 0 Disabled 1 SPI_CLK 2 Analog input 3 Digital input 4 Digital output default low 5 Digital output default high Default 0 D3 DIO3...

Page 208: ...DICATOR configuration pin 15 Parameter range 0 1 3 5 Parameter Description 0 Disabled 1 Associated LED 2 N A 3 Digital input 4 Digital output default low 5 Digital output default high Default 1 D6 DIO...

Page 209: ...d 1 CTS flow control 2 N A 3 Digital input 4 Digital output default low 5 Digital output default high Default 0x1 D8 DIO8 SLEEP_REQUEST Sets or displays the DIO8 DTR SLP_RQ configuration pin 9 Paramet...

Page 210: ...O10 PWM0 Configuration Sets or displays the PWM DIO10 configuration pin 6 This command enables the option of translating incoming data to a PWM so that the output can be translated back into analog fo...

Page 211: ...ode and also during Airplane Mode 2 Enables PWM output 3 Digital input 4 Digital output default low 5 Digital output default high 6 I2C SDA 7 USB direct Default 0 P2 DIO12 Configuration Sets or displa...

Page 212: ...he bit is not set in PR the device uses PD Note Resistors are not applied to disabled lines See PR Pull up down Resistor Enable for bit mappings which are the same Parameter range 0x0 0x7FFF Default 0...

Page 213: ...n SLEEP pin 13 10 DIO12 pin 4 11 DIO10 pin 6 12 DIO11 pin 7 13 DIO7 CTS pin 12 14 DIO13 DOUT pin 17 Parameter range 0 0x7FFF bit field Default 0x7FFF M0 PWM0 Duty Cycle Sets the duty cycle of PWM0 pin...

Page 214: ...O settings commands Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 214 M1 command Sets the duty cycle of PWM1 for P1 2 where a value of 0x200 is a 50 duty cycle Parameter range 0 0x3...

Page 215: ...cimal notation The interpretation of the lines is n Number of samples For legacy reasons this field always returns 1 n Digital channel mask A bit mask of all I O capable pins in the system The bits se...

Page 216: ...AT commands I O sampling commands Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 216 Field Size Analog chanel mask 1 byte Samples 2 bytes each Parameter range N A Default N A...

Page 217: ...Sleep In this mode the device repeatedly sleeps for the value specified by SP and spends ST time awake 5 Cyclic Sleep with Pin Wake In this mode the device acts as in Cyclic Sleep but does not sleep...

Page 218: ...oT TCP support is dependent on the network Contact your network provider for details Parameter range 0 0xFFFF 0 65535 1 s Default 0xa 10 s PU Requested Tracking Area Update Timer The requested Active...

Page 219: ...tently entering Command mode Parameter range 0 0xFF Default 0x2B the ASCII plus character CT Command Mode Timeout Sets or displays the Command mode timeout parameter If a device does not receive any v...

Page 220: ...AT commands Command mode options Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 220 Default 0x3E8 one second...

Page 221: ...le function in the MicroPython REPL refer to the Digi MicroPython Programming Guide The PYB sub command reports details of the bundled code In Command mode it returns two lines of text for example byt...

Page 222: ...Global Smart Modem User Guide 222 PY Interrupt Program Sends KeyboardInterrupt to MicroPython This is useful if there is a runaway MicroPython program and you have filled the stdin buffer You can ent...

Page 223: ...n including the application build date and time Parameter range N A Default Set in firmware HV Hardware Version Read the device s hardware version Use this command to distinguish between different har...

Page 224: ...ssing corrupt or otherwise in error The cellular component requires a new firmware image 0x25 Cellular network registration denied 0x2A Airplane mode 0x2B USB Direct active 0x2C Cellular component is...

Page 225: ...face The FO command has sub commands that either set or read a parameter initiate the FTP OTA ATFOI or clears the parameters ATFOC The table below shows the FTP OTA parameters that can be set and thei...

Page 226: ...lar LTE M NB IoT Global Smart Modem User Guide 226 ATFOC ATFOC clears all parameters back to their defaults as listed in the table above Example usage Setting a parameter ATFOSmyftp server com OK Read...

Page 227: ...in progress 0x03 Disconnecting from Remote Manager 0x04 Not configured for Remote Manager 0x05 Connected over TLS 0x06 Connected over TLS with authenticated server Default N A CI Protocol Connection...

Page 228: ...iption 0x00 The socket is open 0x01 Tried to send but could not 0x02 Invalid parameters bad IP host 0x03 TCP not supported on this cellular component 0x10 Not registered to the cell network 0x11 Cellu...

Page 229: ...u run the command the cell module waits until all other communication is idle and then performs the scan The information that can be reported by this command varies based on the network technology of...

Page 230: ...AT commands Diagnostic interface commands Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 230 Parameter range N A Default N A...

Page 231: ...eters The XBee Smart Modem tears down any TCP UDP sockets and resets Internet connectivity The XBee Smart Modem responds immediately with an OK on the UART and then causes a network restart You can al...

Page 232: ...rors start with a capital E followed by one or more uppercase letters and digits a space and an description of the error If writing your own AT command parsing code you can determine if an FS command...

Page 233: ...le test txt SHA256 n On Mac and Linux use shasum b a 256 test txt ATFS GET filename Starts a YMODEM send of filename on the XBee device When it is ready to send the XBee Smart Modem sends a prompt Sen...

Page 234: ...0 bad 900096 total ATFS FORMAT confirm Reformats the file system leaving it with a default directory structure Pass the word confirm as the first parameter to confirm the format The XBee Smart Modem r...

Page 235: ...s value is populated Parameter range A string of case sensitive ASCII printable characters from 1 to 22 bytes in length Default 0x20 an ASCII space character BL Bluetooth MAC address The BL command re...

Page 236: ...lue where each command represents 32 bytes of the total 128 byte verifier value Note XBee device does not allow for 0 to be valid salt If the value is 0 SRP is disabled and you will not be able to aut...

Page 237: ...d com K1 Remote Manager Server Send Keepalive Specify the Remote Manager Server Send Transmit Keepalive Interval value in seconds The XBee device considers a Remote Manager connection to have failed a...

Page 238: ...which may otherwise result in excessive data usage See Configure Remote Manager keepalive interval Parameter range 0 7 Bit Description 0 Maintains a persistent TCP connection to Remote Manager 1 TCP...

Page 239: ...x3c HM Health Metrics Sets the Health Metrics to report This is a bit mask of values Each bit set in the mask represents a metric which is reported to Remote Manager Parameter range N A Bit Descriptio...

Page 240: ...orted to Remote Manager The reported metrics are as follows n metrics udp sent UDP data sent from the device n metrics udp received UDP data received 4 Link Deactivations Set bit 4 to enable reporting...

Page 241: ...ection to Remote Manager can be idle When the time limit is met the TCP connection is closed For example you can use this command to adjust the desired timeout when a TCP connection is used without a...

Page 242: ...fined physical location for the XBee displayed in Remote Manager Range Up to 20 ASCII characters Default One ASCII space character 0x20 KP Device Description Sets or displays a user defined descriptio...

Page 243: ...fter the socket ID for non Extended API Sockets which are sockets created implicitly when using IPv4 TX API frames In the example below the 0x00 socket is an IPv4 TX RX socket and the 0x01 and 0x02 so...

Page 244: ...ocket REMOTE_ADDRESS The remote IPv4 address for the given socket This is 0 0 0 0 for an unconnected socket Parameter range 0x00 0xFE Default Power measurement commands The following commands enable y...

Page 245: ...mV Default 0xBB8 mV M Low voltage shutdown reset offset The voltage offset in millivolts above L command Low voltage shutdown base threshold at which the XBee recovers from a shutdown state by resetti...

Page 246: ...Operate in API mode API mode overview 247 Use the AP command to set the operation mode 247 API frame format 247 Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 246...

Page 247: ...ity to filter out additional API frames with unknown frame types into your software interface Use the AP command to set the operation mode Use AP API Enable to specify the operation mode AP command se...

Page 248: ...rded For more information on using this API mode see the Escaped Characters and API Mode 2 in the Digi Knowledge base API escaped operating mode works similarly to API mode The only difference is that...

Page 249: ...Note that the length and checksum are the same as the non escaped frame Start delimiter Length Frame type Frame Data Checksum Data 7E 00 0F 17 01 00 7D 33 A2 00 40 AD 14 2E FF FE 02 4E 49 6D The lengt...

Page 250: ...A Length bytes 01 API identifier 01 API frame ID 50 01 Destination address low 00 Option byte 48 65 6C 6C 6F Data packet B8 Checksum To calculate the check sum you add all bytes of the packet excludin...

Page 251: ...D 267 BLE Unlock API 0x2C 268 BLE Unlock Response 0xAC 272 Socket Create 0x40 273 Socket Create Response 0xC0 274 Socket Option Request 0x41 275 Socket Option Response 0xC1 276 Socket Connect 0x42 277...

Page 252: ...the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x08 Byte Frame ID Byte Identifies the data frame for the host to...

Page 253: ...eturns register queries immediately and not does not queue them The response for this command is also an AT Command Response frame 0x88 Format The following table provides the contents of the frame Fo...

Page 254: ...ependent on the network Contact your network provider for details Format The following table provides the contents of the frame For details on frame structure see API frame format Field name Field val...

Page 255: ...es the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x20 Byte Frame ID Byte Reference identifier used to match stat...

Page 256: ...ork provider for details Transmit options Byte bitfield Bit fields are offset 0 Bit field 0 7 Bits 0 and 2 7 are reserved bit 1 is not BIT 1 1 Terminate the TCP socket after transmission is complete 0...

Page 257: ...d value Data type Description Frame type 0x23 Byte Frame ID Byte Reference identifier used to match status responses 0 disables the TX Status frame Destination address 32 bit big endian Destination po...

Page 258: ...eld Bit fields are offset 0 Bit field 0 7 Bits 0 and 2 7 are reserved bit 1 is not BIT 1 1 Terminate the TCP socket after transmission is complete 0 Leave the socket open Closed by timeout see TM IP C...

Page 259: ...me For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x88 Byte Frame ID Byte Identifies the data frame for the host to correlate with a subseq...

Page 260: ...ed in a previous transmit frame Status Byte Status code see the table below The following table shows the status codes Code Description 0x0 Successful transmit 0x20 Connection not found 0x21 Failure t...

Page 261: ...epting frames See User Data Relay 0x2D 0x7E A modem update is in progress Try again after the update is complete 0x80 Connection refused 0x81 Socket connection lost 0x82 No server 0x83 Socket closed 0...

Page 262: ...reset 2 Registered with cellular network 3 Unregistered with cellular network 0x0E Remote Manager connected 0x0F Remote Manager disconnected 0x32 BLE Connect 0x33 BLE Disconnect 0x34 Bandmask configur...

Page 263: ...r NB IoT SMS support is dependent on the network Contact your network provider for details Format The following table provides the contents of the frame For details on frame structure see API frame fo...

Page 264: ...ng table provides the contents of the frame For details on frame structure see API frame format Frame data fields Offset Description Frame type 3 0xB0 IPv4 32 bit source address MSB 4 The address in t...

Page 265: ...estination interface Byte 0 Serial port SPI or UART when in API mode 1 BLE 2 MicroPython Data Variable Error cases The Frame ID is used to report error conditions in a method consistent with existing...

Page 266: ...he frame over the UART with the BLE interface as a target This outputs the data contained in the frame as the Output Frame over the active BLE connection via indication n An external processor outputs...

Page 267: ...ut on The frame can be sent or received from any of the following interfaces MicroPython internal interface UART and BLE This frame is used in conjunction with User Data Relay 0x2D Format The followin...

Page 268: ...d session key which is used to communicate in an encrypted fashion with the peer Additionally a Modem Status 0x8A with the status code 0x32 Bluetooth Connected is sent through the UART if AP 1 or 2 Wh...

Page 269: ...ith content usually due to A mod N 0 0x81 Incorrect payload length 0x82 Bad proof of key 0x83 Resource allocation error 0x84 Request contained a step not in the correct sequence Payload 5 Payload stru...

Page 270: ...hared during authentication Initial remaining counter value is 1 The counter for data sent into the XBee API Service is prefixed with the TX nonce value see the Phase 4 table above and the counter for...

Page 271: ...271 expected to process these indications and the response data is not available if you attempt to perform a read operation to the characteristic d Decrypt the stream of content provided through the i...

Page 272: ...272 BLE Unlock Response 0xAC Description The XBee Smart Modem uses the BLE Unlock API 0x2C frame to authenticate a connection on the Bluetooth interface and unlock the processing of AT command frames...

Page 273: ...ing protocols TCP UDP or TLS Format The following table provides the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0...

Page 274: ...frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0xC0 Byte Frame ID Byte A reference identifier used to match status responses Socket I...

Page 275: ...of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x41 Byte Frame ID Byte A reference identifier used to match status responses...

Page 276: ...e structure see API frame format Field name Field value Data type Description Frame type 0xC1 Byte Frame ID Byte Identifier provided in request Socket ID Byte The socket ID for which modification was...

Page 277: ...n this socket until after a Socket Status frame has been received indicating success Format The following table provides the contents of the frame For details on frame structure see API frame format F...

Page 278: ...f the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0xC2 Byte Frame ID Byte A reference identifier used to match status responses So...

Page 279: ...ockets Format The following table provides the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x43 Byte Frame ID Byte...

Page 280: ...ucceed for a socket that exists the status can be only one of two values Success or Bad socket ID Format The following table provides the contents of the frame For details on frame structure see API f...

Page 281: ...ce responds with a Transmit TX Status 0x89 frame with an error To send data from a UDP socket that is not connect use a Socket SendTo 0x45 frame Format The following table provides the contents of the...

Page 282: ...d You must perform a Socket Bind Listen 0x46 frame for a UDP connection before you attempt a SendTo in order to assign a source port Format The following table provides the contents of the frame For d...

Page 283: ...h the remote address information For a UDP socket this frame binds the socket to a given port A bound UDP socket can receive data with a Socket Receive From IPv4 0xCE frame Format The following table...

Page 284: ...nts of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0xC6 Byte Frame ID Byte Resource identifier used to match status responses...

Page 285: ...inal listener s socket ID and a new socket ID of the incoming connection along with the connection s remote address information Format The following table provides the contents of the frame For detail...

Page 286: ...e following table provides the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Frame type 0xCD Byte Frame ID Byte Optional This f...

Page 287: ...ding addressing information about the source Format The following table provides the contents of the frame For details on frame structure see API frame format Field name Field value Data type Descript...

Page 288: ...l and the Socket ID is closed and invalid after receipt 0x01 Failed DNS lookup 0x02 Connection refused 0x03 Transport closed 0x04 Timed out 0x05 Internal error 0x06 Host unreachable 0x07 Connection lo...

Page 289: ...ID Identifies the data frame for the host to correlate with a subsequent response If set to 0 the device will not emit a response frame 5 8 bit File System Command See File System Commands for valid c...

Page 290: ...ess Response lists the fields following the Status byte when 0 indicating a successful operation and is only listed for commands with additional fields after the Status byte n See Local File System Re...

Page 291: ...0 SECURE Create a secure write only file 9 n variable File Name Pathname relative to Path ID Success Response Offset Size Frame Field Description 5 8 bit File System Command File open 0x01 6 8 bit Sta...

Page 292: ...sponse frame size Success Response Offset Size Frame Field Description 5 8 bit File System Command File Read 0x03 6 8 bit Status Success 0x00 7 16 bit File Handle Value sent in request 9 32 bit Data O...

Page 293: ...ownloading the entire file On XBee Cellular modules there is a response delay in order to calculate the hash of a non secure file Request Offset Size Frame Field Description 5 8 bit File System Comman...

Page 294: ...ory Handle was automatically released 4 If the listing is not complete do one of the following n Send a Directory Read Request to get additional directory entries n Send a Directory Close Request to r...

Page 295: ...ile Size and Flags Refer to description above n 6 variable Entry Name Refer to description above Process the entries in a Directory Open Response or Directory Read Response as follows n Split the File...

Page 296: ...ath ID request to generate a Path ID for any subdirectory of the file system to allow the use of shorter relative pathnames in later requests n If the Path ID field of a Request is 0x0000 the Response...

Page 297: ...er File System Requests with relative pathnames 9 n variable Full Pathname If short enough to fit in the frame the full pathname starting with flash Deep subdirectories may return an empty field inste...

Page 298: ...usable bytes on volume Volume Format 0x4F Description Format the space allocated to file storage This command sends a Volume Info Success Response when the format completes Request Offset Size Frame F...

Page 299: ...for valid command values 6 8 bit Status See Status Values for description 7 n variable Response Data Variable content based on File System Command Only present if Status is 0 and the command has addi...

Page 300: ...TE M NB IoT Global Smart Modem User Guide 300 Value Command 0x57 Hardware failure 0x58 Volume offline format required 0x59 Volume full 0x5A Operation timed out 0x5B Busy wait for prior command to comp...

Page 301: ...The table below shows a list of features that are supported in the regulatory firmware Feature Description Firmware upgrade Use XCTU or Digi Remote Manager to upgrade the device to or from the regulat...

Page 302: ...completed your testing using the regulatory firmware you should re install the device firmware Install regulatory firmware using Remote Manager You can install the regulatory firmware on your XBee fr...

Page 303: ...ting using the regulatory firmware you should re install the device firmware Configure regulatory firmware for testing the Bluetooth radio In XCTU or command mode set the following configurations 1 Tu...

Page 304: ...the requested transmit power Setup 0 6 Transmit power in dBm only 1 dB resolution available ranging from 0 to 17 dBm N A leave as 0 Override the packet type This will supersede the packet type specif...

Page 305: ...is time you may see the module in the error 5 state temporarily n If the error state persists or the status value persistently changes between 1 and 5 double check that the EARFCN AT 8 and power AT A...

Page 306: ...normal cellular component features will not be available Example Stop test mode AT 2 5 Start modulated transmit Use this command to start modulated transmit using the EARFCN and power specified by AT...

Page 307: ...umber that was set using AT 7 Parameter range N A Example Get the EARFCN AT 8 9 Set transmit power Use this command to set the transmit power Parameter range 0 FFF hexadecimal Variant range 40 to 24 d...

Page 308: ...A D Start receive mode Use this command to start receive mode on the EARFCN channel specified using AT 7 Parameter range N A Examples Start receive mode AT D Query test state Use this command to quer...

Page 309: ...ct a macOS Java error 312 Unresponsive cellular component in Bypass mode 313 Syntax error at line 1 313 Error Failed to send SMS 313 Network connection issues 314 Brownout issue 314 Hardware flow cont...

Page 310: ...cted to does not appear Solution 1 Click the Discover radio modules button 2 Select all of the ports to be scanned 3 Click Next and then Finish A dialog notifies you of the devices discovered and thei...

Page 311: ...r and USB from the XBIB CU TH board and reconnect it 4 If you have a driver installed and updated but still have issues on Windows 10 you may have to enable VCP on the driver see Enable Virtual COM po...

Page 312: ...r you may encounter a Java error Condition When opening XCTU for the first time on a macOS computer you may see the following error Solution 1 Click More info to open a browser window 2 Click Download...

Page 313: ...ntax error at line 1 You may get a syntax error at line 1 error after pasting example MicroPython code and pressing Ctrl D Solution This commonly happens when you accidentally type a character at the...

Page 314: ...avoid this condition Voltage brownout This issue may occur if the supply powering the XBee VCC pin dips momentarily into the range of approximately 1 2 to 1 8 V When the supply returns to normal leve...

Page 315: ...ent away from its default you will lose communication with the cellular component while in Bypass mode In firmware version 14 and later the IB Cellular Component Baud Rate command was added to control...

Page 316: ...ication reports 0x13 Socket leak API mode Transmit TX Status 0x89 status 0x32 Resource error retry operation later MicroPython When attempting to make a connection to a server you receive errno ENFILE...

Page 317: ...latory information United States FCC 318 Innovation Science and Economic Development Canada ISED 321 Mexico IFETEL 322 Brazil ANATEL 323 Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide...

Page 318: ...for use with other products without any further certification as per FCC section 2 1091 Modifications not expressly approved by Digi could void the user s authority to operate the equipment IMPORTANT...

Page 319: ...ve articulated RPSMA 4 5 2 1 dBi Fixed Mobile A24 HASM 450 Dipole Half wave articulated RPSMA 4 5 2 1 dBi Fixed Mobile A24 HABSM Dipole Articulated RPSMA 2 1 dBi Fixed A24 HABUF P5I Dipole Half wave b...

Page 320: ...quirements 2 1 General No requirements are associated with this section 2 2 List of applicable FCC rules This module conforms to FCC Parts 27 cellular 2 3 Summarize the specific operational use condit...

Page 321: ...ins IC 8595A 2AGQN4NNN The integrator is responsible for its product to comply with IC ICES 003 FCC Part 15 Sub B Unintentional Radiators ICES 003 is the same as FCC Part 15 Sub B and Industry Canada...

Page 322: ...of a type and maximum or lesser gain approved for the transmitter by Industry Canada To reduce potential radio interference to other users the antenna type and its gain should be so chosen that the eq...

Page 323: ...te equipo o dispositivo debe aceptar cualquier interferencia incluyendo la que pueda causar su operaci n no deseada Brazil ANATEL The XBee 3 Cellular LTE M NB IoT Smart Modem radio modules comply with...

Page 324: ...upgrade XCTU 5 Update the device and cellular firmware using XCTU 6 Configure your module for cellular connectivity 7 Check for cellular registration and connection 8 Use one of the following methods...

Page 325: ...board One 12 V power supply One cellular antenna with U FL connector One Bluetooth Low Energy BLE antenna One USB cable One XBee Smart Modem Note The XBee Smart Modem comes attached to the board in ES...

Page 326: ...o the XBee If a SIM card is not included install the SIM card into the XBee before attaching the XBee device to the board Note Some kits do not include a SIM card Contact your mobile carrier provider...

Page 327: ...when connecting or removing the antennas We recommend using a U FL removal tool 5 Plug the 12 V power supply to the power jack on the development board The LED indicator blinks when the board is power...

Page 328: ...orrect operation Plug in the external power supply prior to the USB connector to ensure that proper USB communications are not interrupted 6 LED indicator Yellow Modem sending serial UART data to host...

Page 329: ...XBIB U DEV reference Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 329 Number Item Description 15 20 pin header Maps to standard through hole XBee pins Male Samtec header part number...

Page 330: ...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...

Page 331: ...kit PN XK3 C A2 UT U or XK3 C N1 UT E Example turn on an LED Digi XBee 3 Cellular LTE M NB IoT Global Smart Modem User Guide 331 led value 1 You have successfully controlled an LED on the board using...

Reviews:

No comments