HOW TO: Create a Scheduled Task to Update the OS Firmware of an XBee Gateway ZB or ConnectPort X2e for Smart Energy on Device Cloud

Introduction:

This article describes the creation of a Digi Remote Manager Scheduled Task which can be used to update the OS Firmware of your XBee Gateway ZB and/or ConnectPort X2e for Smart Energy gateway inventory.

A Scheduled Task is a powerful tool which can be accessed at the Device Management - Schedules tab, when logged-in to your Digi Remote Manager Cloud account. A Scheduled Task can be used for many things, but in this article, we'll be using a Scheduled Task which has already been created for you.  This task is specifically for the purpose of updating the OS Firmware of multiple ConnectPort X2e for Smart Energy or XBee Gateway ZB gateways under your account.  Scheduled Tasks can can also be used to schedule work to be performed on Gateways which are currently in a “Disconnected” state (as long as they connect to Device Cloud within a week of the task being started).

Important Note:

An OS firmware update is necessary for all XBee Gateway ZB and ConnectPort X2e for Smart Energy gateways with an OS firmware version number lower than version 3.2.22.x, to prevent the possibility of the gateway being Factory Defaulted to "Etherios.com" related settings.  The login.etherios.com and time.etherios.com addresses will no longer be capable of connecting to Digi Remote Manager (or Device Cloud) after June 30, 2016.  This Scheduled Task can be used to update the firmware of your Gateways, provided you have a firmware file to update with.

Reference Article:
Digi International Device Cloud/Remote Manager Notice: November 23, 2015 - End use of Etherios domain names in device configurations
 

Requirements:

• A Device Cloud account (Developer or a Subscribed Edition) is required to run a Scheduled Task.  Also, any gateways which need to be updated by the Scheduled Task will need to be under that account, and will need to have attained a "Connected" state within a week of your Scheduled Task being launched.
   
• Click here to download the zip file containing the Update-Linux-OSFW.xml scheduled task.
   
• The correct OS firmware file for your Gateway:
  
  Please see the following links to download the correct OS Firmware image below for your standard Digi XBee Gateway ZB or ConnectPort X2e for Smart Energy gateway:
  
  XBee Gateway ZB Firmware page - Ethernet, Eth/Wifi, and Cellular models
  ConnectPort X2e SE Firmware page (obsolete) - Ethernet, Eth/Wifi, and Cellular models
  
  Note: This Scheduled Task can be used to update the OS Firmware of custom XBee Gateway ZB and ConnectPort X2e SE gateways, provided the OS Firmware image is obtained from the company which installed the custom model. Please see the Company which installed your Gateway for further information.

Update Task Instructions

When first creating a Scheduled Task, we recommend that you initially try it out on a single device, just to get a feel for the Scheduled Task and to understand how it works.  By starting with a single device, you can better understand if any bugs need to be worked out prior to targetting a larger number of devices, or if you want to write the task differently.  In general, there is no specific order of events one must follow when creating a task, as long as the XML code of each individual element is complete.  There are ways which might be more efficient then others however, so trying different things can be a useful tool for learning.

Once a script performs to your liking, it can be run on many devices simultaneously. This can be done by targeting more than one device through use of a Tag or Group (found under Device Management --- Devices --- Groups subtab/"Add A Group" dropdown) or by selecting more than one Device ID Target from the Devices area. By effectively using Tags and/or Groups, a strategy can be developed to update as many or as few devices under your account as you choose.
 

Preface to OS Firmware Update Task guidance: 

Scheduled Tasks are saved with an .xml filename extension (in the following tutorial, the file you downloaded within the zip file under Requirements is already created for you, and is called Update-Linux-OSFW.xml).

1. Prior to running the procedure below, Update-Linux-OSFW.xml must be loaded into a standard text or XML editor.
2. Within the editor, on line 38 of Update-Linux-OSFW.xml, replace the text [YOUR FIRMWARE FILENAME GOES HERE] with the filename of the .bin firmware image for your particular Gateway (Example:  82003150_C.bin) and save your file.  This is a case sensitive entry, and if the filename is entered wrong, your Gateway OS Firmware Update Scheduled Task will fail.

