Load Action and Manifest Properties

The load action and manifest support a number of properties. Some properties are used exclusively by one, and some are supported by both. The following table describes the properties, and indicates whether they are supported in the Load Action, the Manifest, or both:

Property

Load Action or         
Manifest Property   

Type

Description

version

Manifest Property

string

(Optional) version provides version information about this image. We recommended using this field. The CMS can display this information when asking the user for approval to proceed with the load process.

issuer

Manifest Property

string

(Optional) issuer provides the publisher's identity. We recommended using this field. The CMS can display this information when asking the user for approval to proceed with the load process.

description

Manifest Property

string

(Optional) description provides a brief description of the image, its contents, and purpose. We recommended using this field. The CMS can display this information when asking the user for approval to proceed with the load process.

readme

Manifest Property

string

(Optional) readme provides information about this image. We recommended using this field. The CMS can display this information when asking the user for approval to proceed with the load process. readme is a link to a more detailed document or page.

image

Manifest Property

string

(Required) The image property provides the name of a file, such as "top900_v12_2.bin". If the filename is found within the outer IAP image archive, then that archive member is the image. If that filename is not found, it is assumed to be a reference to a remote image, such as an HTTPS link.

Example: top900_v12_2.bin

user

Both

string

(Optional) user provides optional credentials for fetching an image using HTTP BasicAuth.

passwd

Both

string

(Optional) passwd provides optional credentials for fetching such an image using HTTP BasicAuth.

url

Load Action Property

string

(Required) WGET-compatible HTTP/HTTPS URL to the image that is to be loaded onto the target. The iapmq pseudo-protocol is permitted for certain images

The image URL must lead to the image file itself. It must not lead to a download page or to a redirecting link, such as those provided as "download link" with many popular file sharing services. You need a direct HTTP reference to the file. WGET of this URL must produce the image file.

See also the information under The Load Object.

Example: "http://www.acme.com/downloads/sc/321.zip"

imgpwd

Both

string

(Optional) Image password, used to decompress the image (from a ZIP archive) retrieved from url.

integrity

Both

string

(Optional) Specifies the ASCII-encoded image checksum algorithm used to ensure image integrity. It can be either null, MD5, SHA256, SHA512.

method

Both

string

(Required) Image application method. method informs the edge server how to handle the loaded image. The standard choices are native, hybrid, setup, and system. No standard method identifier contains a period.

Specific edge servers may support non-standard load methods. These use identifiers containing at least one period, such as “iox.” or “iox.ble."

native	Indicates a native image such as a Lumewave TOP900.bin file, or a .APB or .NDL file used for loading a LonWorks device. The edge server is expected to have built-in knowledge on how to handle those image types. A native image can also be a ZIP archive containing the true native image. This is used with the hybrid load method, described below, to preserve the native name of the native image file and extension. When a native inner image is a valid ZIP archive, and contains exactly one file, that file is used as the actual inner image. When the native inner image is not a valid ZIP archive, or contains more than one file (or no file at all), the ZIP archive itself is used as the actual inner image.
hybrid	Provides a way of combining multiple inner images with one load. Each embedded image has the image format appropriate for its load method, and is named after its load method, followed by a period and a positive decimal sequence number. For example, one hybrid image can contain a “setup.1” image for use with the setup method, and a “native.2” image for use with the native method. The sequence number determines the order in which these loads occur. The sequence numbers do not need to be continuous or start with a particular value, as long as they can be unambiguously ordered according to their numerical value. For example, hybrid image 1 with “setup.10” and “native.100” is applied in the same way as “setup.1” and “native.2” or “setup.1” and “native.3”. A hybrid image can contain any number of system, setup, native, and hybrid images, as long as all these images apply to the same do action endpoint within IAP/MQ. For example, a hybrid image can contain setup.1 to install new device resources, a native.2 to load new edge device firmware, and native.3 to load new edge device application code that depends on that new firmware. However, the hybrid method cannot be used to deliver three different native images for three different edge device types. Note: Not all implementations support all combinations. For example, system within hybrid images is not supported.
setup	Indicates that the image is a ZIP archive, containing a script called setup at its root. The setup script is not required if the image contains nothing but a collection of recognized resources. These are: Modbus interface files LonWorks interface files (.XIF) Device resource files in xml format (DRF/xml) Application meta data files (.AMD) Binary device resource files (DRF/bin) will be supported after the beta release. Specific implementations define a generic default setup script which is used unless a specific setup script is provided. The load action fails if that generic script encounters data that it cannot support, such as an unsupported file type or folder layout. Once the edge server has validated and extracted the image into a temporary location, it invokes the script, which takes care of installing the image content. For setup images that do not contain a setup script, a generic setup script is invoked. That script identifies the files contained within the image and takes the necessary actions. The setup method is usually used to install, update, or remove data files or app. The setup script is typically a Bash script, but could also be any other executable, including binaries or scripts using a different language such as Python, Perl, or Node.js, provided the script begins with the appropriate shebang. The edge server invokes this script directly and as root. The setup script provides error diagnostics on standard error console output, and returns a non-zero result in the event of an error. A result code of zero indicates success.
system	Is treated like setup with additional lead-in and lead-out steps, subject to the system’s specific requirements. The system method is used to upgrade the SmartServer IoT system, and typically involves a reboot and confirmation of success after the system is rebooted, or a rollback to the previous version if the upgrade failed. Note: Not all implementations support all combinations. For example, system within hybrid images is not supported.

