Digi XBee3 XB3M1, User Manual

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

Page 2: ...l rights reserved Disclaimers Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International Digi provides this document as is without warranty of any kind expressed or implied including but not limited to the implied warranties of fitness or merchantability for a particular purpose Digi may make improvements and or changes in...

Page 3: ...ct 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 techcomm digi com Include the document title and part number Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 90002258 I in the subject line of your email Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 3 ...

Page 4: ...ellular service 29 Configure and update your XBee 30 Add a device 30 Update to the latest firmware from XCTU 31 Configure your module for cellular connectivity 31 Check for cellular registration and connection 33 Update an XBee module from A2 00 to A2 01 using API mode 34 Update an XBee module from A2 00 to A2 01 using FOTA 37 XBee bootloader 39 XBee connection examples Connect to the Echo server ...

Page 5: ... Use picocom in Linux 70 Get started with BLE Enable BLE on an XBee device 72 Enable BLE and configure the BLE password using XCTU 72 Get the Digi XBee Mobile phone application 73 Connect with BLE and configure your XBee device 74 BLE reference 74 BLE advertising behavior and services 74 Device Information Service 74 XBee API BLE Service 75 API Request characteristic 75 API Response characteristic...

Page 6: ...RF characteristics 100 Cellular networking specifications 100 Power requirements 101 Power consumption 102 Electrical specifications 103 Regulatory approvals 104 Hardware Mechanical drawings 106 Pin signals 106 Pin connection recommendations 107 RSSI PWM 108 SIM card 108 Associate LED functionality 108 Antenna recommendations Antenna placement 111 Design recommendations Cellular component firmware...

Page 7: ...t mode 125 Configure the data pins 125 Enable USB direct mode 125 Bypass operating mode DEPRECATED 125 Enter Bypass operating mode 126 Leave Bypass operating mode 126 Restore cellular settings to default in Bypass operating mode 126 Sleep modes About sleep modes 128 Normal mode 128 Pin sleep mode 128 Cyclic sleep mode 128 Cyclic sleep with pin wake up mode 128 SPI mode and sleep pin functionality ...

Page 8: ...r outgoing TCP and SSL connections 147 API mode behavior for outgoing UDP data 148 API mode behavior for incoming TCP connections 148 API mode behavior for incoming UDP data 149 Transparent mode behavior for outgoing TCP and SSL connections 149 Transparent mode behavior for outgoing UDP data 150 Transparent mode behavior for incoming TCP connections 150 Transparent mode behavior for incoming UDP c...

Page 9: ...le 0 166 1 SSL TLS Profile 1 166 2 SSL TLS Profile 2 166 TM IP Client Connection Timeout 167 TS IP Server Connection Timeout 167 DO Device Options 167 DT Cellular Network Time 168 Addressing commands 169 SH Serial Number High 169 SL Serial Number Low 169 MY Module IP Address 169 P Destination Phone Number 169 N1 DNS Address 170 N2 DNS Address 170 DL Destination Address 170 OD Operating Destination...

Page 10: ...de options 187 CC Command Sequence Character 187 CT Command Mode Timeout 187 CN Exit Command mode 187 GT Guard Times 187 MicroPython commands 189 PS Python Startup 189 PY MicroPython Command 189 Firmware version information commands 191 VR Firmware Version 191 VL Verbose Firmware Version 191 HV Hardware Version 191 AI Association Indication 191 HS Hardware Series 192 CK Configuration CRC 192 Diagn...

Page 11: ...rting Frequency 204 HM Health Metrics 204 System commands 205 KL Device Location 205 KP Device Description 205 KC Contact Information 205 Operate in API mode API mode overview 207 Use the AP command to set the operation mode 207 API frame format 207 API operation AP parameter 1 207 API operation with escaped characters AP parameter 2 208 API frames AT Command 0x08 212 AT Command Queue Parameter Va...

Page 12: ...Virtual COM port VCP on the driver 240 Correct a macOS Java error 241 Condition 241 Solution 241 Unresponsive cellular component in Bypass mode 242 Condition 242 Solution 242 Syntax error at line 1 242 Solution 242 Error Failed to send SMS 242 Solution 242 Network connection issues 243 Condition 243 Solution 243 Brownout issue 243 Voltage brownout 243 Power on discontinuities 243 How to distinguis...

Page 13: ...Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 13 RF Exposure 250 CE mark Europe 251 ...

Page 14: ...rent mode n Command mode n Bypass to the raw cellular modem n SMS Some carriers do not support SMS on LTE M and or NB IoT Check with your carrier for details n TCP UDP up to six sockets n TLS up to six sockets n Incoming connections n MicroPython l On module programmability to add local intelligence l Many examples in the Digi MicroPython Programming Guide l AT commands for managing run time behav...

Page 15: ...M interface supports both 1 8 V and 3 V SIM types NB IoT network NB IoT network is supported by XBee3 Cellular Note the following n NB IoT does not support roaming You cannot roam between networks n For NB IoT TCP support is dependent on the network Contact your network provider for details n For NB IoT SMS support is dependent on the network Contact your network provider for details n Digi Remote...

Page 16: ...r cellular connection n Connect to the Echo server n Connect to the ELIZA server n Connect to the Daytime server Optional steps You can review the information in these steps for more XBee connection examples and examples of how to use MicroPython 1 Review additional connection examples to help you learn how to use the device See XBee connection examples 2 Review introductory MicroPython examples Y...

Page 17: ...ng One XBIB U DEV board One 12 V power supply One cellular antenna with U FL connector One Bluetooth Low Energy BLE antenna One USB cable One XBee Smart Modem Note The XBee Smart Modem comes attached to the board in ESD wrap One SIM card Note NB IoT kits Digi product number XK3 C N1 UT E do not include a SIM card Contact your NB IoT mobile carrier provider to obtain a SIM card and service See Acqu...

Page 18: ...on when you get service See Configure your module for cellular connectivity The APN for NB IoT on T Mobile may be iot nb You should confirm the APN when you set up service You can contact Digi Sales at www digi com contactus for information about obtaining NB IoT service European customers If you are using the NB IoT European kit you must purchase a SIM card before you can connect the hardware Con...

Page 19: ...d install the SIM card into the XBee Smart Modem before attaching the XBee device to the board Note NB IoT kits Digi product number XK3 C N1 UT E do not include a SIM card Contact your NB IoT mobile carrier provider to obtain a SIM card and service See Acquire a SIM card WARNING Never insert or remove the SIM card while the device is powered 3 Attach the XBee device to the board 4 Connect the ante...

Page 20: ... is fragile and is not designed for multiple insertions so exercise caution when connecting or removing the antennas We recommend using a U FL removal tool 5 Plug the 12 V power supply to the power jack on the development board The LED indicator blinks when the board is powered 6 Connect the USB cable from a PC to the USB port on the development board The computer searches for a driver which can t...

Page 21: ... Development Kit XBIB U DEV reference Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 21 XBIB U DEV reference This picture shows the XBee USB development board and the table that follows explains the callouts in the picture ...

Page 22: ...SB connector to ensure that proper USB communications are not interrupted 6 LED indicator Yellow Modem sending serial UART data to host Green Modem receiving serial UART data from host Red Associate 7 USB Connects to your computer 8 RSSI indicator See RSSI PWM On the XBIB U more lights are better 9 User buttons Connected to DIO lines for user implementation 10 Reset button Press the reset button t...

Page 23: ...IB CU TH reference Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 23 XBIB CU TH reference This picture shows the XBee CU TH development board and the table that follows explains the callouts in the picture Note This module is sold separately ...

Page 24: ...y flow to the VCC pin of the XBee When active the VCC pin of the XBee is disconnected from the 3 3 V line on the development board This allows current measurement to be conducted by attaching a current meter across the jumper P10 3 Battery Connector If desired a battery can be attached to provide power to the development board The voltage can range from 2 V to 5 V The positive terminal is on the l...

Page 25: ...he XBee 9 Grove Connector This connector can be used to attach I2C enabled devices to the development board Note that I2C needs to be available on the XBee in the board for this functionality to be used Pin 1 I2C_CLK XBee DIO1 Pin2 I2C_SDA XBee DIO11 Pin3 VCC Pin4 GND 10 Temp Humidity Sensor This as a Texas Instruments HDC1080 temperature and humidity sensor This part is accessible through I2C Be ...

