update: firmware: profile: support to update multiple nodes at once

'XBeeNetwork' class includes a new method 'update_nodes()' to update several
nodes at once (firmware or profile).
It requires a list of update tasks with the process details (node, files,
timeout) and also an optional progress callback to get information about each
single update process, similar to the callbacks in 'update_firmware()' and
'apply_profile()' methods of 'XBeeDevice' and 'RemoteXBeeDevice'.

This commit adds the possibility of registering a new callback in the network
using 'add_update_progress_callback()' method. This callback is executed every
time the status of any update process (firmware or profile) changes.
It indicates the XBee being updated, the tasks in process, and its current
percentage.

The corresponding 'del_update_progress_callback()' is also implemented.

https://onedigi.atlassian.net/browse/DAL-5285

Signed-off-by: Tatiana Leon <Tatiana.Leon@digi.com>

Author: tatianaleon

CHANGELOG.rst

@@ -19,10 +19,13 @@ v1.4.1 - XX/XX/2021
 
   * Do not work with network if the XBee does not support it (XBPL-374)
   * Fix creation of IMEI when reading cellular information.
+* Support to update a bunch of nodes at the same time (DAL-5285)
 * Documentation:
 
   * Add info about the ``force_settings`` parameter of ``open`` method (#241)
   * Add missing ``exportutils`` module to documentation.
+* Set exclusive access mode to the XBee serial port (#222, #252)
+* Do not stop frames reader if a serial buffer empty exception occurs (#222, #252)
 * Do not use 'os.path.join()' for relative paths of zip entries (#247)
 * Fix bad conditions when checking for a received packet (#242)
 * Fix attribute name in find neighbors debug message (#122)

digi/xbee/devices.py

@@ -58,7 +58,7 @@
 from digi.xbee.io import IOSample, IOMode
 from digi.xbee.reader import PacketListener, PacketReceived, DeviceDiscovered, \
     DiscoveryProcessFinished, NetworkModified, RouteReceived, InitDiscoveryScan, \
-    EndDiscoveryScan, XBeeEvent
+    EndDiscoveryScan, XBeeEvent, NetworkUpdateProgress
 from digi.xbee.serial import FlowControl
 from digi.xbee.serial import XBeeSerialPort
 
@@ -146,6 +146,7 @@ def __init__(self, local_xbee_device=None, serial_port=None,
         self._reachable = True
 
         self._initializing = False
+        self._active_update_type = None
 
         self.__generic_lock = threading.Lock()
 
@@ -8607,6 +8608,7 @@ def __init__(self, xbee_device):
         self._network_modified = NetworkModified()
         self._device_discovered = DeviceDiscovered()
         self.__device_discovery_finished = DiscoveryProcessFinished()
+        self.__network_update_progress = NetworkUpdateProgress()
         self.__discovery_thread = None
         self.__sought_device_id = None
         self.__discovered_device = None
@@ -8908,6 +8910,44 @@ def export(self, dir_path=None, name=None, desc=None):
 
         return 0, str(file)
 
+    def update_nodes(self, task_list):
+        """
+        Performs the provided update tasks. It blocks until all tasks finish.
+
+        Params:
+            task_list (List or tuple): List of update tasks
+                (:class:`.FwUpdateTask` or :class:`.ProfileUpdateTask`)
+
+        Returns:
+            Dictionary: Uses the 64-bit address of the XBee as key and, as
+                value, a Tuple with the XBee (:class:`.AbstractXBeeDevice`) and
+                an :class:`.XBeeException` if the process failed for that node
+                (`None` if it successes)
+        """
+        from digi.xbee.firmware import FwUpdateTask
+        from digi.xbee.profile import ProfileUpdateTask
+
+        if not task_list:
+            return {}
+
+        result = {}
+        for task in task_list:
+            try:
+                if isinstance(task, FwUpdateTask):
+                    task.xbee.update_firmware(task.xml_path,
+                                              xbee_firmware_file=task.fw_path,
+                                              bootloader_firmware_file=task.bl_path,
+                                              timeout=task.timeout,
+                                              progress_callback=task.callback)
+                elif isinstance(task, ProfileUpdateTask):
+                    task.xbee.apply_profile(task.profile_path, timeout=task.timeout,
+                                            progress_callback=task.callback)
+                result.update({str(task.xbee.get_64bit_addr()): (task.xbee, None)})
+            except XBeeException as exc:
+                result.update({str(task.xbee.get_64bit_addr()): (task.xbee, exc)})
+
+        return result
+
     def add_network_modified_callback(self, callback):
         """
         Adds a callback for the event :class:`.NetworkModified`.
@@ -9028,6 +9068,20 @@ def __received_packet_from_cb(self, packet, remote):
 
         cbs(packet, remote)
 
+    def add_update_progress_callback(self, callback):
+        """
+        Adds a callback for the event :class:`.NetworkUpdateProgress`.
+
+        Args:
+            callback (Function): The callback. Receives three arguments.
+                * The XBee being updated.
+                * An :class:`.UpdateProgressStatus` with the current status.
+
+        .. seealso::
+           | :meth:`.XBeeNetwork.del_update_progress_callback`
+        """
+        self.__network_update_progress += callback
+
     def del_network_modified_callback(self, callback):
         """
         Deletes a callback for the callback list of :class:`.NetworkModified`.
@@ -9128,6 +9182,29 @@ def del_packet_received_from_callback(self, node, callb=None):
             self._local_xbee._packet_listener.del_packet_received_from_callback(
                 self.__received_packet_from_cb)
 
+    def del_update_progress_callback(self, callback):
+        """
+        Deletes a callback for the callback list of :class:`.NetworkUpdateProgress`.
+
+        Args:
+            callback (Function): The callback to delete.
+
+        .. seealso::
+           | :meth:`.XBeeNetwork.add_update_progress_callback`
+        """
+        if callback in self.__network_update_progress:
+            self.__network_update_progress -= callback
+
+    def get_update_progress_callbacks(self):
+        """
+        Returns the list of registered callbacks for update progress.
+        This is only for internal use.
+
+        Returns:
+            List: List of :class:`.NetworkUpdateProgress` events.
+        """
+        return self.__network_update_progress
+
     def clear(self):
         """
         Removes all remote XBee nodes from the network.

digi/xbee/filesystem.py

@@ -3287,7 +3287,7 @@ def get_file_hash(self, file_path):
 
 def update_remote_filesystem_image(remote_device, ota_filesystem_file,
                                    max_block_size=0, timeout=None,
-                                   progress_callback=None, _prepare=True):
+                                   progress_callback=None):
     """
     Performs a remote filesystem update operation in the given target.
 
@@ -3320,7 +3320,7 @@ def update_remote_filesystem_image(remote_device, ota_filesystem_file,
     try:
         update_remote_filesystem(
             remote_device, ota_filesystem_file, max_block_size=max_block_size,
-            timeout=timeout, progress_callback=progress_callback, _prepare=_prepare)
+            timeout=timeout, progress_callback=progress_callback)
     except FirmwareUpdateException as exc:
         _log.error("ERROR: %s", str(exc))
         raise FileSystemException(str(exc)) from None