This document describes the basic principles in using ZIP Packages for downloading content to OSGi devices in ZIP format.

Overview

ZIP Packages are ZIP-based archives that wrap content to be installed on an OSGi-enabled devices. The ZIP Package Agent of RM allows installing and uninstalling such packages on OSGi devices from the backend.
Installation implies downloading the package, extracting its content to a specified directory and deleting the temporary file from the file system. Upon installation the content of a ZIP package must be always extracted to a new directory.
In addition, in a package you can place install script and uninstall script executed respectively upon package installation and uninstallation.
By default, the ZIP package is downloaded to to the "/tmp" directory. To change the default temporary download directory, on the device set the zip.tmp.dir system property in the file <gateway_software_runtime_home>/osgi/bin/vms/<vm>/default.prs before installing the ZIP Package Agent.
To be able to install a ZIP Package, you need to import the corresponding ZIP package archive into the Software Repository. All packages with the same content ID (see "Properties") are treated as different editions of the same package, and are displayed as children of this base package. Editions are associated with different package versions and/or can be suitable for different device platforms.
When a package is installed on a target device, RM allows you either to select the specific package edition, or only a generic package, in which case RM will automatically select for installation the highest package version, which matches best the device's platform capabilities.

Properties

A ZIP Package contains a number of properties specifying its name, version, vendor, etc. The properties should be placed in a text file called np-sr.properties in the main folder of the package and should be defined as key=value pairs.
The following properties are supported for ZIP Packages:

  • DisplayName – The name of the package.
  • Version – The version of the package
  • Vendor – The vendor of the package
  • ContentID – The content ID of the package uniquely identifying the content within the package
  • Architecture – The processor architecture the ZIP Package is built against
  • ScriptTimeout – The timeout in milliseconds to wait for the package install script to complete execution. After this timeout passes, the ZIP Package Agent returns an error and cleans the files extracted from the package. If the property is not specified, a default timeout of 5 minutes is used.
  • Description – Friendly description of the package


Version=1.0
Vendor=Vendor
ContentID=my.zip.id
DisplayName=Simple ZIP Package
Architecture=x86
Description=ZIP package which contains only a properties file.

Install and Uninstall Scripts

Windows OS
To execute a script at ZIP Package installation, it should be named install.bat and it should be configured with pkgzip.install.script property containing the file path to the install script.
To uninstall a script, it should be named uninstall.bat and be configured with pkgzip.uninstall.script property that contains the file path to the uninstall script.
Linux OS
If you want to execute a shell script, name it install.sh. Use pkgzip.install.script property that contains the file path to the install script.
Similarly, you can also use an uninstall script, executed when the package is removed from the device. It must be called uninstall.sh and configured with pkgzip.uninstall.script property that contains the file path to the uninstall script.

If the install script or the uninstall one are being executed for more than a certain timeout, the ZIP Package Agent generates an error. You can configure this timeout with the ScriptTimeout property of the package. 


If using relative paths in the scripts, pay attention to the "extract-to" directory you have specified at installation from the backend. 

Install the Agent on the OSGi Device Framework

To enable management of ZIP Packages on an OSGi-enabled device, you must provide the ZIP Package Agent on the OSGi device framework. You can do this as described below:

  • When registering a new OSGi device, in the Optional Administration Features dialog, enable the ZIP Package Management optional feature.
  • On an already registered OSGi device, deploy the ZIP Package Management Agent bundle (packages/osgidm/osgidm.os.package.zip.agent.jar). You can install the bundle in one of the following ways:
  • By reprovisioning the device and enabling the ZIP Package Management feature.
  • By installing explicitly the ZIP Package Agent bundle from the RM Software Repository with the "Smart Install" option turned on.
  • Manually by copying the bundle and the bundles it depends on to the device – the ZIP Package Agent bundle and the bundles it depends on are located in the packages/osgidm directory, and by installing it along with the Control Unit Admin (packages/system/cuadmin.jar) and Control Unit Management Agent (osgidm/osgidm.clientcu.agent.jar) on the OSGi framework.

Download ZIP Packages over HTTPS

ZIP Packages can be securely downloaded on the target device over HTTPS.
To turn on secure download:

  1. Configure the proper authentication certificate on RM and on the device. The certificate that RM will use to authenticate to the device with must participate in the "TLS Server" domain. On the device, configure the RM certificate as trusted according to the HTTPS client support of the underlying JVM.
  2. In the console go to the System Configuration dashboard view and select the Configurations tab. Locate the Gateway Software Download Configuration and set the HTTPS Download Mode to Yes and click the Save button.