Page 26: ...ture shows the XBIB C GPS module and the table that follows explains the callouts in the picture Note This module is sold separately You must also have purchased an XBIB CU TH development board Note For a demo of how to use MicroPython to parse some of the GPS NMEA sentences from the UART print them and report them to Digi Remote Manager see Run the MicroPython GPS demo ...

Page 27: ... blox This is what makes the GPS measurements Proper orientation is with the board laying completely flat with the module facing towards the sky Interface with the XBIB C GPS module The XBee Smart Modem can interface with the XBIB C GPS board through the large 40 pin header This header is designed to fit into XBIB C development board This allows the XBee Smart Modem in the XBIB C board to communic...

Page 28: ...mmunicate to the XBIB C GPS module see Class UART Run the MicroPython GPS demo The Digi MicroPython github repository contains a GPS demo program that parses some of the GPS NMEA sentences from the UART prints them and also reports them to Digi Remote Manager Note If you are unfamiliar with MicroPython on XBee you should first run some of the tutorials earlier in this manual to familiarize yoursel...

Page 29: ...o run the gpsdemo1 py 4 Open XCTU and use the MicroPython Terminal to run the demo 5 Type CTRL R from the MicroPython prompt to run the code Cellular service Digi now offers Cellular Bundled Service plans This service includes pre configured cellular data options that are ideal for IoT applications bundled together with Digi Remote Manager for customers who want to remotely monitor and manage thei...

Page 30: ...ou can use XCTU to update the firmware 1 To use XCTU you may need to install FTDI Virtual COM port VCP drivers onto your computer Click here to download the drivers for your operating system 2 Upgrade XCTU to version 6 4 2 or later This step is required 3 You must add a device to XCTU before you can update the device s firmware from XCTU 4 Update to the latest firmware from XCTU Configure your mod...

Page 31: ...rsion 1140F reorganizes the product s flash memory and upgrades the product to version 11410 You cannot downgrade to a version earlier than 11410 after installing 1140F 11410 You also need to use XCTU version 6 4 2 or later Note If you have already updated the firmware in a previous step this process is not necessary 1 Launch XCTU 2 Click the Configuration working modes button 3 Select a local XBe...

Page 32: ...carriers require an APN If the carrier does not require an APN you should not change the APN from the default 1 Click the Configuration working modes button 2 Select an XBee module from the Radio Modules list 3 Set the APN using the AN command You should get the APN from your carrier when you purchased your SIM card See Acquire a SIM card To set the APN in the AN field type the APN value from your...

Page 33: ...lopment board blinks when the XBee Smart Modem is registered to the cellular network see Associate LED functionality If the LED remains solid registration has not occurred properly Registration typically takes 5 6 minutes the first time a device is connected to the network Note Make sure you are in an area with adequate cellular network reception or the XBee Smart Modem will not make the connectio...

Page 34: ...e on the UART interface same ATBD value n The machine that will be performing the update must have Python 3 6 or higher installed and the script must be run using Python 3 n The machine that will be performing the update must have visibility to an HTTP server hosting the files n The script dependencies must be satisfied by running pip install r requirements txt in the directory containing the scri...

Page 35: ...verbose Also emit log messages about communications with the XBee default False For additional help see the XBee3 Cellular LTE M NB IoT user guide or contact Digi Technical Support at tech support digi com Example Examples of usage C Users admin over the wire C Users admin AppData Local Programs Python Python37 32 python exe update py COM17 Run the update script The serial port COM port or dev tty...

Page 36: ... 0 00 00 05 06 A 02 01 2019 06 27 16 06 28 502 update py INFO Cellular component update successful 2019 06 27 16 06 28 503 update py INFO Restoring previous baud rate and RTS CTS configuration 2019 06 27 16 06 28 743 update py INFO Completed update of XBee3 Cellular device with IMEI 352753090861053 2019 06 27 16 06 28 744 update py INFO Updates complete This script should automatically exit in a m...

Page 37: ... and contact Digi Technical Support 6 Download the relevant stage 2 update file from Digi s FTP server using HTTP For example http ftp1 digi com support ublox 2stg upd for IP stg2 pkg 5 6A2 00_to_5 6A2 01 pkg The file name is stg2 pkg 5 6A2 00_to_ 5 6A2 01 pkg 7 Transmit the update package file contents into the XBee3 Cellular modem using Firmware Update API frames For a description of this proces...

Page 38: ...py h type auto es2 ip ftp_server FTP_SERVER ftp_port FTP_PORT ftp_user FTP_USER ftp_password FTP_PASSWORD ftp_basedir FTP_BASEDIR IMEI IMEI Perform Over The Air Firmware update FOTA on XBee Cellular LTE M NB IoT positional arguments IMEI IMEI of device on which to perform update optional arguments h help show this help message and exit type auto es2 ip Type of modules default auto ftp_server FTP_S...

Page 39: ...uration 2019 06 27 16 06 28 743 update py INFO Completed update of XBee3 Cellular device with IMEI 352753090861053 2019 06 27 16 06 28 744 update py INFO Updates complete This script should automatically exit in a moment If it does not exit use Ctrl C to stop the script 9 If the update was not successful response to the last frame indicates internal error or other error try the update again with t...

Page 40: ...velopment Kit XBee bootloader Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 40 You can update firmware on the XBee Smart Modem serially This is done by invoking the bootloader and transferring the firmware image using XMODEM ...

Page 41: ...ython Note Some carriers restrict your internet access If access is restricted running some of these examples may not be possible Check with your carrier provider to determine whether internet access is restricted Connect to the Echo server 42 Connect to the ELIZA server 44 Connect to the Daytime server 46 Perform a GET HTTP request 48 Get started with CoAP 50 Connect to a TCP IP address 54 Get st...

Page 42: ...ses If this IP is not whitelisted by your carrier you will not be able to run this example DE Destination Port 0x2329 TCP The target port number of the TCP echo server This port in decimal is 9001 0x2711 UDP The target port number of the UDP echo server This port in decimal is 10001 To communicate with the Echo server 1 Ensure that the device is set up correctly with the SIM card installed and the...

Page 43: ...on the toolbar to open a serial console to the device For instructions on using the Console see the AT console topic in the XCTU User Guide 10 Click the Open button to open a serial connection to the device 11 Click in the left pane of the Console log then type in the Console to talk to the echo server The following screenshot provides an example of this chat ...

Page 44: ...apist 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 3 Click the Configuration working mode button 4 Select a device from the Radio Modules list XCTU displays the current firmware settings for that device 5 To switch to TCP communication in the IP field select 1 and click the ...

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

Page 46: ... entered unless the maximum number of characters has been reached Set to zero to disable text delimiter checking 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 3 Click the Configuration working mode button 4 Select a device from the Radio Mod...

Page 47: ...he Daytime server Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 47 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 ...

Page 48: ...equest port number in the DE field type 50 and click the Write button Hexadecimal 50 is 80 in decimal 7 To switch to TCP communication in the IP field select 1 and click the Write button 8 To move into Transparent mode in the AP field select 0 and click the Write button 9 Wait for the AI Association Indication value to change to 0 Connected to the Internet 10 Click the Consoles working mode button...

Page 49: ...onnection examples Perform a GET HTTP request Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 49 17 Click Send selected packet 18 A GET HTTP response from httpbin org appears in the Console log ...

Page 50: ...gration with the Web while meeting specialized requirements such as multicast support very low overhead and simplicity for constrained environments source CoAP terms When describing CoAP we use the following terms Term Meaning Method COAP s method action is similar to the HTTP method This guide discusses the GET POST PUT and DELETE methods With these methods the XBee Smart Modem can transport data...

Page 51: ... the device is set up correctly with the SIM card installed and the antennas connected as described in Connect the hardware 2 Open XCTU and click the Configuration working mode button 3 Add the XBee Smart Modem to XCTU see Add a device 4 Select a device from the Radio Modules list XCTU displays the current firmware settings for that device 5 To switch to UDP communication in the IP field select 0 ...

Page 52: ...ion 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 Mode...

Page 53: ...rrent baud rate XCTU provides the current baud rate in the BD Baud Rate field In this example you would type 9600 8 Press Y if you want an auto generated example Press Enter to build your own CoAP request 9 If you press Y it generates a message with n Method POST n URI example n payload hello world n token test The send and receive message must match the same token and message id Otherwise the cli...

