Update an XBee module cellular component using API mode (over the wire)

You can update an XBee 3 Cellular LTE-M/NB-IoT module from the current module cellular component version to a more recent version over the wire, using API mode and the script described in this section.

Prerequisites

Each module must be inserted into a development board such as the Digi XBIB-CU-TH, powered on, and connected to the PC.
Each device module must be running firmware 11413 or later. For update instructions, see Update the device and the cellular firmware using XCTU or Update the device firmware.
Each module must have an active, registered SIM card installed.
Each module must be configured in the default operating mode:
- ATAM set to 0 to disable airplane mode
- ATSM set to 0 to disable sleep
- ATP0 set to 0 and ATP1 set to 0 to disable direct USB.
If any of these settings needed to be changed, issue ATWR to save changes.
Each module must be configured to use unescaped API mode: ATAP set to 1.
Each module must be configured to use the same baud rate on the UART interface (same ATBD value).
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.
Note If installing on Windows, ensure that the checkbox for "Add Python to PATH" is checked. If Python is not added to the PATH, you will need to manually specify the directory in which Python is installed in order to proceed.
The machine that will be performing the update must have visibility to an HTTP server hosting the files.
The script dependencies must be satisfied by running pip install --user -r requirements.txt in the directory containing the script. Creating and using a Python virtual environment with the virtualenv command is recommended as a best practice. If using virtualenv, install the script dependencies using pip install -r requirements.txt once the environment is activated. Refer to the instructions in the rest of this section for when to run this command.

Script usage

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

usage: update.py [-h] [--baud <BAUD>] [--type {auto,es2,ip}]
                 [--remote BASE_URL | --local BASE_DIRECTORY] [-f FILE] [-v]
                 <PORT> [<PORT> ...] [<BAUD>]
 
Update the u-blox SARA-R410M cellular module used by the Digi XBee 3 Cellular
LTE-M/NB-IoT device to a firmware version using a serial link to one or XBee 3 Cellular devices. Script version: 1.1.
 
optional arguments:
  -h, --help            show this help message and exit
 
Serial port:
  Arguments which control how the script interfaces with the XBee

  <PORT>                COM port (or /dev/ttyUSBx device) for the XBee 3
                        Cellular device. Can be specified multiple times to
                        update multiple devices.
  --baud <BAUD>         Current baud rate of the XBee 3 Cellular device(s)
                        (default: 9600)
 
Firmware update:
  Arguments which control the firmware update process
 
  --type {auto,es2,ip}  Type of modules (default: auto)
  --remote BASE_URL     HTTP server base path where update files are located
                        (default: http://ftp1.digi.com/support/ublox)
  --local BASE_DIRECTORY
                        Local directory where update files are located
                        (overrides --remote) (default: None)
  -f FILE, --file FILE  Apply only this one file (default: None)
Other arguments:
  -v, --verbose         Also emit log messages about communications with the
                        XBee (default: False)
For additional help, see the XBee 3 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/ttyX device) values for the modules you want to update are entered as arguments when you run the script. See Script usage for information about the arguments.

Identify the source version of the module cellular component using ATMV to identify the source version
Download the scripts needed to transition from the source version to the latest version.
1. Go to the Digi XBee 3 Cellular LTE-M support page.
2. Scroll down to the Firmware Updates section.
3. Look at the links that begin with u-blox Over the Wire Update Script.
4. Click the appropriate links to download the desired script or scripts. You might need more than one script to reach the most recent version.
  Note You can download more than one zip file into the same directory.
5. Unzip the downloaded file (or files).
  Note If you unzip more than one downloaded file, make sure to unzip the zip files into different directories.
Go to a command line.
Navigate to the directory containing the downloaded script.
Note If you have downloaded more than one script, you should begin with the oldest script first.
Run pip install --user -r requirements.txt in the directory containing the script.
Note If using virtualenv, run pip install -r requirements.txt instead.
Verify that you are in the same directory as the script.
Run the script. Type: python update.py <arguments>
where <arguments> includes the serial port (COM# port or /dev/tty# device, where # is the port number) and any optional parameters needed for the environment. For more information, see Script usage.
Windows example
C:\Users\admin\over-the-wire>C:\Users\admin\AppData\Local\Programs\Python\Python37-32\python.exe update.py COM17
Linux examples
$ python update.py /dev/tty5
$ python update.py COM10 --baud=115200
Press Enter to begin running the script. For a detailed description of how the update script works, see How the script works.
When complete, a digi-update.log text file is created, which contains a copy of the log messages emitted to the terminal while the script was running.
A successful update appears as:

2019-06-27 16:06:28,479 update.py: INFO: Reading cellular component version string (ATMV)...
2019-06-27 16:06:28,501 update.py: INFO: Update successful. New MV value: L0.00.00.05.08,A.02.04
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 XBee 3 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.

If you have downloaded more than one script, follow the process again, starting with Step 4.