Page tree
Skip to end of metadata
Go to start of metadata

The software update package (SUP) feature provides a mechanism for updating software and files and for performing various update tasks on your gateways.

This includes updates to the product software and device drivers, and updates to your applications (triggers, devices, transports, etc.).

The creation of software update packages is a developer task and requires knowledge of the IoT solution and the applications that are defined on the gateways.

The contents of your software update packages depends on how you decide to manage your IoT solution, including the product software and the applications.
A software update package can be as simple as updating 1 file on the gateways to as complex as updating the product software, similar to doing a product Update Firmware function, and updating your applications all in one package.

Software update package management tasks

The tasks associated with software update packages will be performed in the following sequence:

  1. Creating a software update package using the Workbench.
    The software update package creation task and the reference information for the software update package library of actions are described on this page and the Software update package actions pages.

  2. Uploading the software update package using the Management Portal -> Developer -> Files feature.

  3. Deploying the software update package from the Management Portal -> Campaigns feature.

  4. Optionally, downloading a copy of the software update package from the Management Portal-> Developer -> Files feature.

Creating a software update package using the Workbench

  1. From the Workbench left pane, select the gateway you want to be the source of the software update package creation.

    Software Update Package source gateway

    It is important that the source gateway be the same platform type as the gateways that will be the destination of the SUP file, when the SUP has platform specific files or tasks.

    For example, the Write Core DB and Write Master DB actions will each update a database on the destination gateway. Those databases may have platform specific content.

  2. Right click to display its pop-up menu, and then select Prepare Update Package.
    The Prepare Update Package wizard appears with a set of steps to guide you through the software update package creation.

  3. Follow the directions for each step, and then select Next to proceed to the next step. At any time, you can go back to the previous step, using the Previous button.

Step 1: Local directory

The Local directory screen provides the first step. The local directory is the folder where all files that are to be included in the software update package (SUP) are placed.

All files in the selected folder will be included in the SUP. This enables you to set up a folder once and then, if you wish, you can modify and recreate the SUP in the future and all content is retained.

Local directory contents

All of the files in the specified local directory will be included in the SUP. Removing unused files from the local directory will reduce the size of the SUP file, which may be important for the data transmission cost and transfer time when connected using a cellular connection.

Step 2: Create

The Create screen provides two options:

  1. Select Create using selected directory to create a new SUP file. You will be asked for a file name later in the set of creation steps.

  2. Select Create from existing package to create a SUP using the contents of an existing SUP.

    • The contents of the existing SUP will be used to configure the new SUP. This will include actions and package names (Step 5: Actions and Step 6: Package Summary).
    • Select the Extract files from package option to extract the files from the SUP and write them to the local folder specified in the Step 1: Local directory.

Note: In either case, review the contents of the local directory and remove any unused files to reduce the size of the SUP file.

The folder name and its location will appear on the status bar at the bottom of the window for the remainder of the create process.

Step 3: Staging Files

The Staging Files screen allows you to select any directories (and their sub-directories and files) or individual files in the gateway's Staging Browser area that you want to include in the SUP.

  1. Select the files you want to copy.

  2. If needed, select the Copy to staging subdirectory of local directory checkbox:
    • If the Copy to staging subdirectory of local directory parameter is selected, the selected directories and files will maintain the staging directory in their path.
      This maintaining of the staging directory path needs to be understood when using the Add Directory from Package action or Add Directory from Package to Staging action in the SUP.
    • If the Copy to staging subdirectory of local directory parameter is not selected, the selected directories and files will not maintain the staging directory in their path.
      This is the default option and will be used in most cases.

  3. After selecting the directories or files select Get.

  4. A message asks you to confirm the file(s) to get. Select Yes.

  5. Another message will tell you that one or more files were saved to the local directory folder specified in Step 1: Local directory. Select OK.

  6. Select Refresh to update the list of files.

Step 4: Configuration Image

The Configuration Image screen allows you export the configuration (Core) database from the source gateway and use it with the Write Core DB action or Write Master DB actions.
For more information, see: Database Deployment.

The configuration database includes all defined items on the gateway such as projects and triggers, transports, transport maps, and devices.

The configuration database will be exported into the folder you specified in Step 1: Local directory.

This step is not required if you do not wish to include a configuration database and the Write Core DB action or the Write Master DB action in the SUP.

  1. Select Export configuration database.
    The Export window appears.

  2. Accept the default name or enter a new name for the file, and then select OK.

  3. A message will be displayed to indicate the database was successfully exported, select OK.

Step 5: Actions

The Actions screen allows you to add actions (similar to commands) that will be executed on the gateway.

Software update package actions

The SUP actions you define may have operating system or deviceWISE product specific files or parameters.

The design of the SUP file and its use on multiple gateways must take into account the operating system and deviceWISE product specific characteristics of the gateways.

You may need to define multiple SUP files, with their actions and parameters to support your multiple gateway product types.


To add an action:

  1. From the bottom of the Actions screen, select Add.  The New Action window appears.

    The New Action window lists the available actions. Actions can be added, removed, or reordered by using the buttons at the bottom of the Actions screen.

  2. Select an action, and then select Add.

    The Actions section accommodates the actions you added. The Details pane is where the specifics of the currently selected action are defined.

    The list of actions and their parameters can be found on the Software update package actions page.

    It is recommended that you add the Stop Runtime action as the first action and the Start Runtime action as the final action for many SUPs, based on the actions included. This is not required, but many changes (code, properties files, Master DB or Core DB) will not take affect without restarting the deviceWISE runtime on the gateway.

  3. After you have added and ordered the actions you want in the SUP, select Next.
    The Package Summary window appears.

Step 6: Package Summary

The Package Summary screen allows you to specify the Name of the SUP file, an identifying Version for the package, and the name of the SUP Output file.

The lower portion of the Package Summary screen displays the files and actions that are included in the SUP.

It is a good practice to update (increment) the Version number with each modification you make to the SUP.

SUP output file location

The SUP output file can be specified to be in any directory on the Workbench computer, but you should not chose the same directory being used as the Local Directory specified in step 1.

The local directory should only contain source files that will be included in generated SUP file. Since you can create new SUP files and reuse the local directory, care should be taken to keep extraneous files out of your SUP local directory.

To create the SUP output file, select Next. The Processing Update Package screen appears.

Step 7: Processing Update Package

The Processing Update Package screen shows the SUP being created.

The details of the creation are listed under the Packaging build output section.

A message appears when the SUP output file is successfully created, select OK, and then select Done.
The file is located in the folder you specified in the Output file parameter.

If any errors occur, a message will appear and you will be able to return to the previous window to correct the errors.
Note if you are unable to resolve your errors all your files will be retained in the local directory specified in Step 1: Local directory.

Uploading and deploying the software update package

After you have successfully created a software update package, it can be uploaded to the IoT Portal and deployed to your gateways.

For information on these topics, see Software update package processing.


  • No labels