Page 54: ... Destination Port Target port number The target port number that 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 antennas connected as described in Connect the hardware 2 Open XCTU and Add a device 3 Click the Configuration working mode button 4 Select a d...

Page 55: ...ttps 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 p...

Page 56: ...e 14 I 0x49 byte 15 G 0x47 byte 16 I 0x49 The following table describes the fields in the packet Field name Description Protocol Name The connect packet starts with the protocol name which is MQTT The length of the protocol name in bytes is immediately before the name itself Protocol Level Refers to the version of MQTT in use in this case a value of 4 indicates MQTT version 3 1 1 Connect Flags Ind...

Page 57: ... 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 4 Select a device from the Radio Modules list XCTU displays the current firmware settings for that device 5 In the AP field set Transparent Mode to 0 if it is not already and click the Write button 6 In the DL field type th...

Page 58: ...ets list 16 Click Send selected packet 17 A CONNACK packet response from the broker appears in the Console log This is a connection acknowledgment a successful response should look like this You can verify the response from the broker as a CONNACK by comparing it to the structure of a CONNACK packet in the MQTT documentation which is available at http docs oasis open org mqtt mqtt v3 1 1 os mqtt v...

Page 59: ...ublishes 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 wou...

Page 60: ...his 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 t...

Page 61: ... 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 fr...

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

Page 63: ...ceptions 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 ...

Page 64: ...nal components Note For in depth information and more complex code examples refer to the Digi MicroPython Programming Guide About MicroPython 65 MicroPython on the XBee Smart Modem 65 Use XCTU to enter the MicroPython environment 65 Use the MicroPython Terminal in XCTU 66 Example hello world 66 Example turn on an LED 66 Example debug the secondary UART 67 Exit MicroPython mode 68 Other terminal pr...

Page 65: ... a USB cable Note MicroPython does not work with SPI The examples in this guide assume n You have XCTU on your computer See Configure and update your XBee n You have a terminal program installed on your computer We recommend using the Use the MicroPython Terminal in XCTU This requires XCTU 6 3 7 or higher n You have an XBee Smart Modem installed in an appropriate development board such as an XBIB ...

Page 66: ...he 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 te...

Page 67: ...ssential indentations import machine from machine import Pin led Pin D4 Pin OUT value 0 Makes a pin object set to output 0 One might expect 0 to mean OFF and 1 to mean ON and this is normally the case But the LED we are turning on and off is setup as what is known as active low This means setting the pin to 0 allows current to flow through the LED and then through the pin to ground 3 To turn it of...

Page 68: ...TU 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 Other terminal programs If you do not use the MicroPython Terminal in XCTU you can use other term...

Page 69: ...ust change this rate as it was previously set to 115200 b s 5 Click Setup and Serial Port The Tera Term Serial port setup window appears 6 In the Tera Term Serial port setup window set the parameters to the following values n Port Shows the port that the XBee Smart Modem is connected on n Baud rate 115200 n Data 8 bit n Parity none n Stop 1 bit n Flow control hardware n Transmit delay N A 7 Click ...

Page 70: ...ached 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...

Page 71: ...Get started with MicroPython Use picocom in Linux Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 71 Now you can type MicroPython commands at the prompt ...

Page 72: ...tooth 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 ...

Page 73: ...ppens 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 t...

Page 74: ...f the device and the BLE signal strength No identifying information for the device displays After you have authenticated the device the device information is cached on the phone The next time the app on this phone connects to the XBee device the IMEI for the device displays in the app device list Note The IMEI is derived from the SH and SL values 4 Tap the XBee device name in the list A password d...

Page 75: ...ce UUID 53da53b9 0447 425a b9ea 9837505eb59a API Request Characteristic UUID 7dddca00 3e05 4651 9254 44074792c590 API Response Characteristic UUID f9279ee9 2cd0 410c 81cc adf11e4e5aea API Request characteristic UUID 7dddca00 3e05 4651 9254 44074792c590 Permissions Writeable XBee API frames are broken into chunks and transmitted sequentially to the request characteristic using write operations Vali...

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

Page 77: ...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 by scheduling tasks o Alway...

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

Page 79: ... in Remote Manager for each device See Enable SM UDP Configure Remote Manager features by scheduling tasks Remote Manager provides tools to perform common management and maintenance tasks on your XBee device A Remote Manager task is a sequence of commands that can be performed on one or more XBee Cellular devices Tasks can then be assigned to a schedule When a scheduled task is run it becomes an a...

Page 80: ...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 Settings 6 Add the following tasks a Click SM UDP SM UDP Request Connect A task is added to the dialog b Add other tasks as needed For examples refer to the Examples section c Click Device Disconnect A t...

Page 81: ...following rci_request query_setting rci_request c Click Device Disconnect A task is added to the dialog 6 Click Schedule in the lower right corner of the dialog to schedule the tasks to run The schedule screen displays Note You can also click Save as to save this schedule for future use 7 Select the device s on which you want to run this schedule You can add more than one device 8 Click Run Now 9 ...

Page 82: ...ange the RCI command to the following rci_request set_setting remote_manager DF 360 DF remote_manager set_setting rci_request c Click Device Disconnect A task is added to the dialog 6 Click Schedule in the lower right corner of the dialog to schedule the tasks to run The schedule screen displays Note You can also click Save as to save this schedule for future use 7 Select the device s on which you...

Page 83: ...schedule a task wizard may display Click the x in the upper left corner to close the wizard See Schedule walk through feature in the Digi Remote Manager User Guide for more information 6 In the Description field enter a name for the schedule such as Update XBee Firmware 7 Add the following tasks a Click SM UDP SM UDP Request Connect A task is added to the dialog b Click Device Gateway Firmware Upd...

Page 84: ... such as MicroPython c Click Create The new file is added to the list of files d Find the MicroPython folder in the folder list e Click Upload Files The Upload Files dialog displays f Browse for the main py file Check with your system administrator for the location of the application file g Click OK 4 Upload the MicroPython library uftp py file a Find the MicroPython folder in the folder list b Cl...

Page 85: ...ue Disable Python Auto start and enable TCP connection for remainder of commands rci_request set_setting micropython PS 0 PS micropython remote_manager MO 7 MO remote_manager set_setting rci_request send_message sci command command Reboot to stop MicroPython name Reboot name event on_error continue on_error event sci reboot allowOffline true waitForReconnect true sci command Update MicroPython app...

Page 86: ...sh lib uftp py file MicroPython uftp py file put_file commands file_system sci command command name RCI Command name event on_error continue on_error event sci send_message cache false allowOffline true Enable Python Auto start rci_request set_setting micropython PS 1 PS micropython remote_manager MO 6 MO remote_manager set_setting rci_request send_message sci command Reboot to start the program c...

Page 87: ...les drop down list button 5 Click Scheduled Operation Create immediate running schedule 6 Update the XML to refer to the updatemicropython xml file you created previously Runs immediately Schedule on IMMEDIATE targets device id 00010000 00000000 03588320 70372440 targets task path my_tasks updatemicropython xml Schedule 7 Click Send to schedule the task 8 Click Device Management Operations to view...

Page 88: ...rough feature in the Digi Remote Manager User Guide for more information 5 In the Description field enter a name for the schedule such as Restore Persistent 6 Add the following tasks a Click SM UDP SM UPD Request Connect A task is added to the dialog b Click Device RCI Command A task is added to the dialog Change the RCI command to the following rci_request set_setting remote_manager MO 7 MO remot...

Page 89: ...ote Manager 3 Click Device Management Devices 4 Select the device that you want to configure 5 Click Properties in the toolbar As an alternative click Properties Edit Device Configuration The configuration Home page appears 6 Click Status in the toolbar to display the status sub menus 7 Click on the status group that has information you want to display The status information is related to AT comma...

Page 90: ...2 Set up a persistent connection to connect the device to Remote Manager using one of the following methods n Remote Manager A persistent connection can be set up in Remote Manager This option should be used when you have many deployed devices and no local access See Restore persistent connection to a remote XBee n XCTU This option allows immediate access and should be used when you have local acc...