Device Cloud/Remote Management Settings Update Task tutorial:

1. Login to your Device Cloud or Remote Manager account
2. Go to the Data Services --> Data Files area and open the my_tasks folder by double-clicking the folder:
   
   
    
3. Create a directory under my_tasks, called Update-Linux-OSFW:
   
    
4. Upload the Update-Linux-OSFW.xml file to your my_tasks folder:
   
   
   
    
5. Double-click on the Update-Linux-OSFW folder you created in Step 2 to open the folder.
    
6. Upload the the appropriate OS Firmware file for your XBee Gateway ZB or ConnectPort X2e for Smart Energy gateway (See the Requirements section above for file information):
   
   
   
   
    
7. Go to the Device Management--> Schedules tab and press the New Schedule button:
   
   
    
8. Select the My Tasks tab on the left, and select the Update-Linux-OSFW task listed (if you entered the filename of your firmware file correctly earlier, the task should load on the right as in the example):
   
   
    
9. Select the Schedule >> button on the bottom right corner, to be taken to the second page of the Scheduler:
   
   
    
10. At the second Scheduler page, various options are listed to run the Scheduled Task Immediately or to schedule for a time/date in the Future. You'll also need to select the Target(s) to run your Task on. You can select individual devices, by Group or by Tag:
    
    
     

You should see the message Operation Submitted Successfully if your new task was successfully scheduled to run on the devices which you selected.

Note on Disconnected Devices:

If scheduling a Task on a device, the Scheduled Task will time out (fail) after one week if the targetted Gateway(s) never attain a "Connected" state with Device Cloud to receive the OS Firmware update launched by the Task.

Once the Update Task has been tested and verified to work, it can be used to easily update multiple batches of devices via Digi Device Cloud.

Executing DBL-OS-update.xml on Gateways from Device Management --- Devices

1. Log into your Device Cloud account
2. Go to Device Management -> Devices
3. Highlight, then right-click on any Gateway(s) you want to update
4. Go to More -> Tasks -> DBL-OS-update.xml
5. When prompted at the Scheduled Operations popup, click Yes.

How to check on Scheduled tasks which have run

1. Browse to Device Management -> Operations
2. Look for listed operations which are called "DBL OS Update":
   
   
    
3. Double click on an operation to observe the details of the individual steps within the Scheduled Task
   
   
    
4. Verify whether the Task was successful or failed.
   
   
    

Return to Device Management -- Devices to view the new Firmware version listed for your Gateway, and Gateway OS Update complete Description which the Scheduled Task writes to your Gateway:



The Description field of your Gateway is useful as an aid for you to see which Gateways under your inventory have been updated. You can edit this field to write a different "Success" message in the Description as preferred, in the same way you edited the Scheduled Task earlier to include the correct OS Firmware filename for your Gateways.
 

Keep in mind that a Scheduled Task operation can only have complete success, if all Gateway target(s) selected were successful in doing so. If a status of Failed is listed for your operation, it means that one of the steps which were part of your Scheduled Task failed, or that any of the device targets selected for the task weren't successful at connecting and receiving the update after a week (even though other device targets may have succeeded).

An operation with a status of Successful means that all commands within the Scheduled Task ran on all the device targets selected for update by the Task completed successfully, i.e. complete success for all devices, not partial.

Additional Reading:

Remote Manager (Device Cloud) Documentation page – Tech Support page for Remote Manager documentation

Remote Manager (Device Cloud) User Guides – see Operations and Schedules sections

Device Cloud Programming Guide – see Scheduled Operations
HOW TO: Example for Configuring a Device Cloud Task to Set a Gateway XBee PAN ID



HOW TO: Remove a Task listed under the My Tasks tab when creating a new Device Cloud Schedule