protocol

Both

string

(Optional) Edge protocol selection. protocol is required to support bulk load requests that upgrade every device within the segment for the selected protocol and type. The manifest should always define the protocol, if the manifest relates to a specific edge protocol. See also Load Many Edge Devices.

Example: "cm"

switchover

Load Action Property

string

(Optional) Timestamp (in UTC or local time) to indicate when the switchover will occur. When not specified, or specified in the past, targets switch to the new image immediately. 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.

Note that some images may not be loaded for execution, such as supplementary data for language packs. For those, “switchover” means “activation.”

Timed switchover is the responsibility of the edge processor for images that apply to edge devices, and is the responsibility of the edge server for images that apply to the edge server.

See IAP/MQ Fundamentals for the timestamp format.

Example: ‘2016-09-28 12:00:00.000 BST’

type

Both

string

(Optional) type contains a regular expression in POSIX BRE syntax. When provided, it must match the type reported in a device’s status object.

For example, one type of LonWorks devices might report type “8000010203040506”. The image manifest can be restricted to this type with a “^8000010203040506$” regular expression.

Because the type is a regular expression, a type of “^80000102030405” matches this application type accepting all model numbers (the last pair of hex digits).

For images that apply to a specific edge server, set the image type to match the model property defined in About.

The CMS can check this property to prevent an invalid load attempt. The edge server is responsible to avoid loading incompatible images, to the extent possible, subject to the data provided with the IAP load action and subject to edge protocol properties.

flags

Both

string

(Optional) A set of flags. Each flag is a key whose value is any valid JSON value. No flags are defined at this time, but specific applications or protocol engines can declare custom flags within the manifest. Flags are set to null when no flag is required.

Example:
One protocol processor could describe additional parameters to retrieve the image from the given URL:

flags: {
     myProtocol.proxy: “123.213.132.231:321”,                    
}

checksum

Both

string

Hex-encoded reference checksum over the entire image (the data retrieved from url).

Example: ‘708662ee8cc7b7129bdd75b731d61a784608a8067cfb7d26c1c15d4d8dc2863a’

response

Load Action Property

string

Optional response request. Errors are reported when a load operation fails, but not all successful load operations yield a deterministic response to determine when the operation completed successfully.

Clients can set the response argument to an event channel topic of their choice, such as:

glp/0/{SID}/ev/=cms/response/load

Note: The = sign is used to indicate that the topic is addressing a service, instead of an object.

When a response is requested in this manner, a load completion object (properties shown below) is published when the image is successfully retrieved, validated, and prepared.

For load methods setup and system, the image has been successfully installed at that time.
For the hybrid method, all steps of the hybrid image have been successfully completed.
For the native method, the image has been successfully handed over to the edge processor.

Load Completion Object Properties

The load completion object with the standard IAP/MQ channel-specific publication properties if the response belongs to a recognized channel (event channel: QoS=1, retain=false, feedback channel: QoS=1, retain=true), otherwise with QoS=1, retain=false.

Property	Type	Description
url	string	As received with the load action request.
method	string	As received with the load action request.
protocol	string	As received with the load action request.
type	string	As received with the load action request.
flags	string	As received with the load action request.
error	object	Is null to indicate success (no error), or contains an IAP error event object. See Event Object Properties table in Events.