Page 91: ...Digi XBee3 Cellular LTE M NB IoT Gating Firmware to download the zip file d Unzip the file The file contains either a ebin or a gbl file 2 Unzip the file and locate the ebin file inside the unzipped directory 3 Send an HTTP SCI request to Remote Manager with the contents of the downloaded ebin or gbl file converted to base64 data see the following examples Examples for ebin n Example update the XB...

Page 92: ...ut using the device firmware image already uploaded to Remote Manager upload the device s ebin firmware to Remote Manager 1 Download the updated firmware file for your device from Digi s support site This is a zip file containing ebin and mxi files for import 2 Unzip the file and locate the ebin inside the unzipped directory 3 Log in to Remote Manager 4 Click the Data Services tab 5 Click Data Fil...

Page 93: ...ation of firmware image firmware_path XBXC gbl Remote Manager device ID of the device being updated device_id 00010000 00000000 03526130 70153378 Remote Manager username and password username my_Remote_manager_username password my_remote_manager_password url https remotemanager digi com ws sci Get firmware image fw_file open firmware_path rb fw_data fw_file read fw_data base64 encodebytes fw_data ...

Page 94: ...quest to Remote manager with the path of the gbl file see the example below import base64 import requests Location of firmware image on Remote Manager firmware_path XBXC gbl Remote Manager device ID of the device being updated device_id 00010000 00000000 03526130 70153378 Remote Manager username and password username my_remote_manager_username password my_remote_manager_password url https remotema...

Page 95: ...nect the device to Remote Manager using one of the following methods n Remote Manager A persistent connection can be set up in Remote Manager This option should be used when you have many deployed devices and no local access See Restore persistent connection to a remote XBee n XCTU This option allows immediate access and should be used when you have local access such as when using a development ki...

Page 96: ... Manager See Disconnect a device in the Digi Remote Manager User Guide n Using web services in Remote Manager See Request connect SM UDP support in the Digi Remote Manager Programming Guide Configure XBee settings within Remote Manager You can configure the device settings to use features with Remote Manager For more information see Example Read settings and state using Remote Manager Configure de...

Page 97: ...ty 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 t...

Page 98: ... select a long code Note The options in the Server Number for SIM 1 list box are determined within Remote Manager and are used to ensure an SMS connection between the device and Remote Manager The option selected from the list box must match the Remote Manager phone number and service ID set for the device The XBee examines received SMS messages and if the phone number matches and content contains...

Page 99: ...Cellular RF characteristics 100 Bluetooth RF characteristics 100 Cellular networking specifications 100 Power requirements 101 Power consumption 102 Electrical specifications 103 Regulatory approvals 104 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 99 ...

Page 100: ...nge 0 2 5 V Cellular chipset u blox SARA R410M 028 Form factor Digi XBee 20 pin through hole SIM size 4FF Nano Cellular RF characteristics The following table provides the RF characteristics for the device Specification Value Transmit power Up to 23 dBm Power Class 3 Receive sensitivity 105 dBm Bluetooth RF characteristics The following table provides the Bluetooth RF characteristics for the devic...

Page 101: ... LTE FDD bands n Band 12 700 Mhz n Band 28 700 MHz n Band 13 700 MHz n Band 20 800 MHz n Band 26 850 MHz n Band 18 850 MHz n Band 5 850 MHz n Band 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 n Band 1 2100 MHz LTE TDD bands n Band 39 1900 MHz Security Digi Trustfence Downlink uplink speeds Up to 375 kb s Duplex mode Half duplex Power requirem...

Page 102: ...ace 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 dBm 205 mA 220 mA Active mode current Idle connected listening 20 mA 35 mA Power save mode current 20 µA Not supported Deep sleep current 10 µA 10 µA USB direct mode must be disabled during sleep ...

Page 103: ...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 output low Sinking 3 mA VCC 3 3 V 0 2 VDD_ IO V VOH Voltage output high Sourcing 3 mA VCC 3 3 V 0 8 VDD_IO V I_IN Input leakage current High Z state I O connected to Ground or VDD_IO 0 1 30 nA RPU Interna...

Page 104: ...y and carrier approvals for the device Specification 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 AT T end device certified Complete Verizon end device certified Complete PTCRB Complete Bluetooth Declaration ID D042514 QDID 121268 ...

Page 105: ...Hardware Mechanical drawings 106 Pin signals 106 RSSI PWM 108 SIM card 108 Associate LED functionality 108 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 105 ...

Page 106: ...gs Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 106 Mechanical drawings The following figures show the mechanical drawings for the XBee Smart Modem All dimensions are in inches Pin signals The pin locations are ...

Page 107: ...er Output Output Clear to Send Flow Control or Digital I O 7 13 ON SLEEP DIO9 Output Output Module Status Indicator or Digital I O 9 14 VREF Feature not supported on this device Used on other XBee devices for analog voltage reference 15 Associate DIO5 Either Output Associated Indicator Digital I O 5 16 RTS DIO6 Either Disabled Input Request to Send Flow Control Digital I O 6 17 AD3 DIO3 SPI_ SS Ei...

Page 108: ... is connected to the RSSI LEDs which may be interpreted as follows PWM duty cycle Number of LEDs turned on Received signal strength dBm 79 39 or more 3 83 dBm or higher 62 42 to 79 39 2 93 to 83 dBm 45 45 to 62 42 1 103 to 93 dBm Less than 45 45 0 Less than 103 dBm or no cellular network connection SIM card The XBee Smart Modem uses a 4FF Nano size SIM card CAUTION Never insert or remove SIM card ...

Page 109: ...lity Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 109 Where the low signal means LED off and the high signal means LED on When CI is not 0 or 0xFF the Associate LED has a different blink pattern that looks like this ...

Page 110: ...Antenna recommendations Antenna placement 111 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 110 ...

Page 111: ... parasitic coupling and detuning preventing the antenna from radiating efficiently 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 beams in structures n Concrete reinforced with metal rods n Metal enclosures n Vehicles n Elevators n Ventilation ducts n ...

Page 112: ... updates 113 Power supply considerations 113 Minimum connection diagram 113 Heat considerations and testing 114 Custom configuration Create a new factory default 114 Clean shutdown 115 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 112 ...

Page 113: ...sing 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 See Brownout issue for details on how to avoid this issue When considering a power supply use the following design practices 1 Power supply ripple should be less than 75 mV peak to peak 2 The power s...

Page 114: ...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 implementing heat mitigating measures for example reduce transmission frequency and duration enter sleep mode more frequently or improve airflow Addressing heat issues will help to ensure long term d...

Page 115: ...e AT 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 on your XBee cellular devices before removing power from the devices Performing a shutdown allows the module to unregister from the cellular network and safely store operating parameters Failure ...

Page 116: ...on xbee sleep_now When the module has gone to sleep and the SLEEP pin pin 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 use Airplane mode AM 1 This puts the XBee into a safe state for shutdown 1 Set AM 1 2 Apply configuration change 3 Wait 30 seco...

Page 117: ...Cellular connection process Connecting 118 Data communication with remote servers TCP UDP 118 Disconnecting 119 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 117 ...

Page 118: ... device receives its IP configuration and address 4 The AI Association Indication command now returns a 0 and the sockets become available Data communication with remote servers TCP UDP Once the data network connection is established communication with remote servers can be initiated in several ways Note For NB IoT TCP support is dependent on the network Contact your network provider for details n...

Page 119: ...he XBee Smart Modem is put into Airplane mode or deep sleep is requested 1 Sockets are closed cleanly if possible 2 The cellular connection is shut down 3 The cellular component is powered off Note We recommend entering Airplane mode before resetting or rebooting the device to allow the cellular module to detach from the network ...

Page 120: ...g mode 121 Transparent operating mode 122 API operating mode 122 Command mode 122 MicroPython mode 124 USB direct mode 125 Bypass operating mode DEPRECATED 125 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 120 ...

Page 121: ...hrough 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 mode and Bypass operating mode The default mode is Transparent operating mode Use the AP API Enable command to select a different operating mode The following flowchart illustrates how the modes relate ...

Page 122: ...an 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 two characters that identify the command and then by some optional configuration values The operating modes of the XBee Smart Modem are controlled by the AP API Enable setting but Command mode is alway...

Page 123: ...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 commands Once the device enters Command mode use the syntax in the following figure to send AT commands Every AT command starts with the letters AT which stands for attention The AT is followed by two ...

