The IAP Load do Action supports loading data to edge devices and edge servers.  This can be used to update and upgrade executable firmware images, but can also be used for applications beyond firmware upgrades. For example, the service can transfer and install language packs for localization, additional software components, software licenses, or supplementary data such as device interfaces or device resource files.

Transferring “an image” through IAP has two steps: first, a privileged operator points the CMS to an IAP Image file, typically referring to this file through their local file system. This is known as the outer image file.

For a description of all Load Do action properties, see Load Action and Manifest Properties.

Outer Image File

The outer image file is a ZIP archive. There is no requirement to use a specific file extension, however, we recommend using the .glpo file extension for the image file.  The outer image file contains a manifest. The manifest contains information about the image to be loaded, which is called the inner image file. The outer image file contains either the inner image file, or a reference to an external location where the inner image file is located, using HTTP or HTTPS (a URI with http or https protocol identifiers).

In special cases, local references with a file protocol identifier are permitted. An iapmq pseudo-protocol to reference a binary file hosted within the IAP/MQ message broker is also permitted, subject to image size constraints.

Outer image files typically contain the inner image file when the inner image is small in size, as might be the case with small language packages, a device interface, or resource files. For larger images, especially those for a complex edge server, the outer image file typically includes a reference to the location of the inner image file. This avoids complications that can arise when using a USB memory device, or attempting to send large images by email.

Load Procedure

The CMS reads the manifest in the outer image file and constructs an IAP load action request. When the inner image is embedded within the outer image, the CMS hosts the inner image in a suitable location and computes the HTTP or HTTPS download URL and access credentials. When the inner image is not embedded within the outer image, the CMS takes the inner image URL and access credentials from the manifest.

Load a Single Edge Device

To load a single edge device, publish a load action object to the edge device’s do topic at:

Load Multiple Edge Devices

To load multiple edge devices, publish a load action object to a group’s do topic at:

The group can contain anything (such as devices, interface blocks, other groups, etc), as long as the group members are compatible in terms of the actions you plan to invoke on the group, or the assignments you plan to make to the group.

All the targets use the same image. In the event of a firmware load, all targets must therefore be firmware image compatible. The edge processor is responsible for detecting and reporting violations of this requirement.

 Load Many Edge Devices

To load many edge devices, publish a load action object to the edge server's do topic at:

For the load action arguments, use method = “native” or "hybrid" (to distinguish from loading the edge server itself), and protocol = "edge_protocol_ID" (such as "lon" to direct the load action to the appropriate edge processor).

Load an Edge Server

This topic is used to load images that are not loaded to a single device or a single group. Images loaded onto this endpoint can affect the edge server firmware, but can also target other destinations ("bulk load"), install resources with the "setup" method (described in the method argument in the Load Action and Manifest Properties table), etc. The supplier of the image needs to provide appropriate instructions through the image manifest.  

Publish a load action object to the edge server's do topic at:

For example, company A might release an IOX firmware upgrade. They would notify their customers about the availability of that upgrade, and include instructions on how to load it. These instructions could be "locate the IOX system device and use the CMS to load the upgrade to that device." Another company might release a new resources package with instructions to "load this to your edge server."

Schedule a Load

To schedule a load for a specific time, define a load job and a schedule to trigger it. Note this is different from the switchover time, optionally specified with the load action. Switchover controls the time when the new image is to be activated. The time when the load action is issued, perhaps with a scheduled IAP job, controls when the load action transfers, validates, and prepares the image in readiness for switchover.

The Load Object

The load object does not contain the image data. Instead, it informs the edge server of the image's location, which is provided as a WGET-compatible HTTP or HTTPS URL.  Local references using the file protocol identifier, or IAP/MQ binary channel references using the iapmq pseudo-protocol are permitted where appropriate. This method reduces the burden on participating message brokers and avoids transport failure caused by brokers which might limit the message size.

Binary images less than 64 KB can also be published into the IAP/MQ binary channel (described in Binary Channel). To reference such an image, the URL takes the form: iapmq://topic.  For example, a binary image published at glp/0/{SID}/bin/{Handle}/x/y/z is referenced with URL iapmq://glp/0/{SID}/bin/{Handle}/x/y/z .

The URL provided with the load object points to a IAP inner image. The load object itself forwards most aspects from the outer image’s manifest to the target.  The edge server does not have to use WGET, but the URL and data must use a format compatible with WGET, except for the iapmq URL, which references a retained item within the IAP/MQ binary channel.  Images transferred through the IAP/MQ binary channel are automatically and always removed after retrieval.

HTTP basic authentication is supported with optional user and password arguments.

Inner Image File Example

IAP supports several methods of handling inner image files (native, hybrid, setup, and system) as described under method in the Load Action and Manifest Properties table. 

Typically the inner image is a native image for the target, such as a .bin file for a TOP900, or a .ndl or .apb file for a CLP 3000, or it is a ZIP archive. The archive can be protected with a ZIP password.

The inner image integrity can be checked with an MD5, SHA256, or SHA512 checksum. This is optional, but recommended unless the image itself includes a way to verify its integrity. The checksum is provided with the manifest, which is part of the outer image file.

The manifest is a text file named "manifest" (no period or file extension) that is provided with the outer image.  The manifest contains a JSON object that provides meta data about the inner image, and is not part of the inner image.  For example:

See the Load Action and Manifest Properties table for a description of the contents of the manifest.