Update the XBee¶
To keep your XBee devices up to date, the XBee Python Library provides several methods to update the device software including firmware, file system and XBee profiles:
Warning
- At the moment, update features are only supported in:
- XBee 3:
- Local and remote firmware updates
- Local and remote file system updates
- Local and remote profile updates
- XBee SX 868/900 MHz
- Local and remote firmware updates
- Local and remote profile updates
- XBee S2C
- Remote firmware updates
- Remote profile updates
Update the XBee firmware¶
You may need to update the running firmware of your XBee devices to, for example, change their XBee protocol, fix issues and security risks, or access to new features and functionality.
The XBee Python Library provides methods to perform firmware updates in local and remote devices:
Warning
- At the moment, firmware update is only supported in:
- XBee 3: Local and remote firmware updates
- XBee SX 868/900 MHz: Local and remote firmware updates
- XBee S2C: Remote firmware updates
Update the firmware of a local XBee¶
The firmware update process of a local XBee device is performed over the serial connection. For this operation, you need the following components:
- The XBee device object instance or the serial port name where the device is attached to.
- The new firmware XML descriptor file.
- The new firmware binary file (*.gbl)
- Optionally, the new bootloader binary file (*.gbl) required by the new firmware.
Warning
Firmware update will fail if the firmware requires a new bootloader and it is not provided.
Warning
At the moment, local firmware update is only supported in XBee 3 and XBee SX 868/900 MHz devices.
Example: Local Firmware Update |
---|
The XBee Python Library includes a sample application that displays how to perform a local firmware update. It can be located in the following path: examples/firmware/LocalFirmwareUpdateSample/LocalFirmwareUpdateSample.py |
Update the local firmware using an XBee device object¶
If you have an object instance of your local XBee device, you have to call
the update_firmware
method of the XBeeDevice
class providing the
required parameters:
Method | Description |
---|---|
update_firmware(String, String, String, Integer, Function) | Performs a firmware update operation of the device.
|
The update_firmware
method may fail for the following reasons:
The device does not support the firmware update operation, throwing a
OperationNotSupportedException
.There is an error during the firmware update operation, throwing a
FirmwareUpdateException
.Other errors caught as
XBeeException
:- The device is not open, throwing a generic
XBeeException
. - The operating mode of the local XBee device is not
API_MODE
orESCAPED_API_MODE
, throwing anInvalidOperatingModeException
.
- The device is not open, throwing a generic
Update local XBee device firmware using an XBee device object
[...]
XML_FIRMWARE_FILE = "my_path/my_firmware.xml"
XBEE_FIRMWARE_FILE = "my_path/my_firmware.gbl"
BOOTLOADER_FIRMWARE_FILE = "my_path/my_bootloader.gbl"
[...]
# Instantiate an XBee device object.
xbee = XBeeDevice(...)
[...]
# Update the XBee device firmware.
device.update_firmware(XML_FIRMWARE_FILE,
xbee_firmware_file=XBEE_FIRMWARE_FILE,
bootloader_firmware_file=BOOTLOADER_FIRMWARE_FILE,
progress_callback=progress_callback,)
[...]
Update the local firmware using a serial port¶
If you do not know the XBee serial communication parameters or you cannot instantiate the XBee device object (for example if the device must be recovered), you can perform the firmware update process by providing the serial port identifier where the XBee is attached to.
In this scenario, use the update_local_firmware
method of the
XBee firmware
module providing the required parameters. The library
forces the XBee to reboot into bootloader mode, using the recovery mechanism,
and performs the firmware update from that point.
Method | Description |
---|---|
update_local_firmware(String or XBeeDevice, String, String, String, Integer, Function) | Performs a local firmware update operation in the given target.
|
The update_local_firmware
method may fail for the following reasons:
- There is an error during the firmware update operation, throwing a
FirmwareUpdateException
.
Update local XBee device firmware using a serial port
import digi.xbee.firmware
[...]
SERIAL_PORT = "COM1"
XML_FIRMWARE_FILE = "my_path/my_firmware.xml"
XBEE_FIRMWARE_FILE = "my_path/my_firmware.gbl"
BOOTLOADER_FIRMWARE_FILE = "my_path/my_bootloader.gbl"
[...]
# Update the XBee device firmware using the serial port name.
firmware.update_local_firmware(SERIAL_PORT,
XML_FIRMWARE_FILE,
xbee_firmware_file=XBEE_FIRMWARE_FILE,
bootloader_firmware_file=BOOTLOADER_FIRMWARE_FILE,
progress_callback=progress_callback,)
[...]
Update the firmware of a remote XBee¶
The firmware update process for remote XBee devices is performed over the air using special XBee frames. For this operation, you need the following components:
- The remote XBee device object instance.
- The new firmware XML descriptor file.
- The new firmware binary file (*.ota)
- Optionally, the new firmware binary file with the bootloader embedded (*.otb)
Warning
Firmware update fails if the firmware requires a new bootloader and the *.otb file is not provided.
Warning
At the moment, remote firmware update is only supported in XBee 3, XBee SX 868/900 MHz, and XBee S2C devices.
To perform the remote firmware update, call the
update_firmware
method of the RemoteXBeeDevice
class providing the
required parameters:
Method | Description |
---|---|
update_firmware(String, String, String, Integer, Function) | Performs a remote firmware update operation of the device.
|
The update_firmware
method may fail for the following reasons:
The remote device does not support the firmware update operation, throwing a
OperationNotSupportedException
.There is an error during the firmware update operation, throwing a
FirmwareUpdateException
.Other errors caught as
XBeeException
:- The local device is not open, throwing a generic
XBeeException
. - The operating mode of the local device is not
API_MODE
orESCAPED_API_MODE
, throwing anInvalidOperatingModeException
.
- The local device is not open, throwing a generic
Update remote XBee device firmware
[...]
XML_FIRMWARE_FILE = "my_path/my_firmware.xml"
OTA_FIRMWARE_FILE = "my_path/my_firmware.ota"
OTB_FIRMWARE_FILE = "my_path/my_firmware.otb"
REMOTE_DEVICE_NAME = "REMOTE"
[...]
# Instantiate an XBee device object.
xbee = XBeeDevice(...)
# Get the network.
xnet = xbee.get_network()
# Get the remote device.
remote = xnet.discover_device(REMOTE_DEVICE_NAME)
# Update the remote XBee device firmware.
remote.update_firmware(SERIAL_PORT,
XML_FIRMWARE_FILE,
xbee_firmware_file=OTA_FIRMWARE_FILE,
bootloader_firmware_file=OTB_FIRMWARE_FILE,
progress_callback=progress_callback,)
[...]
Example: Remote Firmware Update |
---|
The XBee Python Library includes a sample application that displays how to perform a remote firmware update. It can be located in the following path: examples/firmware/RemoteFirmwareUpdateSample/RemoteFirmwareUpdateSample.py |
Update the XBee file system¶
XBee 3 devices feature file system capabilities, meaning that they are able to persistently store files and folders in flash. The XBee Python Library provides classes and methods to manage these files.
Warning
At the moment file system capabilities are only supported in XBee 3 devices.
Create file system manager¶
A LocalXBeeFileSystemManager
object is required to work with local devices
file system. You can instantiate this class by providing the local XBee device
object. Once you have the object instance, you must call the connect
method to open the file system connection and leave it ready to work.
Warning
File system operations take ownership of the serial port, meaning that you will
stop receiving messages from the device until file system connection is closed.
For this reason it is highly recommended to call the disconnect
method of
the file system manager as soon as you finish working with it.
Method | Description |
---|---|
connect() | Connects the file system manager. |
disconnect() | Disconnects the file system manager and restores the device connection. |
The connect
method may fail for the following reasons:
- The device does not support the file system capabilities, throwing a
FileSystemNotSupportedException
. - There is an error during the connect operation, throwing a
FileSystemException
.
Create a local file system manager
from digi.xbee.filesystem import LocalXBeeFileSystemManager
[...]
# Instantiate an XBee device object.
xbee = XBeeDevice(...)
[...]
# Create the file system manager and connect it.
filesystem_manager = LocalXBeeFileSystemManager(xbee)
filesystem_manager.connect()
[...]
filesystem_manager.disconnect()
[...]
File system operations¶
The file system manager provides several methods to navigate through the device file system and operate with the different files and folders:
Method | Description |
---|---|
get_current_directory() | Returns the current device directory. |
change_directory(String) | Changes the current device working directory to the given one.
|
make_directory(String) | Creates the provided directory.
|
list_directory(String) | Lists the contents of the given directory.
|
remove_element(String) | Removes the given file system element path.
|
move_element(String, String) | Moves the given source element to the given destination path.
|
put_file(String, String, Boolean, Function) | Transfers the given file in the specified destination path of the XBee device.
|
put_dir(String, String, Function) | Uploads the given source directory contents into the given destination directory in the device.
|
get_file(String, String, Function) | Downloads the given XBee device file in the specified destination path.
|
format_filesystem() | Formats the device file system. |
get_usage_information() | Returns the file system usage information. |
get_file_hash(String) | Returns the SHA256 hash of the given file path.
|
The methods above may fail for the following reasons:
- There is an error executing the requested operation, throwing a
FileSystemException
.
Example: Format file system |
---|
The XBee Python Library includes a sample application that displays how to format the device file system. It can be located in the following path: examples/filesystem/FormatFilesystemSample/FormatFilesystemSample.py |
Example: List directory |
---|
The XBee Python Library includes a sample application that displays how to list the contents of a device directory. It can be located in the following path: examples/filesystem/ListDirectorySample/ListDirectorySample.py |
Example: Upload/download file |
---|
The XBee Python Library includes a sample application that displays how to upload/download a file from the device. It can be located in the following path: examples/filesystem/UploadDownloadFileSample/UploadDownloadFileSample.py |
Apply an XBee profile¶
An XBee profile is a snapshot of a specific XBee configuration, including firmware, settings, and file system contents. The XBee Python API includes a set of classes and methods to work with XBee profiles and apply them to local and remote devices.
- Read an XBee profile
- Apply an XBee profile to a local device
- Apply an XBee profile to a remote device
To configure individual settings see Configure the XBee device.
Note
Use XCTU to create configuration profiles.
Warning
- At the moment, firmware update is only supported in:
- XBee 3: Local and remote profile updates
- XBee SX 868/900 MHz: Local and remote profile updates
- XBee S2C: Remote profile updates
Read an XBee profile¶
The library provides a class called XBeeProfile
that is used to read and
extract information of an existing XBee profile file.
To create an XBeeProfile
object, provide the location of the profile file
in the class constructor.
Instantiate a profile
from digi.xbee.profile import XBeeProfile
[...]
PROFILE_PATH = "/home/user/my_profile.xpro"
[...]
# Create the XBee profile object.
xbee_profile = XBeeProfile(PROFILE_PATH)
[...]
The creation of the XBee profile object may fail for the following reasons:
- The provided profile file is not valid, throwing a
ValueError
. - There is any error reading the profile file, throwing a
ProfileReadException
.
Once the XBee profile object is created, you can extract some profile information by accessing each of the exposed properties:
Property | Description |
---|---|
profile_file | Returns the profile file. |
version | Returns the profile version. |
flash_firmware_option | Returns the profile flash firmware option. |
description | Returns the profile description. |
reset_settings | Returns whether the settings of the XBee device are reset before applying the profile ones. |
has_firmware_files | Returns whether the profile has firmware binaries (local or remote) |
has_local_firmware_files | Returns whether the profile has local firmware binaries. |
has_remote_firmware_files | Returns whether the profile has remote firmware binaries. |
has_filesystem | Returns whether the profile has filesystem information (local or remote) |
has_local_filesystem | Returns whether the profile has local filesystem information. |
has_remote_filesystem | Returns whether the profile has remote filesystem information. |
profile_settings | Returns all the firmware settings that the profile configures. |
firmware_version | Returns the compatible firmware version of the profile. |
hardware_version | Returns the compatible hardware version of the profile. |
compatibility_number | Returns the compatibility number of the profile. |
region_lock | Returns the region lock of the profile. |
To access to the files inside, use open
method. Once done with it, use
close
method.
Open/close a profile
xbee_profile = XBeeProfile(PROFILE_PATH)
xbee_profile.open()
[...]
xbee_profile.close()
[...]
An opened profile also offers the following properties:
Property | Description |
profile_description_file | Returns the path of the profile description file. |
firmware_description_file | Returns the path of the profile firmware description file. |
file_system_path | Returns the profile file system path. |
remote_file_system_image | Returns the path of the remote OTA file system image. |
bootloader_file | Returns the profile bootloader file path. |
Read a profile
from digi.xbee.profile import XBeeProfile
[...]
PROFILE_PATH = "/home/user/my_profile.xpro"
[...]
# Create the XBee profile object.
xbee_profile = XBeeProfile(PROFILE_PATH)
# Print profile compatible hardware and software versions
print(" - Firmware version: %s" % xbee_profile.firmware_version)
print(" - Hardware version: %s" % xbee_profile.hardware_version)
[...]
Example: Read an XBee profile |
---|
The XBee Python Library includes a sample application that displays how to read an XBee profile. It can be located in the following path: examples/profile/ReadXBeeProfileSample/ReadXBeeProfileSample.py |
Apply an XBee profile to a local device¶
Applying a profile to a local XBee device requires the following components:
- The local XBee device object instance.
- The profile file to apply (*.xpro).
Note
Use XCTU to create configuration profiles.
Warning
At the moment, local profile update is only supported in XBee 3 and XBee SX 868/900 MHz devices.
To apply the XBee profile to a local XBee, you have to call the
apply_profile
method of the XBeeDevice
class providing the required
parameters:
Method | Description |
---|---|
apply_profile(String, timeout, Function) | Applies the given XBee profile to the XBee device.
|
The apply_profile
method may fail for the following reasons:
The local device does not support the apply profile operation, throwing a
OperationNotSupportedException
.There is an error while applying the XBee profile, throwing a
UpdateProfileException
.Other errors caught as
XBeeException
:- The local device is not open, throwing a generic
XBeeException
. - The operating mode of the local device is not
API_MODE
orESCAPED_API_MODE
, throwing anInvalidOperatingModeException
.
- The local device is not open, throwing a generic
Apply an XBee profile to a local device
[...]
PROFILE_PATH = "/home/user/my_profile.xpro"
[...]
# Instantiate an XBee device object.
xbee = XBeeDevice(...)
[...]
# Apply the XBee device profile.
device.apply_profile(PROFILE_PATH, progress_callback=progress_callback)
[...]
Example: Apply local XBee profile |
---|
The XBee Python Library includes a sample application that displays how to apply an XBee profile to a local device. It can be located in the following path: examples/profile/ApplyXBeeProfileSample/ApplyXBeeProfileSample.py |
Apply an XBee profile to a remote device¶
Applying a profile to a remote XBee requires the following components:
- The remote XBee device object instance.
- The profile file to apply (*.xpro).
Note
Use XCTU to create configuration profiles.
Warning
At the moment, remote profile update is only supported in XBee 3, XBee SX 868/900 MHz, and XBee S2C devices.
To apply the XBee profile to a remote XBee device, you have to call the
apply_profile
method of the RemoteXBeeDevice
class providing the
required parameters:
Method | Description |
---|---|
apply_profile(String, timeout, Function) | Applies the given XBee profile to the remote XBee device.
|
The apply_profile
method may fail for the following reasons:
The remote device does not support the apply profile operation, throwing a
OperationNotSupportedException
.There is an error while applying the XBee profile, throwing a
UpdateProfileException
.Other errors caught as
XBeeException
:- The local device is not open, throwing a generic
XBeeException
. - The operating mode of the local device is not
API_MODE
orESCAPED_API_MODE
, throwing anInvalidOperatingModeException
.
- The local device is not open, throwing a generic
Apply an XBee profile to a remote device
[...]
PROFILE_PATH = "/home/user/my_profile.xpro"
REMOTE_DEVICE_NAME = "REMOTE"
[...]
# Instantiate an XBee device object.
xbee = XBeeDevice(...)
# Get the network.
xnet = xbee.get_network()
# Get the remote device.
remote = xnet.discover_device(REMOTE_DEVICE_NAME)
[...]
# Apply the XBee device profile.
remote.apply_profile(PROFILE_PATH, progress_callback=progress_callback)
[...]
Example: Apply remote XBee profile |
---|
The XBee Python Library includes a sample application that displays how to apply an XBee profile to a remote device. It can be located in the following path: examples/profile/ApplyXBeeProfileRemoteSample/ApplyXBeeProfileRemoteSample.py |