Page 124: ...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 valid AT commands within the time specified by CT Command Mode Timeout it returns to Transparent or API mode The default Command mode timeout is 10 seconds For an example of programming the device using ...

Page 125: ... direct mode in two ways 1 Enable via software Set DO Device Options bit 2 Ensure that P0 DIO10 PWM0 Configuration is not set to 6 as that would override the DO setting 2 Enable based on the state of VBUS pin 6 Set P0 to 6 Apply a logic high signal to DIO10 PWM0 pin 6 to enable USB or a logic low signal to disable USB Note Although pin 6 is 5 V tolerant on this device it operates with the same 3 3...

Page 126: ...ular component in a way that makes it incompatible with the firmware Bypass operating mode exists for users who wish to communicate directly with the cellular component settings and do not intend to use XBee Smart Modem software features such as API mode Command mode is available while in Bypass mode see Enter Command mode for instructions Enter Bypass operating mode To configure a device for Bypa...

Page 127: ...de 128 Pin sleep mode 128 Cyclic sleep mode 128 Cyclic sleep with pin wake up mode 128 SPI mode and sleep pin functionality 128 The sleep timer 129 MicroPython sleep behavior 129 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 127 ...

Page 128: ... the D7 command to enable hardware flow control the CTS pin asserts low when the device wakes and can receive serial data and de asserts high when the device sleeps Cyclic sleep with pin wake up mode Set SM to 5 to enter Cyclic sleep with pin wake up mode This mode is a slight variation on Cyclic sleep mode SM 4 that allows you to wake a device prematurely by de asserting the SLEEP_RQ pin SLEEP_RQ...

Page 129: ...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 resets on re configuration When the sleep timer expires the device returns to sleep MicroPython sleep behavior When the XBee Smart Modem enters Deep Sleep mode any MicroPython code currently executin...

Page 130: ...Power saving features Airplane mode 131 Power Saving Mode PSM 131 PSM behavior 131 Deep Sleep mode 131 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 130 ...

Page 131: ... taking advantage of XBee sleep features such as Pin Sleep or Cyclic Sleep rather than powering the cellular component 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 also triggered to wake up when the user performs any activity requiring network connec...

Page 132: ...eep Sleep mode Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 132 Note When the XBee Smart Modem enters deep sleep mode any MicroPython code currently executing is suspended until the device comes out of sleep ...

Page 133: ... Serial interface 134 Serial data 134 UART data flow 134 Serial buffers 135 CTS flow control 135 RTS flow control 135 Enable UART or SPI ports 135 I2C 136 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 133 ...

Page 134: ... significant bit first and a stop bit high The following diagram illustrates the serial bit pattern of data passing through the device The diagram shows UART data packet 0x1F decimal number 31 as transmitted through the device You can configure the UART baud rate parity and stop bits settings on the device with the BD NB and SB commands respectively For more information see Serial interfacing comm...

Page 135: ...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 DOUT pin as long as RTS is de asserted set high Do not de assert RTS for long periods of time or the serial transmit buffer will fill Enable UART or SPI ports To enable the UART port configure DIN and DO...

Page 136: ...dem User Guide 136 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 wire serial protocol section in the MicroPython Programming Guide for details ...

Page 137: ...ation SPI communications 138 Full duplex operation 139 Low power operation 140 Select the SPI port 140 Force UART operation 141 Data format 141 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 137 ...

Page 138: ...ommunication with the slave SPI_ATTN Attention Alerts the master that slave has data queued to send The XBee Smart Modem asserts this pin as soon as data is 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 bit MSB first bit 7 is the first bit of a ...

Page 139: ... from the master When the master is sending data to the slave and the slave has valid data to send in the middle of receiving data from the master it allows a true full duplex operation where data is valid in both directions for a period of time During 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 causi...

Page 140: ...e to sleep in SM1 mode Select the SPI port To force SPI mode hold DOUT DIO13 pin 2 low while resetting the device until SPI_ATTN asserts This causes the device to disable the UART and go straight into SPI communication mode Once configuration 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 p...

Page 141: ...enabled and no SPI master is available to access the SPI slave port you can recover the device to UART operation by holding DIN CONFIG low at reset 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 it for UART operation If you write those parameters ...

Page 142: ...ion about using MicroPython on the XBee Smart Modem refer to the Digi MicroPython Programming Guide Overview of the file system 143 XCTU interface 144 Encrypt files 144 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 142 ...

Page 143: ...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 refers to the parent directory so an operation on filename txt that takes place in the directory flash test accesses the file flash filename txt n The directory refers to the current directory so the ...

Page 144: ...cation 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 identical to the PUT operation Files placed in this way are indicated with a pound sign following the filename The XBee Smart Modem does not allow an encrypted file to be read by normal use so it 1 Cann...

Page 145: ...e incoming TCP sockets in API mode 147 API mode behavior for outgoing TCP and SSL connections 147 API mode behavior for outgoing UDP data 148 API mode behavior for incoming TCP connections 148 API mode behavior for incoming UDP data 149 Transparent mode behavior for outgoing TCP and SSL connections 149 Transparent mode behavior for outgoing UDP data 150 Transparent mode behavior for incoming TCP c...

Page 146: ...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 transmit TCP TLS data to a remote destination using the 0x20 or 0x23 API frames sending a large amount of data as a single API frame is preferable to multiple smaller API frames Using a single large ...

Page 147: ...try 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 sockets in API mode In API mode you can enable incoming connections to the XBee Smart Modem Note For NB IoT TCP support is dependent on the network Contact your network provider for details 1 To ena...

Page 148: ... 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 the C0 setting in the Transmit TX request frame use a source port that matches the value configured for the C0 setting The device sends a Transmit TX Status 0x89 frame in reply to the Transmit TX Req...

Page 149: ... 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 from the Receive RX frame In other words take the source address source port and destination port fields from the Receive RX frame and use those respectively as the destination address destination po...

Page 150: ...nd protocol used for incoming connections TCP and incoming data UDP in Transparent mode SSL is not currently supported for incoming connections Note For NB IoT TCP support is dependent on the network Contact your network provider for details When the IP setting is TCP and there is no existing connection to or from the XBee Smart Modem the device accepts one incoming connection Any data received on...

Page 151: ...the network Contact your network provider for details TLS AT commands 152 Transparent mode and TLS 153 API mode and TLS 153 Key formats 153 Certificate formats 153 Certificate limitations 153 Cipher suites 154 Server Name Indication SNI 154 Secure the connection between an XBee and Remote Manager with server authentication 154 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 151 ...

Page 152: ...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 authentication failure n client_key optional Filename of a file in the certs directory Indicates the private key matching the public key contained in client_cert This should be a secure file uploaded with ATFS XPUT filename ...

Page 153: ...guration specified by 0 SSL 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 the network Contact your network provider for details Key formats The RSA PKCS 1 format is the only common format across XBee Cellular device variants You can identify a PKCS 1 key file by the pr...

Page 154: ...es 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 is dependent on the network Contact your network provider for details The only documented shared suites between the XBee3 Cellular LTE Cat 1 Smart Modem and the XBee3 Cellular LTE M Global Smart Modem...

Page 155: ... the correct location 1 Verify the following settings Setting Value DO Bit 0 mask 0x1 must 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 contain the value flash cert digi remote mgr pem This is the file system location where the firmware will lo...

Page 156: ...6 3 When the device is connected to Remote Manager the DI command can take on any of the three values shown below based on the security level of the connection Verify the that the DI command is set to 6 to verify that the server was correctly authenticated n 0 Connected without TLS n 5 Connected with TLS but without authentication n 6 Connected with TLS and with authentication ...

Page 157: ... 175 I O sampling commands 183 Sleep commands 185 Command mode options 187 MicroPython commands 189 Firmware version information commands 191 Diagnostic interface commands 193 Execution commands 196 File system commands 197 BLE commands 200 Remote Manager commands 202 System commands 205 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 157 ...

Page 158: ...e the CN Exit AT Command Mode or AC commands Parameter range N A Default N A FR Force Reset Resets the device The device responds immediately with an OK and performs a reset 100 ms later If you issue FR while the device is in Command Mode the reset effectively exits Command mode Note We recommend entering Airplane mode before resetting or rebooting the device to allow the cellular module to detach...

