DIGI International 90002263 XBee Multi Programmer User Guide
- July 31, 2024
- DIGI International
Table of Contents
- 90002263 XBee Multi Programmer
- Specifications:
- Product Information:
- Hardware Overview:
- Software Overview:
- Product Usage Instructions:
- 1. Connect the XBee Multi Programmer Tool:
- 2. Plug in the XBee Devices:
- 3. Load a Profile:
- 4. Program the XBee Devices:
- 5. Settings:
- Q: Where can I find product warranty information?
- Q: How can I contact Digi technical support?
- Copyright 2019, Digi International Inc. # # Permission to use, copy, modify,
- Instantiate the XBee device. device = XBeeDevice(args.portName,
- Implement a retry system to ensure a more robust connection with the target
- module. The FTDI D2XX library, used by XBee Multi Programmer, locks the
- to all ports when opening any of them. This could cause the port you are
- to access to be in use when your script tries to open the connection.
- Ensure the device is open. if not device.is_open():
- Update the XBee device name. new_name = MODULE_NAME % get_name_index()
- Save the XBee device name. device.write_changes() finally: # Close the
- References
- Read User Manual Online (PDF format)
- Download This Manual (PDF format)
90002263 XBee Multi Programmer
“`html
Specifications:
- Product Name: XBee Multi Programmer
- Release Date: March 2018
- Version: 1.2.0
- Manufacturer: Digi International
Product Information:
The XBee Multi Programmer is a tool designed for programming
XBee devices. It allows users to connect multiple XBee devices,
load profiles, program the devices, and store session reports in a
database.
Hardware Overview:
The XBee Multi Programmer features status LEDs, workflow
instructions for connecting and disconnecting devices, and supports
various types of XBee modules including through-hole,
surface-mount, and XBee3 micro-mount devices.
Software Overview:
The application software provides a user-friendly interface with
menu bars, toolbars, board panels, history tables, search
functions, configuration settings, and the ability to program XBee
devices, store session reports, and export reports in PDF or CSV
formats.
Product Usage Instructions:
1. Connect the XBee Multi Programmer Tool:
Follow the workflow instructions to properly attach the board to
your PC.
2. Plug in the XBee Devices:
-
For through-hole devices, follow the break-in procedure if
needed. -
For surface-mount and XBee3 micro-mount devices, plug them in
accordingly.
3. Load a Profile:
- Select to load a new profile or a recent profile.
- View the profile details before proceeding with
programming.
4. Program the XBee Devices:
Start the programming session and finish accordingly. Store
sessions in the database for future reference.
5. Settings:
- Adjust general settings, storage settings, and update software
as needed.
FAQ:
Q: Where can I find product warranty information?
A: To view product warranty information, visit the following
website: www.digi.com/howtobuy/terms
Q: How can I contact Digi technical support?
A: You can contact Digi technical support by calling +1
952.912.3444 or visiting www.digi.com/support.
“`
XBee® Multi Programmer User Guide
User Guide
Revision history–90002263
Revision A B
C D
Date March 2018 March 2019
June 2019 October 2019
Description Initial Release
Updated supported devices. Added Install USB drivers for cellular modems.
Added through-hole break-in procedure. Made changes for version 1.1.0 of the
application software. Added items included in the package. Clarified
terminology.
1.2.0 release.
Trademarks and copyright
Digi, Digi International, and the Digi logo are trademarks or registered
trademarks in the United States and other countries worldwide. All other
trademarks mentioned in this document are the property of their respective
owners. © 2021 Digi International Inc. All rights reserved.
Disclaimers
Information in this document is subject to change without notice and does not
represent a commitment on the part of Digi International. Digi provides this
document “as is,” without warranty of any kind, expressed or implied,
including, but not limited to, the implied warranties of fitness or
merchantability for a particular purpose. Digi may make improvements and/or
changes in this manual or in the product(s) and/or the program(s) described in
this manual at any time.
Warranty
To view product warranty information, go to the following website:
www.digi.com/howtobuy/terms
Customer support
Gather support information: Before contacting Digi technical support for help,
gather the following information:
Product name and model Product serial number (s) Firmware version Operating
system/browser (if applicable) Logs (from time of reported issue) Trace (if
possible) Description of issue Steps to reproduce
Digi XBee® Multi Programmer
2
Contact Digi technical support: Digi offers multiple technical support plans
and service packages. Contact us at +1 952.912.3444 or visit us at
www.digi.com/support.
Feedback
To provide feedback on this document, email your comments to techcomm@digi.com
Include the document title and part number (Digi XBee® Multi Programmer,
90002263 C) in the subject line of your email.
Digi XBee® Multi Programmer
3
Contents
Hardware
6
Software
6
Package contents
6
Download and install the XBee Multi Programmer application software
Requirements
9
Install XBee Multi Programmer application software
10
Install USB drivers
10
Install USB drivers for cellular modems
10
RF concepts and terminology
RF modules
13
XBee RF modules
13
Radio firmware
13
Configuration profile
13
Hardware overview
General features
16
Status LEDs
16
Workflow
17
Connect the XBee Multi Programmer tool
19
Plug in the XBee devices
19
Through-hole devices
19
Surface-mount devices
20
XBee3 micro-mount devices
20
Unplug the XBee devices
21
Through-hole break-in procedure
21
Replace XBee socket boards
21
Application software overview
Menu bar
27
Toolbar
27
Board panels
28
History table
29
Digi XBee® Multi Programmer
4
Table toolbar
30
Search for programming tasks
30
Search examples
31
Lock scroll
32
Clear completed programming tasks
32
Status bar
32
Connect an XBee Multi Programmer board
Steps to properly attach the board to your PC
35
Detach an XBee Multi Programmer board
35
Load a profile
Load a new profile
36
Load a recent profile
36
View the profile details
37
Configuration
37
Settings
38
File system
38
Scripts
39
Program the XBee devices
Start the programming session
42
Finish the programming session
42
Store sessions in a database
43
Database structure
43
Export the session report
46
PDF report
46
CSV report
46
Settings
General settings
49
Storage settings
50
Update settings
51
Update software
How-to articles
How to create a profile using XCTU
54
Step 1: Create the profile
54
Step 2: Configure the profile
55
How to use a custom script to update the name of XBee devices individually
62
Step 1: Create the post-script
63
Step 2: Create the configuration profile
66
Step 3: Test the post-script
67
Known issues
Digi XBee® Multi Programmer
5
Digi XBee® Multi Programmer
The XBee Multi Programmer is a combination of hardware and software that
enables users to program multiple Digi Radio frequency (RF) devices
simultaneously. It provides a fast and easy way to prepare devices for
distribution or large network deployment. Some of the features include:
n The XBee Multi Programmer allows you to program up to six devices
simultaneously. n Connect more XBee Multi Programmers to increase the number
of devices you can program
simultaneously. n Multiple Multi programmers may be attached to the same
computer. n Three interchangeable header board variants support all the XBee
form factors to program
surface-mount (SMT), through-hole (TH) and micro-mount (MMT) Digi RF devices.
n Intuitive application interface makes it easy to start programming devices
in just a few
minutes. n Unattended programming process allows you to focus on substituting
devices in the boards
without wasting any time. n Export your programming session report or save it
in a database to track your progress. n Automatic application update keeps you
up to date with the latest software version. n Online documentation can be
accessed directly from the application.
Hardware
The XBee Multi Programmer tool is an enclosed hardware component that allows
you to program up to six RF devices at a time thanks to its six external XBee
sockets. For more information about this tool, see Hardware overview. There
are three variants of the XBee Multi Programmer tool, one for each footprint
of the XBee product line; see Replace XBee socket boards.
Software
The XBee Multi Programmer application communicates with the boards and allows
you to easily set up and execute programming sessions. For more information
about the application, see Application software overview.
Package contents
The XBee Multi Programmer package contains the following components:
Digi XBee® Multi Programmer
6
n One XBee Multi Programmer n One USB-C cable n One power supply
Package contents
Digi XBee® Multi Programmer
7
Download and install the XBee Multi Programmer application software
This section provides instructions for downloading and installing the XBee Multi Programmer. If the XBee Multi Programmer is not automatically detected when it is attached to your computer, you may also need to install the USB drivers.
Requirements
9
Install XBee Multi Programmer application software
10
Install USB drivers
10
Install USB drivers for cellular modems
10
Digi XBee® Multi Programmer
8
Download and install the XBee Multi Programmer application software
Requirements
Requirements
To program Digi RF devices with the Multi Programmer application software, you
must connect the tool to your computer. Programming requires two pieces of
external hardware:
n USB-C cable n Power supply of 9 VDC or 12 VDC with a current rating of at
least 1.5 A
Operating systems
XBee Multi Programmer is compatible with the Windows Vista/7/8/10 (32-bit or
64-bit versions) operating systems.
System requirements
Property HDD space RAM memory CPU
Minimum 300 MB 2 GB Dual-core processor
Recommended 500 MB 4 GB Quad-core processor
Supported RF devices
n XBee3 Zigbee n XBee3 DigiMesh n XBee3 802.15.4 n XBee3 Cellular LTE CAT 1 n
XBee3 Cellular LTE-M/NB-IoT n XBee Cellular LTE Cat 1 n XBee Cellular 3G n
XBee S2C n XBee SX n XBee SX 868 n XBee 900HP n XBee XSC
Note XBee Multi Programmer supports all of the devices listed above in all
hardware variants, including surface-mount (SMT), through-hole (TH) and XBee3
micro-mount technology (MMT).
Digi XBee® Multi Programmer
9
Download and install the XBee Multi Programmer application software
Install XBee Multi Programmer application software
Install XBee Multi Programmer application software
To download and install the XBee Multi Programmer application software:
1. Navigate to digi.com/xbeemultiprogrammer.
2. Click Diagnostics, Utilities & MIBs. 3. Click Digi XBee Multi Programmer –
Windows x86.
4. When the file finishes downloading, run the executable file and follow the
steps in the XBee Multi Programmer Setup Wizard.
Install USB drivers
The required USB drivers are automatically installed the first time you
connect an XBee Multi Programmer tool to your computer. If the board drivers
do not automatically install, use the following instructions to install the
board drivers manually:
1. Go to the FTDI drivers page. 2. Locate the correct driver for your
operating system. 3. For the Windows operating system, click the setup
executable link. A zip file downloads. 4. Right-click the zip file and select
Extract All. A folder displays with the setup file. 5. Double-click the setup
file to run it. 6. Follow the steps in the installation wizard.
Install USB drivers for cellular modems
The XBee Multi Programmer application requires additional drivers to update
the modems of newer XBee3 Cellular devices. If you have not installed them,
use the following instructions to do so depending on the devices you want to
program.
Note This step is only required if you are going to program the modem of the
XBee3 Cellular LTE CAT 1 or XBee3 Cellular LTE-M/NB-IoT devices.
Drivers for XBee3 Cellular LTE CAT 1
1. Go to the Telit drivers page. 2. Select the Telit Windows Desktop Drivers
Installer. 3. Run the executable file. 4. Follow the steps in the installation
wizard.
Drivers for XBee3 Cellular LTE-M/NB-IoT
1. Download the u-blox drivers. 2. Uncompress the file and run the
executable. 3. Follow the steps in the installation wizard. 4. When prompted
select the ETHERNET-DHCP option. 5. After driver installation completes,
reboot your computer.
Digi XBee® Multi Programmer
10
Download and install the XBee Multi Programmer application software Install USB drivers for cellular modems CAUTION! If you are using Windows 7 or Vista, we highly recommend that you disable the drivers installation from Windows Update in order to speed up the modem update process. For more information on how to do this, see https://support.microsoft.com/enus/help/2500967/how-to- stop-windows-7-automatically-installing-drivers.
Digi XBee® Multi Programmer
11
RF concepts and terminology
This section contains concepts related to RF devices and the XBee Multi Programmer application. Understanding these concepts will help you work with the XBee Multi Programmer.
RF modules
13
Radio firmware
13
Configuration profile
13
Digi XBee® Multi Programmer
12
RF concepts and terminology
RF modules
RF modules
A radio frequency (RF) module is a small electronic circuit used to transmit
and receive radio signals on different frequencies. Digi produces a wide
variety of RF modules to meet the requirements of almost any wireless
solution, such as long-range, low-cost, and low-power modules. The most
popular wireless products are the XBee RF modules.
XBee RF modules
XBee is the brand name of a family of RF modules produced by Digi. They are modular products that make deploying wireless technology easy and cost- effective. Digi has made multiple protocols and RF features available in the popular XBee footprint, giving you flexibility to choose the best technology for your needs.
XBee RF modules are available in three form-factors, through-hole, surface-
mount, and micro-mount, each with various antenna options. Most modules are
available in the through-hole form factor and each share the same footprint.
Radio firmware
Radio firmware is program code stored in a radio module’s persistent memory
that provides the control program for the device. The main goal of the XBee
Multi Programmer application is to program the same radio firmware in multiple
devices simultaneously. The XBee Multi Programmer gets the radio firmware that
you program from the configuration profile loaded in the application. For more
information about configuration profiles, see Configuration profile.
Configuration profile
A configuration profile is a snapshot of a specific radio firmware
configuration. The profile is useful in a production environment when you need
to set the same radio firmware and parameters on multiple radios. A
configuration profile is an XPRO file containing the following elements:
n Radio firmware to be programmed in the device. n Firmware settings to
configure with their respective values. n File system to be flashed in the
XBee device. n Pre and post-scripts to be executed during the programming
process.
l Pre-script is executed just before starting the programming process in the
XBee device. l Post-script is executed when the entire programming
process–firmware, settings and file-
system–is finished. n Other configurations and metadata to identify the
profile, such as the flash firmware policy,
profile description, and so on.
XBee Multi Programmer requires a configuration profile to be loaded before
starting the programming process for the necessary information to be
available.
Digi XBee® Multi Programmer
13
RF concepts and terminology
Configuration profile
Note XCTU is required to generate and save configuration profiles. XCTU is a free multi-platform application designed to enable developers to interact with Digi RF modules through a graphical interface. See How to create a profile using XCTU for more information about generating profiles.
Digi XBee® Multi Programmer
14
Hardware overview
This section provides information about the steps required to work with the XBee Multi Programmer tool.
General features
16
Status LEDs
16
Workflow
17
Connect the XBee Multi Programmer tool
19
Plug in the XBee devices
19
Unplug the XBee devices
21
Through-hole break-in procedure
21
Replace XBee socket boards
21
Digi XBee® Multi Programmer
15
Hardware overview
General features
General features
The XBee Multi Programmer tool is a hardware device designed to allow for
concurrent XBee programming using the XBee Multi Programmer application
software.
There are three types of interchangeable header boards, one per XBee form
factor (each sold separately):
n Through-hole sockets (TH) n Surface-mount sockets (SMT) n Micro-mount
sockets (MMT) These boards are interchangeable depending on the needs of the
user.
Note To change the current header board, you must temporarily remove the
plastic enclosure of the hardware device.
Status LEDs
Each XBee socket of the XBee Multi Programmer header board has four LEDs that
indicate the programming status of the XBee device attached to that socket.
LED Conn
Prog
Color Blue
Yellow/Orange
Description Indicates whether an XBee device is attached to the socket (ON) or not (OFF). This LED blinks when the programming process is taking place. When finished, the LED is turned off and any of the Pass or Fail LEDs are turned on to indicate the final state of the programming operation.
Digi XBee® Multi Programmer
16
Hardware overview
Workflow
LED Color Pass Green
Fail Red
Description This LED illuminates when the programming process of the XBee device attached to the socket finishes successfully. If the programming process finishes with any error, this LED illuminates.
Workflow
The normal workflow for this tool is:
1. Open the XBee Multi Programmer application software. 2. Connect the power
supply and USB-C connector. 3. Select a valid profile. 4. Start the session.
5. Plug one or more XBee devices into the board and verify they are detected
by the tool. 6. Whenever a device is successfully programmed, you can take it
out of the socket and replace it
with a new one without disconnecting the board.
Digi XBee® Multi Programmer
17
Hardware overview
Workflow
Digi XBee® Multi Programmer
18
Hardware overview
Connect the XBee Multi Programmer tool
Connect the XBee Multi Programmer tool
The XBee Multi Programmer tool has a power source socket (left) and a USB-C
socket (right).
To power on the XBee Multi Programmer, connect a 9 VDC or 12 VDC power supply
to the power source socket. The current rating on the supply should be at
least 1.5 A. The red LED next to the power socket should light up to indicate
the programmer is properly powered. After powering the tool, connect a USB-C
cable to the USB socket to allow for proper programming. The USB-C on this
tool uses USB 2.0 technology.
Plug in the XBee devices
XBee Multi Programmer allows you to connect up to six of the same type of XBee
devices. The application detects the connection event of any device. To
connect one XBee device to one of the sockets, complete the following steps
for the appropriate XBee device.
Through-hole devices
Note See Through-hole break-in procedure. XBee through-hole devices have a
flat edge and a more angular, diagonal edge. Match that footprint with the
white lines on your board and carefully insert it, taking care not to bend any
of the pins.
Digi XBee® Multi Programmer
19
Hardware overview
Plug in the XBee devices
XBee through-hole alignment tip
Touch pins 10 and 11 first; this allows time to align the pins without false
detection of the XBee prior to complete contact of the pins to the socket.
Surface-mount devices
For XBee surface-mount devices, align all XBee pins with the spring header and
carefully push the device until it is hooked to the board. Ensure that pin 1
of the XBee device matches pin 1 of the socket.
XBee3 micro-mount devices
For XBee3 micro-mount devices, align all XBee pins with the spring header and
carefully push the device until it is hooked to the board. Ensure that pin 1
of the XBee device matches pin 1 of the socket.
Digi XBee® Multi Programmer
20
Hardware overview
Unplug the XBee devices
You can repeat this process on the remainder of XBee sockets. No waiting time is required between connecting or disconnecting devices. Note Make sure the modules are correctly plugged into the board and their footprints match the white lines on the board.
Unplug the XBee devices
This board has been designed to allow for XBee devices to be unplugged whether
the board is powered or not. The application will detect the disconnection
event of any device.
Note The devices should not be disconnected while they are being programmed.
Wait until the process is completed before disconnecting the devices.
To unplug an XBee from the board:
n For XBee through-hole devices, take the device from its top and bottom edges
and pull up carefully, taking care not to bend any of the pins.
n For XBee surface-mount and micro-mount devices, holes have been cut in the
programmer above and below each unit to facilitate gripping the device. Take
care not to bend the socket pins when lifting the device out of the socket.
Through-hole break-in procedure
The XBee Multi Programmer through-hole has sockets that can stand up to many
insertions before needing replacement. These sockets tend to be very tight
when new and loosen over time. The first full insertions should be done
without the programming software engaged and trying to program the units.
1. In each socket, plug in an XBee fully. 2. Remove the XBee by grabbing the
top and bottom and wiggling it back and forth as it is being
removed. Be careful not to bend the pins of the XBee during this process. 3.
Repeat this five times before clicking Play and programming the devices.
The insertion and extraction will continue to be very stiff for the first 10
to 20 insertions. After 20 full insertions and extractions, the socket will
still function well with a half insertion. Insert with enough force to make
good contact with the pins (about half way into the sockets). When the
programming completes the extraction will require less force.
Replace XBee socket boards
To replace XBee socket boards, order interchangeable board(s) by part number:
XBee device form-factor Micro-mount (MMT) Surface-mount (SMT) Through-hole (TH)
Part number XBEE-MP-MCRO-PCB XBEE-MP-SMT-PCB XBEE-MP-TH-PCB
When you have the board(s):
Digi XBee® Multi Programmer
21
Hardware overview
Replace XBee socket boards
1. Remove the USB connector and power cable.
2. Remove seven screws.
3. Remove the plastic cover. You may need a thin knife blade or a flat-head
screw driver to help pry off the plastic cover.
4. Use the extraction levers shown in the following picture. They are XBee
Multi Programmer PCB Extraction Levers.
This picture shows the location to insert the levers:
Digi XBee® Multi Programmer
22
Hardware overview This picture shows a lever inserted correctly:
Replace XBee socket boards
This picture shows a lever inserted incorrectly:
5. Apply pressure such that the top board rises evenly, so that pins are not
bent or damaged during the removal process. Ensure that the lever is not
flexing the plastic housing more than a few millimeters; if so, the extraction
lever is inserted too far.
WARNING! Lifting only one side at a time will bend the pins!
Digi XBee® Multi Programmer
23
Hardware overview 6. Inspect the connectors for any damaged or bent pins.
Replace XBee socket boards
7. Insert the new board.
Digi XBee® Multi Programmer
24
Hardware overview
Replace XBee socket boards
8. Press firmly on the board next to the connectors such that the board seats evenly until touching the standoffs.
9. Place the plastic cover on the XBee Multi Programmer again. 10. Place and tighten the screws.
Digi XBee® Multi Programmer
25
Application software overview
The XBee Multi Programmer application software is divided into five main sections:
Menu bar
27
Toolbar
27
Board panels
28
History table
29
Status bar
32
Digi XBee® Multi Programmer
26
Application software overview
Menu bar
Menu bar
The menu bar is located at the top of the user interface. Use the menu bar to
access all XBee Multi Programmer features.
Toolbar
The toolbar is located below the menu bar near the top of the page.
Digi XBee® Multi Programmer
27
Application software overview
Board panels
Board panels
Board panels are displayed below the toolbar of the application and represent
physical XBee Multi Programmer devices. There is one board panel per multi
programmer connected to your computer. When the application software detects a
new XBee Multi Programmer, it is assigned an index starting at 1 and appears
in the board panel.
Each board panel contains six slot elements representing the XBee slots of the actual XBee Multi Programmer board. When there is no module, the slot representation shows that information. The slot elements can display the following statuses:
Status XBee radio module not detected
Image
XBee radio module detected
Programming task in progress
Programming task succeeded
Digi XBee® Multi Programmer
28
Application software overview
Status Programming task failed
Image
History table
Note You can collapse board panels using their corresponding collapse button,
providing more space for the history table. For more information, see History
table.
History table
The history table is the main control of the application and is located in the
center of the user interface. The history table displays all the programming
tasks that have been finished and those that are taking place in the XBee
slots of the XBee Multi Programmer tools connected to your computer.
Each programming task displays the following information in the table:
n #. Index identifier of the programming task. This index starts at 1 and
increments by 1 for each new programming task that is executed.
n Status. Status of the programming task. The available statuses are listed in
the following table:
Status Waiting In progress Success Error
Description XBee device is connected in the socket, but the programming
process has not started yet. Programming process is in progress.
Programming process finished successfully.
Programming process failed.
Digi XBee® Multi Programmer
29
Application software overview
History table
n Date. Complete date when the programming task started. n Socket. XBee Multi
Programmer board index and XBee socket ID of the device being
programmed. n Progress. Total percentage of the task’s programming process. n
Elapsed. Total elapsed time in minutes and seconds for the programming task
from beginning
to end. n MAC address. MAC address of the XBee device corresponding to the
task.
Note The MAC address does not display until the programming task writes the
firmware settings in the radio module.
n Details. Information about the actions taking place in the programming
process. If the programming task failed, this field displays the reason.
Note History table columns allow you to sort programming tasks in ascending or
descending order based on the column criteria.
The header pane of the history table contains a small toolbar located at the
right side that allows you to perform some tasks in the table. For more
information, see Table toolbar.
Table toolbar
The table toolbar is located at the right side of the history table header and
contains the following elements:
Name Lock scroll button
Description Toggles to lock scroll and unlock.
Control image
Clear completed tasks button Search box
Allows you to clear completed programming tasks. Allows you to search for programming tasks.
Search for programming tasks
You can use the search box of the history table toolbar to find programming
tasks by Status, Board, Slot and unique address. Type your search expression
in the search box. You can type the following search prefixes:
Digi XBee® Multi Programmer
30
Application software overview
History table
Search prefix STATUS: BOARD: SLOT: ADDR:
Search by Status of the programming task. Board number of the device associated with a programming task. Slot number of the device associated with a programming task. Unique address of the device associated with a programming task.
Note By default, the search box filters by address (if no prefix is added), and all the filters contain a colon. It is necessary to specify the column you want to filter. For example, 4F shows only the devices with a unique address that contains 4F. For more information, see the Search examples. You can also use a wildcard if you do not want to specify the entire parameter or if you want to find more than one programming task.
Wildcard * ?
Equals Any string Any character Escape for literals (i.e. *, ?, or )
Search examples
The following table lists some examples of searches using prefixes and
wildcards:
Description Get all the tasks done in board 2.
Get all the tasks for modules whose unique address is of this range:
0013A20040F2XXXX. Get all the tasks for modules whose unique address is of
this range: 0013A20040F213XE. Get all the tasks that failed.
Example Search box text BOARD:2 |BOARD:2 | BOARD:Board 2 ADDR:0013A20040F
ADDR:0013A20040F213?E
STATUS:Err | STATUS:Err* | STATUS:Error
It is always necessary to include the complete unique address in the search box or a partial unique address with wildcards. As shown in the previous table, you can search BOARD and SLOT columns using only the number of the target board or slot. For example, type SLOT:4 to show only the devices programmed with the Slot 4. For the STATUS column, you can also start typing a valid status value in the search box as follows (without using wildcards): STATUS:Su
Digi XBee® Multi Programmer
31
Application software overview
Status bar
In this case, only successfully programmed devices will be displayed. To see the valid status values, see History table. Note Blank spaces are included. Be careful not to include spaces after the colon that separates the prefix and the search expression. STATUS:Error (correct). STATUS: Error (incorrect) – There is a space between the colon and the expression.
Lock scroll
Whenever a new programming task is generated and added to the table, it
scrolls automatically to that task. Click the lock scroll button on the
toolbar to disable this feature and maintain the scroll at its current
position. Click the lock scroll button a second time to enable the feature.
Clear completed programming tasks
After you have finished programming, the programming tasks display a status of
Success or Error. Click the Clear completed tasks button to clear all the
completed tasks from the table and view only those in progress.
Status bar
The status bar is located at the bottom of the screen and displays the
programming session statistics, such as the number of radio modules
programmed, running time, average programming time per module, and the session
status (for example, running or stopped). When the application is looking for
new updates or installing them, the status bar also displays the status of the
process.
The SQL and CSV status icons located at the right side of the status bar indicate whether the session is being recorded in CSV and stored in a database. Note By default, all the sessions are always recorded in CSV format, which allows you to export it later to a CSV or PDF file, but you can also store the session in a database. For more information, see Store sessions in a database.
Status icon
Description Session is not being saved in CSV format. Either session is not
started yet or there was a problem generating the CSV file.
Session has started and is being saved in CSV format. You will be able to
export the session later to a CSV or PDF file.
Digi XBee® Multi Programmer
32
Application software overview
Status bar
Status icon
Description Session is not being recorded in a database. Either the session is
not started yet, the database recording is not enabled, or there was a problem
writing to the database.
Session has started and is being recorded in a database.
Digi XBee® Multi Programmer
33
Connect an XBee Multi Programmer board
The XBee Multi Programmer tool can only detect a specific type of board called the XBee Multi Programmer board. For more information about this board, see Hardware overview. Note The application automatically detects when an XBee Multi Programmer board is plugged into the PC. You can attach the board before or after the application has started.
Steps to properly attach the board to your PC
35
Detach an XBee Multi Programmer board
35
Digi XBee® Multi Programmer
34
Connect an XBee Multi Programmer board
Steps to properly attach the board to your PC
Steps to properly attach the board to your PC
Before plugging the board into your PC, make sure the board is powered
externally. To properly attach the board to your PC:
1. Connect a 9 VDC or 12 VDC power supply to the power source socket of the
board (the current rating on the supply should be at least 1.5 A).
2. Attach the board to the PC using a USB host cable.
If the application is not running when the board is connected to the PC, the
application detects the board at startup. If you attach the board once the
tool is running, the tool may take a few seconds before it detects the board.
Once a board is detected, a notification appears indicating the board ID of
the newly detected board:
When you add a new board to the tool, a graphic representation of it is
displayed as a board panel. Note Once the application is running, detecting a
new board can take several seconds.
Detach an XBee Multi Programmer board
The process of detaching or connecting a board is basically the same. The
application detects if the board’s USB host cable is disconnected from the PC.
After a few seconds, the tool displays a notification indicating the board is
disconnected.
At this point, if any module was being programmed, the update process fails
and the appropriate message is displayed. To safely remove the board:
1. Make sure there are no programming tasks in progress. 2. Remove the board
from the PC by disconnecting the USB host cable. 3. Disconnect the board from
the external power supply.
Digi XBee® Multi Programmer
35
Load a profile
Before programming the radio modules, you must load the configuration profile containing the information being programmed. For more information about configuration profiles, see Configuration profile.
Load a new profile
To load a new profile with the XBee Multi Programmer tool:
1. On the main window, click the Open button for the configuration file you want to load.
. An Open file dialog appears prompting you
2. Locate the configuration profile (XPRO file), and click Open.
Load a recent profile
To load a previously loaded profile with the XBee Multi Programmer tool:
1. On the File menu, hover over the Open recent profile option to display a
list of up to five recently opened profiles.
2. Select the profile you want to load. After a profile loads, the profile panel on the toolbar displays the configuration profile path and description and continues to display until a new profile is loaded. For more information about the toolbar, see Toolbar. Note For more information about viewing the details of the loaded profile, see View the profile details.
Digi XBee® Multi Programmer
36
Load a profile
View the profile details
View the profile details
The XBee Multi Programmer tool allows you to view the details of the currently
loaded profile. Access the Profile viewer after loading a configuration
profile to view the details.
Click the Info button in the top right corner of the toolbar of the main
window . The View profile details window appears.
This profile viewer window is divided in four sections: Configuration,
Settings, File system and Scripts.
Configuration
This tab shows general information of the profile:
n Firmware and hardware information this profile is suitable for. n Firmware
flash policy: Flash always, Flash if firmware is different, Do not flash
firmware. n Whether the device’s settings will be reset prior to loading the
profile settings. n Bootloader version, in case the firmware requires a
specific one. n Modem version, in case the firmware requires a specific one
(only for cellular devices). n Description of the profile (optional).
Digi XBee® Multi Programmer
37
Load a profile
View the profile details
Settings
By default, this tab shows the firmware settings that have been modified for
the current profile. To display all the configurable settings for the selected
profile, check the Show all firmware settings checkbox:
You can hide the non-modified settings again by clearing the Show all firmware
settings checkbox. The values configured in the profile are represented with a
blue background whereas the rest remain gray. To view the specific setting
description (see the ID in the previous graphic), click the help button ( ).
Each firmware setting has a help button. All the settings sections, such as
Network, are collapsible to help you display only parts of the profile you
want to see. You can expand or collapse all sections independently or as a
group using the plus (+) and minus (-) buttons from the top right corner of
the window.
Note All of the settings in the XBee Multi Programmer application are view-
only. To modify settings, see the XCTU User Guide.
File system
If the profile contains a file system to be flashed on the XBee device, this
tab is enabled and shows its contents and a summary with the number of files
and total size. You can navigate through the file system by expanding or
collapsing the folders.
Digi XBee® Multi Programmer
38
Load a profile
View the profile details
Scripts
Profiles can be also configured to run a pre-script and/or a post-script
during the programming process of an XBee device. If any script is configured
in the profile, this tab is enabled and shows the scripts commands to run as
well as the list of files associated to each one.
Digi XBee® Multi Programmer
39
Load a profile
View the profile details
Digi XBee® Multi Programmer
40
Program the XBee devices
Once the profile is loaded, you can start programming the XBee devices. This
process uses the loaded profile to update the firmware of the device
(depending on the specified program policy) and load the setting values. When
you start the process, the tool automatically creates a programming session.
This session contains the following information:
n Devices that have been programmed. n Start and end time, total time, and
average time per device. n Profile information.
This information appears in the main window and can also be saved when you
finish the session. This section explains how to:
Start the programming session
42
Finish the programming session
42
Store sessions in a database
43
Export the session report
46
Digi XBee® Multi Programmer
41
Program the XBee devices
Start the programming session
Start the programming session
To start the programming session, click the Start session button located on
the toolbar:
If there are any XBee devices connected to the XBee Multi Programmer board,
the application starts programming those devices. If none are connected, the
application waits until you connect any device and then starts the programming
process automatically. The XBee Multi Programmer board has four LEDs in each
slot to indicate the status of the device:
n Connected (blue) n Being programmed (yellow/orange) n Finished successfully
(green) n Finished with error (red)
Note For more information about the XBee Multi Programmer board, see Hardware
overview.
The programming process of each device is independent of the others and runs
until you stop the session. When a device has been programmed, either
successfully (green LED) or with errors (red LED), you can detach it from the
board and connect another device to that slot. The application software
detects the connection and automatically starts the programming process. You
can view the current progress of the programming process and some additional
information both in the board panels and in the history table.
Finish the programming session
When you have programmed all your devices, click the Finish session button to
end the programming session.
This action is required if you want to change the profile that is being used
to program the devices or if you want to export the session report.
WARNING! If you click Finish session when there are still modules being
programmed, you are prompted to confirm that you want to stop the process.
Devices could become unresponsive if you finish a session while they are being
programmed. Once you press the Finish session button, the application prompts
you to save the session report.
Digi XBee® Multi Programmer
42
Program the XBee devices
Store sessions in a database
Click Yes to save the session data in that moment or No to save the session
data later. See Export the session report for more information about exporting
the session data.
Store sessions in a database
The XBee Multi Programmer application software allows you to save all the
information related to the sessions in a database, such as the profile used
and its settings, user, session information and devices programmed. This is
helpful if the application is used in multiple computers, and all the
information is stored in the same place. To store sessions in a database, you
must first enable the option in the settings.
1. Click the Settings button of the toolbar or select the File > Settings
option on the menu. The Settings dialog appears.
2. On the left side of the Settings dialog, select Storage. 3. Check the Save
sessions in a database checkbox. 4. Enter the database server address, port,
user and password. 5. Click Apply and then Close.
Note Only MySQL is supported for database recording. The database user must
have the following privileges: CREATE, EXECUTE, INSERT, REFERENCES, SELECT and
UPDATE.
When you start the programming session, the application software creates a new
database called xbee_Multi_programmer and the required tables to store the
information (see Database structure for more information). As the devices are
programmed, the application automatically stores their information in the
database. The SQL indicator of the status bar toggles green when the session
is being stored in a database.
For more information about the contents of the database, see Database
structure.
Database structure
The xbee_multi_programmer database has five tables:
Digi XBee® Multi Programmer
43
Program the XBee devices
Store sessions in a database
The following tables provide information about the contents of the database
tables.
profile_xbmp
The profile_xbmp table contains information about the profiles used in the
tool.
Column file_md5 file_path firmware_info hardware_version flash_policy reset_settings description fs_summary pre_script_cmd post_script_cmd
Type char(32) varchar(255) varchar(255) varchar(10) varchar(35) varchar(10) varchar(255) varchar(512) varchar(1024) varchar(1024)
Description Primary key. MD5 hash of the profile zip package. Profile path. Firmware information. Hardware information. Flash policy. Reset settings. Profile description. File system summary. Pre-script command. Post-script command.
profile_settings_xbmp
The profile_settings_xbmp table contains the different settings associated to
the profiles.
Digi XBee® Multi Programmer
44
Program the XBee devices
Store sessions in a database
Column profile_id
Type char(32)
at_command char(2)
at_value
varchar(40)
Description Primary key. References to the file_md5 column of profile_xbmp. Primary key. AT command. Primary key. AT command value.
user_xbmp
The user_xbmp table contains information about the users of the tool.
Column mac name_pc
Type varchar(16) varchar(255)
Description Primary key. MAC address of the user’s computer.
Computer name.
session_xbmp
The session_xbmp table contains information about the sessions.
Column profile_id
user_mac start_date end_date num_modules num_errors timeper module
Type char(32)
Description Primary key. References to the filemd5 column of profile xbmp.
varchar(16) Primary key. References to the mac column of user_xbmp.
datetime Primary key. Date and time when the session started.
datetime Date and time when the session finished.
int(11)
Number of devices programmed successfully.
int(11)
Number of devices not programmed due to an error.
int(11)
Average programming time per device.
programming_task_xbmp
The programming_task_xbmp table contains information about the programming
tasks.
Column profile_id
Type char(32)
Description Primary key. References to the file_md5 column of profile_xbmp.
user_mac varchar(16) Primary key. References to the mac column of user_xbmp.
session_ date
datetime Primary key. References to the start_date column of session_xbmp.
task_id
int(11)
Primary key. Index identifier of the programming task.
task_status varchar(10) Status of the programming task.
Digi XBee® Multi Programmer
45
Program the XBee devices
Export the session report
Column
Type
Description
start_date boardslot elapsed
mac address details
datetime Complete date at which the programming task started.
varchar(20) XBee Multi Programmer board index and socket ID of the device.
int(11)
Total time (in seconds) elapsed since the programming task started until finished.
varchar(16) MAC address of the XBee device corresponding to the task.
varchar (255)
Information about the error in case the programming task failed.
Export the session report
Once you have finished the programming process, you can save a report and
export it to a PDF or CSV file. Complete the following steps to export the
session report:
1. Select the File > Export session data option from the menu. 2. Select the
destination folder, the name of the file and the file type of the report:
n PDF file (.pdf) n CSV file (.csv) 3. Click Save to generate the session
report.
PDF report
The PDF report provides the following information:
1. Session statistics. Start and end time, total session time, number of
devices programmed successfully, and number of errors and average time per
module.
2. Profile information. Profile path, firmware information, hardware version,
flash policy, reset settings, description, bootloader version, modem version,
file system summary, pre-script, post-script and list of settings.
3. History table. List with all the devices that have been programmed (both
successfully or with errors) and details.
CSV report
The CSV report has four sections:
1. Session statistics. Start and end time, total session time, number of
devices programmed successfully, number of errors and average time per module.
2. Profile information. Profile path, firmware information, hardware version,
flash policy, reset settings, description, bootloader version, modem version,
file system summary, pre-script and post-script.
3. Firmware settings. List of firmware settings and their values.
Digi XBee® Multi Programmer
46
Program the XBee devices
Export the session report
4. History table. List with all the devices that have been programmed (both
successfully or with error) and details.
The following is an example of the CSV file: Start,End,Total
time,Successes,Errors,Time per module 6/28/17 4:22:42 PM,6/28/17 4:43:50
PM,00:21:07,6 (100 %),0 (0 %),01:05 Profile,Information,HW version,Flash
policy,Reset settings,Description,Bootloader version,Modem version,File System
summary,Prescript,Post-script C:profile31010.xpro,”XBEE – XBC LTE Cat 1 AT&T
– 31010″,0x49,Flash always,Yes,””,1.6.7,23.00.303,””,”pre:python.exe pre
script.py”,”post:python.exe Setting,Value NI (Node Identifier),DIGI AP (API
Enable),1 Status,Date,Socket,Elapsed,MAC address,Details SUCCESS,6/28/17
4:22:42 PM,Board 1 – Slot 6,00:56,0013A200XXXXXXXX,”” SUCCESS,6/28/17 4:22:42
PM,Board 1 – Slot 1,00:58,0013A200XXXXXXXX,”” SUCCESS,6/28/17 4:22:42 PM,Board
1 – Slot 3,01:02,0013A200XXXXXXXX,”” SUCCESS,6/28/17 4:22:42 PM,Board 1 – Slot
5,01:03,0013A200XXXXXXXX,”” SUCCESS,6/28/17 4:22:42 PM,Board 1 – Slot
2,01:05,0013A200XXXXXXXX,”” SUCCESS,6/28/17 4:22:42 PM,Board 1 – Slot
4,01:12,0013A200XXXXXXXX,””
Digi XBee® Multi Programmer
47
Settings
This section describes how to configure several XBee Multi Programmer
settings. To open the Settings dialog, click the Settings button of the
toolbar or select the File > Settings option of the menu.
The setting categories are listed on the left side of the Settings dialog. You can configure settings for the following categories:
General settings
49
Storage settings
50
Update settings
51
Digi XBee® Multi Programmer
48
Settings
General settings
General settings
To configure some general settings of the application, complete the following
steps:
1. Click the Settings button on the toolbar or select the File > Settings
option of the menu. The Settings dialog appears.
2. On the left side of the Settings dialog, select General.
3. Configure the following settings and click Apply.
Setting
Description
Retries to program a radio module
If the programming process of a device fails, it retries the process the number of times you specify in this setting.
Override pre and postscripts timeout
Check this setting to use a different pre and post-scripts timeout than the one established in the configuration profile. Once the setting is checked you can enter the new timeout values for the pre and post-scripts (in seconds).
Custom logo Configures the logo to be drawn in the PDF report document. If the custom logo value is empty, the application draws the Digi logo by default. See Export the session report for more information.
Digi XBee® Multi Programmer
49
Settings
Storage settings
Storage settings
Complete the following steps to enable and configure storage mechanisms for
the programming sessions.
1. Click the Settings button of the toolbar or select the File > Settings
option of the menu. The Settings dialog appears.
2. On the left side of the Settings dialog, select Storage.
3. Configure the following settings and click Apply.
Setting
Description
Save
Enables or disables the database storage mechanism for the programming sessions.
sessions in a When this setting is selected, all of the MySQL database storage settings are enabled.
database
Database hostname
Address of the database server.
Database port
Port to access the database.
Database user
User value of the database account.
Digi XBee® Multi Programmer
50
Settings
Update settings
Setting Database password
Description Password value of the database account.
Note Only MySQL is supported for the database storage.
Update settings
Complete the following steps to enable or disable the option to automatically
check for new application updates when the application is started.
1. Click the Settings button of the toolbar or select File > Settings option
of the menu. The Settings dialog appears.
2. On the left side of the Settings dialog, select Update.
3. Select or clear the Automatically check for updates every time the
application is started checkbox to enable or disable the automatic updates
feature.
4. Click Apply.
Digi XBee® Multi Programmer
51
Update software
XBee Multi Programmer allows you to automatically update the application
without downloading any extra files. This process can be configured to execute
automatically, but you can also execute it manually at any time. For more
information about configuring automatic updates, see Update settings. If you
have enabled the automatic updates, you may be notified about software updates
when you open XBee Multi Programmer. You should always run the latest version
of the tool.
1. When a new version is available, a notification window appears asking you
if you want to update the application.
2. Click Yes to start the update process. 3. When the installation process is
finished, you must restart XBee Multi Programmer so new
changes can be applied. When prompted, click Yes to restart the tool. You can
also check for updates and manually update the tool by clicking Help > Check
for updates. Note Click the Run in background button of the progress dialog to
execute this process in the background. The status bar displays the update
process.
Digi XBee® Multi Programmer
52
How-to articles
The following pages contain how-to articles describing some of the most common procedures to work with the XBee Multi Programmer tool.
How to create a profile using XCTU
54
How to use a custom script to update the name of XBee devices individually
62
Digi XBee® Multi Programmer
53
How-to articles
How to create a profile using XCTU
How to create a profile using XCTU
XCTU is required to generate and save configuration profiles. This section
provides the steps to create a profile using XCTU. For more information about
configuration profiles, see Configuration profile.
Step 1: Create the profile
XCTU offers two methods for configuring a profile:
n Configuration working mode n Profile Editor
Configuration working mode
Configuration working mode allows you to quickly generate profiles for devices
attached to your computer.
1. In the main window of XCTU, switch to Configuration working mode . 2.
Select a device from the device list. 3. Configure the radio module with the
appropriate values. You only need to change the values;
they do not need to be written to the specific device. 4. Click the
Configuration profiles drop-down menu on the configuration toolbar and select
Create configuration profile.
Profile Editor
The Profile Editor is the main tool to create, visualize and edit profiles
(regardless of if you have a physical device connected to your computer or
not).
1. In the main window of XCTU, select the Profile Editor tool in the tools
menu.
Digi XBee® Multi Programmer
54
How-to articles
How to create a profile using XCTU
2. Click the Create button.
Step 2: Configure the profile
In this step you have to create a representative model upon which to base the
configuration profile by specifying the general configuration, firmware
version and settings. A wizard guides you through the different steps in order
to create the profile.
1. Specify the general profile configuration:
Digi XBee® Multi Programmer
55
How-to articles
How to create a profile using XCTU
n Flash radio firmware. Check this option if you want the profile to flash the
radio firmware. If you do so, you have also to specify the flash policy:
l Flash if firmware is different. If the target device has the same firmware
version as the one selected in the profile, firmware is not flashed. If the
target device does not have the same firmware version as the one selected in
the profile, the firmware is flashed into the device.
l Flash always. The firmware image is always programmed into the device. n
Reset module to factory defaults before applying settings. Check this option
if you want to
reset the XBee device settings to their default values prior to applying the
profile settings.
n Flash a file system. Check this option if you want to include a file system
in the profile. n Use custom scripts for XBee Multi Programmer. Check this
option to include pre and post
scripts to be run by the XBee Multi Programmer application when flashing an
XBee device.
n Profile description (optional). Include a short description of the profile
to be generated.
Digi XBee® Multi Programmer
56
How-to articles
How to create a profile using XCTU
2. Select the firmware of the profile: Product family, Function set and Firmware version. If the selected firmware version is for an XBee Cellular device, you have the option to attach the cellular modem firmware too.
3. Choose and configure the firmware settings (optional). If you want to add any specific setting to the profile, select it and specify its value.
Digi XBee® Multi Programmer
57
How-to articles
How to create a profile using XCTU
4. Attach a file system (optional). If you checked the Flash a file system option in the first page of the wizard, you have to select the folder containing the file system to be flashed with the profile. Once you have done that, you can visualize its structure in the following panel.
Digi XBee® Multi Programmer
58
How-to articles
How to create a profile using XCTU
5. Specify Multi Programmer scripts (optional). If you checked the Use custom scripts for XBee Multi Programmer option in the first page of the wizard, you can specify the pre and post scripts to be executed by the XBee Multi Programmer application when programming an XBee device. Each script is defined by the following elements: n Script command. Process executed by the XBee Multi Programmer application. n Script timeout. Maximum time the XBee Multi Programmer application waits for the script to finish before considering a timeout error. n Script folder (optional). Folder containing the script file or files. This is the execution path of the script. The XBee Multi Programmer application provides the following parameters to the scripts when they are run, so you need to consider them when writing the script: n –portID. The FTD2XX identifier of the serial port that the XBee that has been programmed is attached to. n –portName. The name of the serial port (COMX) that the XBee that has been programmed is attached to. n –portBaudrate. The baudrate of the serial port that the XBee that has been programmed is attached to.
Digi XBee® Multi Programmer
59
How-to articles
How to create a profile using XCTU
n –boardIndex. The index of the board within the XBee Multi Programmer
application containing the slot that the XBee that has been programmed is
attached to.
n –slotIndex. The XBee slot index within the XBee Multi Programmer board that
the XBee that has been programmed is attached to.
n –xbeeAddress. The XBee 64-bit or IMEI address of the XBee that has been
programmed.
Note If the script is a pre-script instead of a post-script, XBee Multi
Programmer will not provide the -portBaudrate or –xbeeAddress parameters when
running it because they are still unknown for the application.
CAUTION! If your script communicates with an XBee device over the serial port, you must implement a retry system to ensure a more robust connection with the target device. The FTDI D2XX library used by XBee Multi Programmer locks the access to all ports when opening any of them. This could cause the port you are trying to access to be in use when your script tries to open the connection.
Digi XBee® Multi Programmer
60
How-to articles
How to create a profile using XCTU
6. Specify Multi Programmer scripts (optional). If you checked the Use custom
scripts for XBee Multi Programmer option in the first page of the wizard, you
can specify the pre and post scripts to be run by the XBee Multi Programmer
application when programming an XBee device. Each script is defined by the
following elements:
n Script command. Process run by the XBee Multi Programmer application. n
Script timeout. Maximum time the XBee Multi Programmer application waits for
the
script to finish before considering a timeout error.
n Script folder (optional). Folder containing the script file or files. This
is the execution path of the script.
Digi XBee® Multi Programmer
61
How-to articles
How to use a custom script to update the name of XBee devices individually
7. Once you are finished, click Create profile. A Save file dialog box
appears. 8. Choose a name and path and click Save.
How to use a custom script to update the name of XBee devices individually
One of the latest features added to XBee Multi Programmer application is the
ability to use custom scripts before and/or after programming XBee devices to
configure custom settings or perform any operation with them individually. In
this how-to article you will learn how to use a custom script to change the
name of an XBee device after it has been programmed by the application. This
is very useful because the XBee Multi Programmer applies the same profile to
all the XBee devices being programmed in a session, meaning that all of the
programmed devices will have the same parameters configured, like the device
name.
Digi XBee® Multi Programmer
62
How-to articles
How to use a custom script to update the name of XBee devices individually
The post-script changes the name of the XBee devices as they are programmed
with a fixed text (XBEEDEVICE) plus an index obtained from a counter file.
The value of the index is increased and saved in the counter file every time
an XBee device is programmed.
Step 1: Create the post-script
First you need to develop the post-script that will be automatically run just
after the XBee Multi Programmer application programs an XBee device. You can
write the script in any programming language, but you need to make sure the
computer running it has the necessary resources installed and available–Python
interpreter, Java machine, libraries, and so forth. The script explained in
the section uses Python 3 as programming language plus the Digi XBee Python
library to cover communicating with the XBee device. Follow these steps to
create the post-script file:
1. Create a folder in your computer named xbmp_custom_script. 2. Create a
file named counter.txt inside the xbmp_custom_script folder. 3. Edit the
counter.txt file and write the following text:
0 4. Create a file named change_name.py inside the xbmp_custom_script folder.
5. Edit the content of the change_name.py file and paste the following code:
change_name.py
Copyright 2019, Digi International Inc. # # Permission to use, copy, modify,
and/or distribute this software for any # purpose with or without fee is
hereby granted, provided that the above # copyright notice and this permission
notice appear in all copies. # # THE SOFTWARE IS PROVIDED “AS IS” AND THE
AUTHOR DISCLAIMS ALL WARRANTIES # WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
OR ANY DAMAGES # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
import argparse import os import sys import time
from digi.xbee.devices import XBeeDevice from serial import SerialException
FILE_COUNTER = “counter.txt” FILE_LOCK = “.lock”
MODULE_NAME = “XBEEDEVICE%s”
LOCK_TIMEOUT_MS = 3000
Digi XBee® Multi Programmer
63
How-to articles
How to use a custom script to update the name of XBee devices individually
def get_name_index(): “”” Returns the name index from the counter file and
updates it with the new one. Use a lock file to avoid concurrent accesses when
modifying the counter file. Returns: Integer: The name index to be used for
the Node Identifier. “”” # Wait until the lock file is released. deadline =
time.time() + LOCK_TIMEOUT_MS while os.path.isfile(FILE_LOCK) and time.time()
< deadline: time.sleep(0.1) # Lock file was not released, exit with error. if
os.path.isfile(FILE_LOCK): sys.exit(“Lock file was not released.”) # Acquire
the lock file. try: with open(FILE_LOCK, “w+”): with open(FILE_COUNTER, “r+”)
as f: # Read the index from the file. read_data = f.read() index =
int(read_data) # Update the file with the next index. f.seek(0)
f.write(str(index + 1)) f.truncate() finally: # Release (remove) the lock
file. if os.path.isfile(FILE_LOCK): os.remove(FILE_LOCK) return index
def main(): “”” Main execution of the script. Updates the name of the XBee
device located in the port specified in the arguments with a constant name +
an index read from an external file. The index is incremented by one when the
name “”” # Get all the arguments from XBee Multi Programmer. parser =
argparse.ArgumentParser() parser.add_argument(“–portID”, required=False)
parser.add_argument(“–portName”, required=False)
parser.add_argument(“–portBaudrate”, required=False, type=int)
parser.add_argument(“–boardIndex”, required=False, type=int)
parser.add_argument(“–slotIndex”, required=False, type=int)
parser.add_argument(“–xbeeAddress”, required=False) args = parser.parse_args()
Instantiate the XBee device. device = XBeeDevice(args.portName,
args.portBaudrate) try: # Open the device connection.
Digi XBee® Multi Programmer
64
How-to articles
How to use a custom script to update the name of XBee devices individually
Implement a retry system to ensure a more robust connection with the target
module. The FTDI D2XX library, used by XBee Multi Programmer, locks the
access
to all ports when opening any of them. This could cause the port you are
trying
to access to be in use when your script tries to open the connection.
retries = 10 while not device.is_open() and retries > 0:
try: device.open()
except SerialException: time.sleep(0.1) retries -= 1
Ensure the device is open. if not device.is_open():
sys.exit(“Could not open the device.”)
Update the XBee device name. new_name = MODULE_NAME % get_name_index()
device.set_node_id(new_name)
Save the XBee device name. device.write_changes() finally: # Close the
connection with the device. if device is not None and device.is_open():
device.close()
if name == ‘main’: main()
Notice that the script is expecting the following arguments which are provided
by the XBee Multi Programmer application when running it:
n –portID. The FTD2XX identifier of the serial port that the XBee that has
been programmed is attached to.
n –portName. The name of the serial port (COMX) that the XBee that has been
programmed is attached to.
n –portBaudrate. The baud rate of the serial port that the XBee that has been
programmed is attached to.
n –boardIndex. The index of the board within the XBee Multi Programmer
application containing the slot that the XBee that has been programmed is
attached to.
n –slotIndex. The XBee slot index within the XBee Multi Programmer board that
the XBee that has been programmed is attached to.
n –xbeeAddress. The XBee 64-bit or IMEI address of the XBee that has been
programmed.
Note If the script is a pre-script instead of a post-script, XBee Multi
Programmer will not provide the -portBaudrate or –xbeeAddress parameters when
running it because they are still unknown for the application.
Digi XBee® Multi Programmer
65
How-to articles
How to use a custom script to update the name of XBee devices individually
CAUTION! If your script communicates with an XBee device over the serial port,
you must implement a retry system to ensure a more robust connection with the
target device. The FTDI D2XX library used by XBee Multi Programmer locks the
access to all ports when opening any of them. This could cause the port you
are trying to access to be in use when your script tries to open the
connection.
With the parameters given by the XBee Multi Programmer application, the script
can open communication with the XBee device and change its name based on the
index number contained in the counter.txt file.
6. Save the change_name.py file.
Step 2: Create the configuration profile
The next step is to create the configuration profile with the post-script
attached so that XBee Multi Programmer can execute it. There is another
tutorial that explains How to create a profile using XCTU, but you can follow
these simplified steps if you prefer:
1. Open XCTU. 2. In the main window, select the Profile Editor tool from the
tools menu. The Profile Editor tool
displays. 3. Click the Create button from the Profile Editor toolbar. The
Create a profile wizard displays. 4. On the first page of the wizard you need
to specify the general profile configuration. Select
your desired settings but make sure you check the Use custom scripts for XBee
Multi Programmer option. This enables a final page in the wizard to configure
the pre and postscripts. Click Next when you are done. 5. On the second page
of the wizard you must select the firmware version of the profile. You can do
so specifying the Product family, Function set and Firmware version options.
Once you have selected your desired firmware, click Next to continue. 6. On
the next page you can configure the value of the firmware settings that you
want to apply to your XBee devices. Click Next when you are ready. 7. If you
did not check the Flash a file system option on the first page of the wizard,
skip to step 8. Otherwise, the Attach a file system page displays and you are
forced to configure a file system for the profile. When you are done, click
Next. 8. The Attach your custom pre/post scripts page and this is where you
must to specify the postscript that XBee Multi Programmer will run. Leave all
the pre-script options empty and configure the post-script ones: a. Post-
processing script command. Fill it with the command to be run by the XBee
Multi Programmer application:
python.exe change_name.py
Note Notice that you must add Python 3 to the Path environment variable of the
computer where you run the XBee Multi Programmer application, otherwise
python.exe will not be found and the script execution will fail.
Digi XBee® Multi Programmer
66
How-to articles
How to use a custom script to update the name of XBee devices individually
b. Script timeout (seconds). This is the maximum time XBee Multi Programmer
waits for the script to finalize running before considering it as failed. It
is required, so fill it with 5 seconds for example–the communication with the
device should not take longer than 1 second.
c. Post-processing script folder. Here you need to specify the folder within
your computer where the post-script is located at. All the files contained in
the folder are attached to the configuration profile and XBee Multi Programmer
is able to access them as that folder will be the execution path of the
script. Configure this option with the xbmp_custom_script folder you created
previously. When you have configured it, you can see its structure in the
panel below.
9. Click Create profile to create your configuration profile specifying the
destination file when prompted. Name it custom_script_profile.xpro for
example.
Step 3: Test the post-script
The final step is to test that the post-script attached to the configuration
profile works properly. To do so follow these steps:
1. Attach the XBee Multi Programmer board to your computer. 2. Open the XBee
Multi Programmer application. 3. Select the File > Open profile option from
the main menu and browse the customscript
profile.xpro you created previously to load it in the application. 4. Select
the File > View profile Information option from the main menu to open the
Profile
viewer dialog that displays the configuration of the profile. Select the
Scripts tab and verify that the post-script configuration is correct.
Digi XBee® Multi Programmer
67
How-to articles
How to use a custom script to update the name of XBee devices individually
5. Close the Profile viewer dialog. 6. Attach six XBee devices to the XBee
Multi Programmer board. 7. Click the Start Session button from the toolbar to
start the programming session. 8. A programming task is run for each device
attached to the board. After flashing the firmware
and configuring the settings, the Details column of the history table should
display the Executing post-script… message, indicating that the post-script is
being executed for that device. After that, the process should complete
successfully. 9. Once all the devices have been programmed, click the Finish
session button from the toolbar to end the programming session. 10. Open XCTU.
11. Attach each device to your computer through a development board and add
them to XCTU. 12. Verify that the names of the devices go from XBEE_DEVICE_0
to XBEE_DEVICE_5.
Digi XBee® Multi Programmer
68
Known issues
The XBee Multi Programmer application currently has the following known issues
and limitations:
n It is not possible to update XBee Cellular LTE Cat 1 modules to firmware
versions lower than 100A.
n If you use pre/post scripts to communicate with an XBee device over the
serial port, you must implement a retry system to ensure a more robust
connection with the target device. The FTDI D2XX library used by XBee Multi
Programmer locks the access to all ports when opening any of them. This could
cause the port you are trying to access to be in use when your script tries to
open the connection.
Digi XBee® Multi Programmer
69
Mouser Electronics
Authorized Distributor
Click to View Pricing, Inventory, Delivery & Lifecycle Information:
Digi International:
XBEE-MP-MCRO XBEE-MP-TH
References
- Technical Support | Digi International
- GitHub - digidotcom/xbee-python: Python library to interact with Digi International's XBee radio frequency modules.
- How to stop Windows 7 automatically installing drivers - Microsoft Support
- Digi XBee Multi Programmer | Digi International
- XCTU User Guide
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>