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.

   Make sure the source and the destination gateways are of the same platform type to ensure the SUP files are compatible.

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

2. Right click on the source gateway.
   The shortcut menu appears.
   
3. Click Prepare Update Package.
   As a part of the Prepare Update Package wizard, Local directory screen appears.
4. Choose the Local directory for packaging.
   

   The local directory is the folder where all files that will be included in the software update package (SUP) are placed. Removing unused files from the local directory will reduce the size of the SUP file, which is important for the data transmission cost and transfer time when connected using a cellular connection.

5. Click Next.
   The Staging Files screen appears.
6. 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.
   
   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 click Get.
   A message asks you to confirm the file(s) to get.
   
4. Click Yes.
   A message appears with the info that one or more files were saved to the local directory folder specified in Local directory
   
5. Click OK.
   
6. Click Refresh to update the list of files.
7. Click Next.
   The Create screen appears.
8. Do one of the following on the Create screen.
   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.
9. Click Next.
   The Configuration Image screen appears.
10. Select to export the configuration database in the local package directory.
    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 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 click OK.
       A message will be displayed to indicate the database is successfully exported.
       
    3. Click OK.
11. Click Next.
    The Action screen appears.
12. Choose the actions to perform upon package installation.
    The Actions screen allows you to add actions (similar to commands) that will be executed on the gateway.
    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.
    To add an action:
    
    1. From the bottom of the Actions screen, click 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 click 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.
       
13. After you have added and ordered the actions you want in the SUP, click Next.
    The Package Summary window appears.
14. Enter the package description.
    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. 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.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.
15. To create the SUP output file, click Next.
    The Processing Update Package screen appears. 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.
16. Click OK, and then click 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.
    If you are unable to resolve your errors all your files will be retained in the local directory specified in Local directory.

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.