Page 159: ...nds Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 159 Note Once you issue a WR command do not send any additional characters to the device until after you receive the OK response Parameter range N A Default N A ...

Page 160: ... 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 Identity IMEI Parameter range N A Default Set in the factory MN Operator Reads the network operator on which the device is registered Parameter range N A Default N A MV Modem Firmware Version Read the firmware versio...

Page 161: ...nges or CN Exit Command mode triggers a network reset See Network connection issues if the XBee Smart Modem is not joining the network Parameter range 1 100 ASCII characters Default CP Carrier Profile Configures the cellular component to select network operator settings RF bands packet data configuration for various networks The default setting of 0 autodetect increases the boot time The 1 No Prof...

Page 162: ...ending on the limitations of the cellular component WARNING If this value is configured incorrectly the XBee module may be unable to locate a tower and join the network Parameter range 0 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF 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 ...

Page 163: ...0x080080 bits 7 and 19 enable NB IoT Bands 8 and 20 Bit LTE Band 0 1 127 128 Default 0xFFFFFFFFFFFFFFFF bands 1 64 enabled AM Airplane Mode When set the cellular component of the XBee Smart Modem is fully turned off and no access to the cellular network is performed or possible Parameter range 0 1 0 Normal operation 1 Airplane mode Default 0 N Preferred Network Technology Note This command applies...

Page 164: ...mands Cellular commands Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 164 Parameter Description 0 LTE M with NB IoT fallback 1 NB IoT with LTE M fallback 2 LTE M only 3 NB IoT only Default 0 ...

Page 165: ...rity layer profile manager USECPRF heading Parameter range 0 4 Value Description 0x00 UDP 0x01 TCP 0x02 SMS Transparent mode 0x03 Reserved 0x04 SSL over TCP Default 0x01 TL SSL TLS Protocol Version Sets the SSL TLS protocol version used for the SSL socket If you change the TL value it does not affect any currently open sockets The value only applies to subsequently opened sockets Note Due to known...

Page 166: ...S Profile 1 Specifies the SSL 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 on the network Contact your network provider for details Format server_cert client_cert client_key Parameter range From 1 through 127 ASCII characters Default N A 2 SSL TLS Profile 2 Specifies the SSL TLS certificate s to use in Tr...

Page 167: ...ction timeout If no activity for this timeout then the connection is closed When set to 0 the connection is closed immediately after data is sent Note For NB IoT TCP support is dependent on the network Contact your network provider for details Parameter Range 10 0xFFFF x 100 ms Default 0xBB8 5 minutes DO Device Options Enables and disables special features on the XBee Smart Modem Note For NB IoT T...

Page 168: ... device retains with Remote Manager causes the cellular component to spend very little time in low power negating the value of selecting that feature Default 0x01 Bit 0 enabled DT Cellular Network Time Reads the current network provided local time of the XBee device If the time is not known the response is empty This value is synchronized with the network approximately once per hour Parameter rang...

Page 169: ...ecause the IP address is 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 represented as a dotted quad string notation Parameter range 0 15 IPv4 characters Default 0 0 0 0 P Destination Phone Number Sets or displays the destination phone number used for ...

Page 170: ...he destination address to an IP address the value must be a dotted quad for example XXX XXX XXX XXX To set the destination address to a domain name the value must be a legal Internet host name for example remotemanager digi com Parameter range 0 128 ASCII characters Default 0 0 0 0 OD Operating Destination Address Read the destination IPv4 address currently in use by Transparent mode The value is ...

Page 171: ...mitted on the XBee Smart Modem s serial port As long as a network connection is established to this port for TCP data received on the serial port is transmitted on the established network connection IP IP Protocol sets the protocol used when UART is in Transparent or API mode For more information on using incoming connections see Socket behavior Parameter range 0 0xFFFF Value Description 0 Disable...

Page 172: ...ts Command mode or you issue AC Apply Changes The baud rate resets to default unless you save it with WR Write or by clicking the Write module settings button in XCTU Parameter range Standard baud rates 0x1 0x8 Non standard baud rates 0x5B9 to 0x3D090 250 000 b s 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 2...

Page 173: ...0 bytes maximum packet size are received in the DI buffer Set RO to 0 to transmit characters as they arrive instead of buffering them into one RF packet Parameter range 0 0xFF x character times Default 3 TD Text Delimiter The ASCII character used as a text delimiter for Transparent mode When you select a character information received over the serial port in Transparent mode is not transmitted unt...

Page 174: ...ing The device can format the RF packets it receives into API frames and send them out the UART When API is enabled 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 Transparent mode 0x01 API enabled 0x02 API enabled with escaped control characters 0x03 N A 0...

Page 175: ...the DIO0 AD0 configuration pin 20 Parameter range 0 2 5 Parameter Description 0 Disabled 1 N A 2 Analog input 3 Digital input 4 Digital output default low 5 Digital output default high Default 0 D1 DIO1 AD1 Sets or displays the DIO1 AD1 configuration pin 19 Parameter range 0 6 Parameter Description 0 Disabled 1 SPI_ATTN 2 ADC 3 Digital input 4 Digital output low 5 Digital output high 6 I2C SCL Def...

Page 176: ...ription 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 AD3 Sets or displays the DIO3 AD3 configuration pin 17 Parameter range 0 5 Parameter Description 0 Disabled 1 SPI_SSEL 2 Analog input 3 Digital input 4 Digital output default low 5 Digital output default high Default 0 D4 DIO4 Parameter range Default 0 ...

Page 177: ...tion 0 Disabled 1 Associated LED 2 N A 3 Digital input 4 Digital output default low 5 Digital output default high Default 1 D6 DIO6 RTS Sets or displays the DIO6 RTS configuration pin 16 Parameter range 0 1 3 5 Parameter Description 0 Disabled 1 RTS flow control 2 N A 3 Digital input 4 Digital output default low 5 Digital output default high Default 0 D7 DIO7 CTS Sets or displays the DIO7 CTS conf...

Page 178: ...ult high Default 0x1 D8 DIO8 SLEEP_REQUEST Sets or displays the DIO8 DTR SLP_RQ configuration pin 9 Parameter range 0 1 3 5 Parameter Description 0 Disabled 1 SLEEP_REQUEST input 3 Digital input 4 Digital output default low 5 Digital output default high Default 1 D9 DIO9 ON_SLEEP Sets or displays the DIO9 ON_SLEEP configuration pin 13 Parameter range 0 1 3 5 Parameter Description 0 Disabled 1 ON S...

Page 179: ... PWM so that the output can be translated back into analog form Parameter range 0 6 Parameter Description 0 Disabled 1 RSSI PWM0 output 2 PWM0 output 3 Digital input 4 Digital output low 5 Digital output high 6 USB VBUS Default 0 P1 DIO11 PWM1 Configuration Sets or displays the DIO11 configuration pin 7 Parameter range 0 1 3 7 Parameter Description 0 Disabled 1 Fan enable Output is low when the XB...

Page 180: ...SDA 7 USB direct Default 0 P2 DIO12 Configuration Sets or displays the DIO12 configuration pin 4 Parameter range 0 1 3 5 Parameter Description 0 Disabled 1 SPI_MISO 2 N A 3 Digital input 4 Digital output default low 5 Digital output default high Default 0 P3 DIO13 DOUT Sets or displays the DIO13 DOUT configuration pin 17 Parameter range 0 1 Parameter Description 0 Disabled 1 UART DOUT enabled Defa...

Page 181: ... Pull up down Resistor Enable for bit mappings which are the same Parameter range 0x0 0x7FFF Default 0 0x7FFF PR Pull up down Resistor Enable Sets or displays the bit field that configures the internal resistor status for the digital input lines Internal pull up down resistors are not available for digital output pins analog input pins or for disabled pins Use the PD command to specify whether the...

Page 182: ...in 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 6 for P0 2 where a value of 0x200 is a 50 duty cycle Before setting the line as an output 1 Enable PWM0 output P0 DIO10 PWM0 Configuration 2 2 Apply the settings use CN Exit Command mode or AC Apply Changes The PWM period is 42 62 µs and there are 0x03FF...

Page 183: ...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 set to 1 are configured for digital I O and are included in the digital data value below Pins D0 D9 are bits 0 9 and P0 P2 are bits 10 12 n Analog channel mask The bits set to 1 are configured for analo...

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

Page 185: ...c 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 if the SLEEP_RQ pin is inactive allowing the device to be kept awake or woken by the connected system Default 0 SP Sleep Period Sets or displays the time to spend asleep in cyclic sleep modes In Cycl...

Page 186: ...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 Timer for PSM Note This is related to 3GPP timer T3412 Note For NB IoT TCP support is dependent on the network Contact your network provider for details Parameter range 0 0x35683200 1 s Default 0x8ca0...

Page 187: ...rtently 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 valid commands within this time period it returns to Idle mode from Command mode Parameter range 2 0x1770 x 100 ms Default 0x64 10 seconds CN Exit Command mode Immediately exits Command Mode and appli...

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

Page 189: ...ing the Ctrl F command from the MicroPython REPL refer to the Digi MicroPython Programming Guide The PYC sub command reports details of the stored code In Command mode it returns three lines of text for example source 1662 bytes hash 0xC3B3A813 bytecode 619 bytes hash 0x0900DBCE compiled 2017 05 09T15 49 44 The messages are n source the size of the source code used to generate the bytecode and its...

Page 190: ... any stored code and then does a soft reboot on the MicroPython subsystem PYV Version Report Report the MicroPython version PY Interrupt Program Sends KeyboardInterrupt to MicroPython This is useful if there is a runaway MicroPython program and you have filled the stdin buffer You can enter Command mode and send ATPY to interrupt the program Default N A ...

Page 191: ... HV Hardware Version Read the device s hardware version Use this command to distinguish between different hardware platforms The upper byte returns a value that is unique to each device type The lower byte indicates the hardware revision Parameter range 0 0xFFFF read only Default Set in firmware AI Association Indication Reads the Association status code to monitor association progress The followi...

Page 192: ...n PSM Note For NB IoT TCP support is dependent on the network Contact your network provider for details 0x2F Bypass mode active 0xFF Initializing Parameter range 0 0xFF read only Default N A HS Hardware Series Read the device s hardware series number Parameter range N A Default Set in the firmware CK Configuration CRC Displays the cyclic redundancy check CRC of the current AT command configuration...

Page 193: ... 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 Indication Displays information regarding the last IP connection when using Transparent mode AP 0 The following table provides the parameter s meaning when IP 0 for UDP connections Parameter Descripti...

Page 194: ...nnections Parameter Description 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 Cellular component not identified yet 0x12 DNS query lookup failure 0x13 Socket leak 0x20 Bad handle 0x21 User closed 0x22 No network registration 0x23 No internet connection 0x24 ...

Page 195: ...de the command returns line based records mapping key value pairs The record for the serving cell begins with the capital letter S and keys for the fields are MCC MNC Area CID and Signal Each line describes a particular cell and only those values determined during a single scan are reported Example atas S MCC 311 MNC 480 Area 48707 CID 48825632 Signal 88 CID 48825612 Signal 95 CID 48825603 Signal ...

Page 196: ...s The XBee Smart Modem responds immediately with an OK on the UART and then causes a network restart If NR 0 the XBee Smart Modem tears down any TCP UDP sockets and resets Internet connectivity You can also send NR which acts like NR 0 Parameter range 0 Default N A R Modem Reset Forces the cellular component to reboot CAUTION This command is for advanced users and you should only use it if the cel...

Page 197: ...rrors 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 response is an error by checking if the first letter of the response is capital E ATFS File System When sent without any parameters FS prints a list of supported commands ATFS PWD Prints the current ...

Page 198: ...ile 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 Sending file with YMODEM When the prompt is sent you should initiate a YMODEM receive in your terminal emulator If the command is incorrect the reply will be an error as described in Error responses ATF...

Page 199: ... 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 responds with Formatting adds a period every second until the format is complete and ends the response with a carriage return ...

Page 200: ...uld only use this command if you have already configured a password on the XBee device and the salt corresponds to the password The SRP Secure Remote Password Salt is a 32 bit number used to create an encrypted password for the XBee device The S command is used in conjunction with the V W X and Y verifiers Together the command and the verifiers authenticate the client for the BLE API Service witho...

Page 201: ...e used in conjunction with the S command used to create an encrypted password for the XBee device Together with the S command these commands authenticate the client for the BLE API Service without storing the XBee password on the XBee device The salt is configured in the S command In the V W X and Y verifiers you specify the 128 byte verifier value where each command represents 32 bytes of the tot...

Page 202: ...m 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 after 3 missed keepalives This command works with the K2 command to limit data usage See Configure Remote Manager keepalive interval Note Changing this value causes any currently active Remote Manager conn...

Page 203: ... 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 connection uses TLS This is the default 2 Reserved for future use Default 6 Bits 1 and 2 are enabled by default D Remote Manager certificate Defines the SSL TLS Remote Manager certificate Parameter ra...

Page 204: ...en attempts to upload metrics The time is measured in minutes Metrics which cannot be collected or reported at any particular time are skipped until the next attempt Parameter range N A Value Description 0x3c One hour Default 0x3c 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 Paramet...

Page 205: ...efined 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 description for the XBee displayed in Remote Manager Range Up to 20 ASCII characters Default One ASCII space character 0x20 KC Contact Information Sets or displays user defined contact information for the XBee...

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

Page 207: ...lity 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 po...

Page 208: ...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 when working in API escaped mode the software must escape any payload bytes that match API frame specific data such as the start of frame byte 0x7E The following table shows the structure of an API f...

Page 209: ...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 length field has a two byte value that specifies the number of bytes in the frame data field It does not include the checksum field Length field The length field is a two byte value that specifies the numb...

Page 210: ...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 excluding the frame delimiter 7E and the length the second and third bytes 7E 00 0A 01 01 50 01 00 48 65 6C 6C 6F B8 Add these hex bytes 01 01 50 01 00 48 65 6C 6C 6F 247 Now take the result of 0x247 and keep...

Page 211: ...Pv4 0x20 215 Tx Request with TLS Profile 0x23 217 AT Command Response 0x88 219 Transmit TX Status 0x89 220 Modem Status 0x8A 222 Receive RX Packet SMS 0x9F 223 Receive RX Packet IPv4 0xB0 224 User Data Relay 0x2D 225 User Data Relay Output 0xAD 227 BLE Unlock API 0x2C 228 BLE Unlock Response 0xAC 232 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 211 ...

Page 212: ... 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 correlate with a subsequent ACK If set to 0 the device does not send a response AT command Byte Command name two ASCII characters that identify the AT command Parameter value Byte If present indicate...

Page 213: ...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 For details on frame structure see API frame format Field name Field value Data type Description Frame type 0x09 Byte Frame ID Byte Identifies the data frame for the host to correlate with a subsequent ...

Page 214: ...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 value Data type Description Frame type 0x1F Byte Frame ID Byte Reference identifier used to match status responses 0 disables the TX Status frame Options Byte Reserved for future use Phone number 20 byte...

Page 215: ...API frame format Field name Field value Data type Description Frame type 0x20 Byte Frame ID Byte Reference identifier used to match status responses 0 disables the TX Status frame Destination address 32 bit big endian Destination port 16 bit big endian Source port 16 bit big endian If the source port is 0 the device attempts to send the frame data using an existing open socket with a destination t...

Page 216: ...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 Client Connection Timeout Ignore this bit for UDP packets All other bits are reserved and should be 0 Payload Variable Data to be transferred to the destination may be up to 1500 bytes UDP is limited to 512 bytes ...

Page 217: ...ld 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 port 16 bit big endian Source port 16 bit big endian If the source port is 0 the device attempts to send the frame data using an existing open socket with a destination that matches the destination add...

Page 218: ...ield 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 Client Connection Timeout Ignore this bit for UDP packets All other bits are reserved and should be 0 Payload Variable Data to be transferred to the destination may be up to 1500 bytes ...

Page 219: ...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 subsequent ACK If set to 0 the device does not send a response AT command Byte Command name two ASCII characters that identify the AT command Status Byte 0 OK 1 ERROR 2 Invalid command 3 Invalid parameter P...

Page 220: ...transmit frame Status Byte Status code see the table below The following table shows the status codes Code Description 0x0 Successful transmit 0x21 Failure to transmit to cell network 0x22 Not registered to cell network 0x2c Invalid frame values check the phone number 0x31 Internal error 0x32 Resource error retry operation later See Socket limits in API mode for more information 0x74 Message too l...

Page 221: ...lular LTE M NB IoT Global Smart Modem User Guide 221 Code Description 0x80 Connection refused 0x81 Socket connection lost 0x82 No server 0x83 Socket closed 0x84 Unknown server 0x85 Unknown error 0x86 Invalid TLS configuration missing file and so forth ...

Page 222: ...ld value Data type Description Frame type 0x8A Byte Status Byte 0 Hardware reset or power up 1 Watchdog timer 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 configuration failed Note The BLE Connect and BLE Disconnect events are reported over the UART SPI...

Page 223: ...or 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 format Field name Field value Data type Description Frame Type 0x9F Byte Phone number 20 byte string String representation of the phone number padded out with null bytes 0x0 Payload Variable Body of th...

Page 224: ...ing 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 the example below is for a source address of 192 168 0 104 32 bit big endian 5 6 7 16 bit destination port MSB 8 The port that the packet was received on 16 bit big endian LSB 9 16 bit source port MSB...

Page 225: ...us frame for sucess Destination interface Byte 0 Serial port SPI or UART when in API mode 1 BLE 2 MicroPython Data Variable Checksum 1 Byte Error cases The Frame ID is used to report error conditions in a method consistent with existing transmit frames The error codes are mapped to statuses The following conditions result in an error that is reported in a TX Status frame referencing the frame ID f...

Page 226: ...ternal processor to output the 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 the Frame over the UART with the Micropython interface as a target Micropython operates over the data and publishes the data to mqtt topic ...

Page 227: ...ta to be output 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 following table provides the contents of the frame For details on frame structure see API frame format Field name Field value Data type Description Delimiter 7E Length Frame type 0xAD Byte Source...

Page 228: ...ed 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 When an unlocked connection is terminated a Modem Status Frame with the status code 0x33 Bluetooth Disconnected is sent through the UART The following implementations are known to work with the BLE SRP...

Page 229: ...with 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 structure varies by Frame ID value Descriptions are in the tables below The tables below give more information about the phase of authentication and interpretation of payload data Phase 1 Client presents...

Page 230: ... will allow additional API frames to be used Content from this point will be encrypted using AES 256 CTR with the following parameters n Key The entire 32 byte session key n Counter 128 bits total prefixed with the appropriate nonce shared 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...

Page 231: ...0x2C b Write the frame using one or more Write operations c When successful the response arrives in one or more indications If your stack does not do it for you remember to acknowledge each indication as it is received Note that you are 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 ...

Page 232: ... 232 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 This frame is used in conjunction with the Response 0xAC frame For details see BLE Unlock API 0x2C ...

Page 233: ...irmware updates About packaged firmware updates 234 FW Update 0x2B 235 FW Update Response 0xAB 235 Important notes 236 Perform a cellular component firmware update 236 Error recovery 237 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 233 ...

Page 234: ...dating the firmware on the microcontroller Cellular component firmware update A cellular component firmware update is the process of updating the firmware on the cellular component Packaged firmware update A packaged firmware update is the process of updating the firmware on the module and on the cellular component if and only if it is needed The primary reason for not always updating the cellular...

Page 235: ...me modulo 256 Component identifier 2 uint8 Set to zero may be used in the future to identify the target component Flags 3 uint8 Bit mask of values indicating various status bit 0 0x01 Initial request bit 1 0x02 Final request File fully transferred bit 2 0x04 Cancel request Used to abort an update in progress Payload 4 multi byte Next section of file being transferred FW Update Response 0xAB Descri...

Page 236: ...cifies how a host program can perform a cellular component firmware update without XCTU 1 Configure the module at a high baud rate 230 400 BD 8 2 Configure the module in API mode AP 1 3 Set up the host program to a matching baud rate and API mode 4 Send the update file a Send the first block of the file with ID set to 0 and bit 0 of the flags byte set to indicate the first frame The size of the bl...

Page 237: ...r example and then follow the steps in Perform a cellular component firmware update to redo the cellular component firmware update Error An error occurs when FW Update Response 0xAB returns a non zero status code This can be caused by a programming error on the host side for example out of order sequence numbers a software error on the module side for example too short of a timeout waiting for res...

Page 238: ...device 239 Correct a macOS Java error 241 Unresponsive cellular component in Bypass mode 242 Syntax error at line 1 242 Error Failed to send SMS 242 Network connection issues 243 Brownout issue 243 Hardware flow control in Bypass mode 244 Socket leaks 244 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 238 ...

Page 239: ...ected 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 their details 4 Remove the development board from the USB port and view which port name no longer appears in the Discover radio devices list of ports The port name that no longer appears is the correct p...

Page 240: ...r and USB from the XBIB U DEV 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 port VCP on the driver Enable Virtual COM port VCP on the driver On Windows 10 computers if XCTU does not see the devices you have attached to a PC you may need to enable VCP on the USB driver To enable...

Page 241: ...er 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 to get the file javaforosx dmg 3 Double click on the downloaded javaforosx dmg 4 In the dialog double click the JavaForOSX pkg and follow the instructions to install Java ...

Page 242: ...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 beginning of line 1 before pasting the code Error Failed to send SMS In MicroPython you consistently get Error Failed to send SMS messages Note For NB IoT SMS support is dependent on the network Conta...

Page 243: ... 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 levels the SoC may not restart properly and enter an unresponsive state You must fully power cycle the XBee to recover from this state The failure rate tends to increase with slower ramp down rates of the...

Page 244: ...eriods of high UART traffic The configuration command BD Baud Rate does not control the baud rate of this internal UART connection The XBee Smart Modem does not currently have an option to change the baud rate of the internal UART connection to match any changes to the AT IPR setting of the cellular component We suggest that customers interested in Bypass mode consider using direct USB mode Socket...

Page 245: ...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 7023 Solution To recover the leaked sockets and make them available again in all modes you should perform a reset of the cellular component hard or soft ...

Page 246: ...Regulatory information United States FCC 247 Innovation Science and Economic Development Canada ISED 250 CE mark Europe 251 Digi XBee3 Cellular LTE M NB IoT Global Smart Modem User Guide 246 ...

Page 247: ...C 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 OEMs must test final product to comply with unintentional radiators FCC section 15 107 15 109 before declaring compliance of their final product to Part 15 of the FCC Rules IMPORTANT The RF module h...

Page 248: ...PSMA 2 1 dBi Fixed A24 HABUF P5I Dipole Half wave bulkhead mount U FL w 5 pigtail 2 1 dBi Fixed A24 HASM 525 Dipole Half wave articulated RPSMA 5 25 2 1 dBi Fixed Mobile 29000812 Flexible PCB U FL w 200mm pigtail 4 4 dBi Fixed Mobile FXP74 07 0100A Flexible PCB U FL w 100mm pigtail 4 0 dBi Fixed Mobile Cellular antennas The gain of the system antenna i e the combined transmission line connector ca...

Page 249: ... includes significant extra testing and cost If an embedded trace or chip antenna is desired contact a Digi sales representative for information on how to engage with a lab to get the modified FCC grant 2 6 RF exposure considerations For RF exposure considerations see RF exposure Host product manufacturers need to provide end users a copy of the RF Exposure section of the manual RF exposure 2 7 An...

Page 250: ...t accepter tout brouillage radioélectrique subi même si le brouillage est susceptible d en compromettre le fonctionnement RF Exposure CAUTION This equipment is approved for mobile and base station transmitting devices only Antenna s used for this transmitter must be installed to provide a separation distance of at least 20 cm from all persons and must not be co located or operating in conjunction ...

Page 251: ...epas l intensité nécessaire àl établissement d une communication satisfaisante CE mark Europe The XBee is certified for use in several European countries For information visit www digi com resources certifications If the XBee is incorporated into a product the manufacturer must ensure compliance of the final product with articles 3 1a and 3 1b of the RE Directive Radio Equipment Directive A Declar...

Page 252: ... n If the CE marking is reduced or enlarged the proportions given in the above graduated drawing must be respected n The CE marking must have a height of at least 5mm except where this is not possible on account of the nature of the apparatus n The CE marking must be affixed visibly legibly and indelibly ...