The software update model defined in this clause is used to manage the software of a Device. This can include the installation of new software, the update of existing software, the update of a firmware and a limited backup and restore of parameters and firmware as far as it is required for the update. The specific steps to perform the actual installation are only known by the device. They are not exposed by this Information Model.

The use cases that were considered for this Information Model are described in 8.2. Several options that can be combined for a concrete SoftwareUpdateType instance are described in 8.3. Valid combinations of these options are defined in the profiles section. 8.3.5 describes how to implement a Software Update Client that has to deal with several options. The types for this model are formally defined in 8.4 and 8.4.12.

The software update model is used in several scenarios. The following subsections list common use cases that are considered by this model. There are also some use cases that that are not covered. A future version could possibly add features for them.

The model is intended to be applicable across devices with varying resources and constraints. This is achieved e.g. by various options for the server implementation (see 8.3.4).

Allow devices to be updated via Software Update Client software. To address the domain specific constraints this can be a domain-specific client software. (In the manufacturing domain a machine often necessitates to be stopped before the update, whereas in process domain e.g., a redundant device will be activated.) 8.3.5 describes the workflow of a Software Update Client.

Software update is applicable for any device or software component that is exposed in the Server AddressSpace. This can also represent other devices that are just connected to the device hosting the Server. This can be done using the AddIns described in 8.3.11.

When updating several connected devices in a machine or plant the devices possibly are first set into a special “state” where they wait for the start of the update and don’t start operating again. After that the updates can be installed in an order defined by the Client (e.g., sensors first, switches last). Finding the best sequence is task of the client implementation or the operator and not in scope of this specification.

The “state” is defined depending on the type of machine / plant. For factory automation this normally means that production and the software on the devices is stopped. For a sensor in process automation this could mean that a replacement value is configured in the controller for the value measured in the device. If a controller requires an update in process automation it often is the passive part of a redundant set of controllers.

It is also necessary that the Client considers the proper sequence when updating the devices. For example, if parts of the network become unreachable due to the update of an infrastructure device.

A server can support the prepare for update option (8.3.4.2) to enable this use case.

For some updates it is not necessary to stop the software. This could be the case if parts of a software are replaced that are currently not used or if new software is installed. Whether an update can be installed like this is only known by the device and depends on the concrete update file. To support this, the Client can read the UpdateBehavior (8.5.2) to determine if stopping is required.

In some cases, it is required to prepare the update and then plan the start for a later time or under some strategic conditions. In this case the software is transferred to the device first. Later (e.g., at the end of the shift or on the weekend) and under specific conditions (e.g. nothing to produce) the update Client can start the update. In this scenario the time and the conditions are known and checked by the update Client, not by the Server, so for the use of the software update options an established Client-Server connection is required. The scheduling is a task of the Client and not described in this specification.

It should be possible to distribute the software to several devices without actual installation. In this scenario a central tool can determine the required updates and distribute them to all devices. The actual installation can then be started later by a different Client. This is realized by separating the transfer (8.4.1.2) from the installation (8.3.4.6).

Depending on the device there should be several options to partition a software. For example, it should be possible to structure the firmware of a device in a way that each part can be updated individually. Additionally, software update should be applicable to the firmware of devices and to the software of components. This is realized with the AddIn model (8.3.11).

If a Software Package becomes very large and only parts of it can be replaced, the Server maintains the individual files of the Software Package independently. When all desired files are on the Server, the installation can be started for the set of files. Here the FileSystem option (8.3.4.5) can be used.

Especially for devices that are not easy to access for a manual reset or replacement, the update shall always result in a working OPC UA Client – Server connection. This requires an additional confirmation by the update Client, so that the Server can do an automatic rollback if the communication cannot be established again after a reboot. A Server can support this with the confirmation option (8.3.4.9).

Very constrained devices can lose parameters during the update. It is necessary that the update Client is aware of that and should be able to backup the parameters in advance. After the update – but before the device starts operating again – the parameters shall be restored. This can be supported using the Parameters object (8.3.4.8).

An update client selects the correct version of the Software Package to install. The rules behind this decision can be complex and can include e.g., dependency checks or a release process of the distributor and / or operator of the machine. The Server can expose information about the device (8.3.11) and information about the Current Version (8.4.3.2) which is then used by the Client to select an update.

Selecting the new version is done by the user with the help of the update client before transfer and installation. Therefore, it is not in scope of this specification.

Some devices can run several software applications. The Information Model should allow the Client to transfer and install additional software applications if the Server supports this. This can be done using the FileSystem based Loading (8.3.4.5) or the SoftwareFolderType (8.4.12).

An Update Client imports a software along with all metadata and all supporting files. These files can come from different vendors for different devices. For easier transport and handling, a single standardized container file is required.

The Software Update AddIn supports atomic transfer of a single file to the server. To keep the metadata together with the transferred file a standard container file format is required.Additionally, a server possibly wants to store multiple files (to prevent nesting ZIP in ZIP).

If a working device is used as the prototype for other devices the Software Package of an application or configuration can be uploaded. Therefore, an embedded device should be able to create a Software Package and upload it using the SoftwareUpdate AddIn. This package can also be used for backup.

An Update Client identifies Software Packages that are installable to a SoftwareUpdate AddIn found on the server. For example, getting suitable firmware packages from a repository for a device, which is identified by ManufacturerUri and ProductCode.

An Update Client checks the compatibility before transfer anything to a device. This includes selecting the proper version as a valid update.

An Update Client ensures that all dependent hardware / firmware / software components have suitable versions.

An Update Client presents additional files to the user. This can include release notes, license information, manuals.

An Update Client verifies the integrity and authenticity of the files within the Software Package.

In some plants it is required that only those Software Packages can be installed onto the devices that are tested and approved for use in that plant. In that cases the devices is configured to only accept Software Packages with a specific approval signature.

At system design a combination of several devices or several software instances on a single device or machine or UA Server is defined and released. Example: modular devices like PLC, IO Island or Machine. For that case it shall be possible to sign this combination and transfer all related files in a single container. A target shall be configurable to only accept such combinations with a specific valid signature.

If an OPC UA Server abstracts several devices that support the SoftwareUpdate AddIn, the Information Model shall provide a defined entry point to find all these devices in an efficient manner.

This Use Case is expected to be addressed in other working groups or in a future version of this specification.

A possible solution would be to create a SWUpdate FolderType below DeviceFeatures as it is described in the DI specification. This folder could reference all SoftwareUpdate AddIns.

In most update scenarios the device can restart automatically during or after the installation. However, there can be situations where it is required to explicitly restart the device by the Client.

This use case is not supported by the current version of this specification. Since this feature can be useful outside of software update it should be realized somewhere outside this specification.

Sometimes it is desirable to store all files required for software update at a central place and have the devices get the files on their own time and pace. In this case the Client would tell the Server only the location of the file. Then the actual transfer is initiated by the device.

There is no specific support for this use case in this specification. However, it is possible to use the described mechanisms to transfer a file that does not contain the actual software but the location of the external source(s) where the software file(s) should be pulled from.

Besides specific Clients for specific devices, this specification also describes Software Update Clients that can update devices of various vendors (for additional details see 8.3.5).

For Devices in operational use, it is often necessary to consider the operation state of the software / machine / plant before performing the update (e.g. stop and start the operation). For this case a specialized Client can use additional domain-specific Information Models as part of the update process.

An update can be performed manually by a user for a single device. However, if a lot of devices are maintained on a regular basis an automatic update is desirable. For this scenario the Information Model also allows the transfer of software to the devices without starting the update process. For the installation a Client could control several devices simultaneously.

This common model can describe several types of software that could necessitate to be updated or installed. This can be the firmware or operating system of a device but also be one or more software applications that require an update. Configuration can be maintained as software as well. Besides the update, it is also desired to install additional software. The Server can expose all software as a single component or separate it into several smaller components as it is illustrated in Figure 33.

Figure 33 – Example with a device and several software components

For precise identification of a specific software instance, the SoftwareUpdateType can support additional Properties: The SoftwareClass can be used to distinguish an application from a configuration or firmware. This can be further specialized by the SoftwareSubclass Property for example to identify the type of an application. Finally, the Property SoftwareName can be used to distinguish multiple instances of an application as illustrated in Figure 33 and Figure 34.

Figure 34 – Example with flexible software components

Devices can have different requirements regarding a firmware update, depending on their type and available resource (e.g., memory).

Memory-constrained devices like sensors often cannot store an additional firmware. These devices install the new firmware while it is transferred to the device. In this specification this is called Direct-Loading (see 8.3.4.3).

Devices with more memory can store a new firmware in a separate memory without installing it which is referred as Cached-Loading in this specification (see 8.3.4.4). In this case the installation is separated from the file transfer and can be done later or with a different Client.

Some devices have two memory partitions for the operating system. One active partition that is used in the boot process and a second alternative fallback partition. These devices install the firmware into the fallback partition and then perform a restart after swapping the active partition. This has an advantage if the device detects an issue with the new firmware: The change can easily be reverted to the old version by switching the partitions again (with another reboot).

Constrained devices like sensors typically do not support a real file system. Devices with more memory often have a file system which can be used to store files like firmware, parameters and backups. This Information Model provides update mechanisms for both types of devices (see 8.3.4.5 for FileSystem based Loading).

Updating software or firmware of a machine or plant is a complex task and different devices have different requirements to the update or installation of software. To support this, the SoftwareUpdateType provides several options where a vendor can select the parts that are necessary for the software update.

All these options are exposed as optional References of the SoftwareUpdateType. A Server can choose which options it wants to support (the Profiles section describes valid combinations of options).

This way the Server can choose between Direct-Loading, Cached-Loading or FileSystem based Loading and it can use additional optional features like manual power cycle, parameter backup / restore or confirmation.

It is necessary that a Software Update Client checks which options are exposed by the Server and how the Server behaves during the update (a Software Update Client is described in 8.3.5).

There are situations where it is preferable to prepare the device explicitly before the installation and resume operation explicitly after the installation. The PrepareForUpdateStateMachine, which is described in 8.4.7.9 can be used for this task.

This can be the case, when several devices of a machine should be updated at once. All devices have to be prepared first to ensure that all are waiting for an update. After that they can be updated by the Client. At the end after all individual updates are complete the devices can resume operation.

Or a device requires the behavior to enter a safe state (e.g., reaching a safe area) to be able to update the software.

If the installation comprises several steps (e.g., backup parameters, install firmware, restore parameters). The steps can be encapsulated by the Prepare and Resume Methods to ensure consistency between all the steps.

The Direct-Loading option provides a model where the installation is part of the transfer. To support the Direct-Loading model the Server has to provide the Current Version. This includes parameters like the version number, a release date or patch identifiers. With this information the Client can decide if an update is required and which version to install.

The Software Package is transferred using the TemporaryFileTransferType (OPC 10000-5). This includes the installation itself so that the installation option is not used.

Note that if the Software Package is installed during the transfer, the server cannot verify the integrity of the complete Software Package before the installation. If this is required, Cached-Loading is a better alternative.

For Direct-Loading the DirectLoadingType is used, which is described in 8.4.4.

The Cached-Loading option provides a model where the transfer of the Software Package and its installation are separate steps. To support the Cached-Loading model the Server has to provide the Current Version and the Pending Version. Optionally the Fallback Version can be supported.

With the Current Version the Client can decide if an update is required and which version to transfer. With the Pending Version the Client can ensure to install the desired version after the transfer of the Software Package. With the Fallback Version the Client can install an alternative version.

Software Packages are transferred using the TemporaryFileTransferType (OPC 10000-5). The new software can be transferred in the background without stopping the device. The actual installation of the software can be done later using the installation option.

Note: This loading option is the preferred option for best interoperability between Software Update Clients and Devices.

For Cached-Loading the CachedLoadingType is used, which is described in 8.4.5.

The Cached-Loading option with a self-contained Software Package and concrete definition of the version information can be too restrictive for some devices. E.g., if new software should be installed. For this use case the FileSystem based Loading provides an open structure of files and directories where a Client can read and write. These files could be e.g., configuration, setup files or recipes.

Note: The FileSystem exposed in the AddressSpace is not necessarily congruent with the actual file system of the device.

Note: Since FileSystem based Loading supports adding new software and updating multiple parts with individual versions, there is no standard way to expose the current version number(s) of the system. Therefore, a Software Update Client requires additional vendor-specific information, or other companion specifications must define a more specific use. If the additional flexibility of FileSystem based Loading is not required, Cached-Loading should be preferred.

The purpose of the directories and files is not part of this specification. It is necessary, that Client and the Server know it. Other companion specifications could add this definition for specific types of devices. If accessed by a Software Update Client, the FileSystem root can be used to store and install the files.

For FileSystem based Loading the FileSystemLoadingType is used, which is described in 8.4.6.

Using the Cached-Loading option or the FileSystem option, a transferred Software Package or file is installed explicitly (compared to the implicit installation of Direct-Loading). Therefore, the InstallationStateMachineType shall be used (see 8.4.9). It can either be used to install a Software Package (Cached-Loading) or a list of files from the FileSystem (File System based Loading).

The update Clients are often operated by human users. Since an update normally is a long process, the user would like to see the current state. At a first glance the percentage can give a hint about completion of the update, especially if several devices are updated at the same time. But if there are unexpected delays or errors the user requies a detailed textual description about the current update action or issue.

This can be accomplished with the UpdateStatus Variable (see 8.4.1.8). A Client can subscribe to it for a user display. At least if a state machine is in an error state the UpdateStatus should provide a meaningful error message for the user.

If the device cannot keep the parameters during the update, it shall support the Parameters Object of the SoftwareVersionType (see 8.4.1.7). If supported by the Server, the update Client should perform a backup of the parameters before and restore the parameters after the software update.

The confirmation option supports the use case of 8.2.2.9: A Client can set a ConfirmationTimeout before the installation. After every reboot of the Server caused by the update, it shall wait this time for a call to the Confirm Method. If the call is not received the Server shall perform a rollback to enable a working Client – Server connection again. This state machine is defined in 8.4.11.

The power cycle option is intended for devices where a manual power cycle is required. During the installation the state WaitingForPowerCycle informs the user that it is time to turn the power off and on again. The PowerCycleStateMachineType is defined in 8.4.10.

If an instance of the SoftwareUpdateType supports the power cycle option, the UpdateBehavior RequiresPowerCycle shall indicate if this can happen for an installation.

This power cycle state machine is used in combination with the installation. For Cached-Loading it can be used in the Installing state of the InstallationStateMachineType. For Direct-Loading it can be used during the transfer of the new software with the TemporaryFileTransferType (OPC 10000-5) of the DirectLoadingType.

The first task of a Software Update Client is to find the components that support software update. After that it can execute the update of the components one by one or in parallel. The following activity diagrams illustrate how a Software Update Client can perform an update using the different update types. The first task is to detect what options are supported by browsing the references of the SoftwareUpdate AddIn. Then the Client can check the version information to determine whether an update is necessary. This is illustrated in Figure 35.

Figure 35 – Determine the type of update that the Server implements.

The activities of the different loading types are slightly different. With Cached-Loading the Client can check CurrentVersion and PendingVersion Objects to determine if the Software Package is already transferred. With the FileSystem based Loading the Client can browse the FileSystem to find out which files are already transferred. For Cached-Loading and File System based Loading the transfer can be done in advance. There are different ways to get the UpdateBehavior, because for Cached-Loading and File System based Loading this depends on the actual software that should be installed (with Direct-Loading the server has no information about the new software). For Direct-Loading and Cached-Loading the validation is done during the transfer. For File System based Loading this shall be done before the installation as an extra step. These steps are illustrated in Figure 36.

Figure 36 – Different flows of Direct-Loading, Cached-Loading and FileSystem based Loading

The prepare activity can be handled equal for all types of loading. This optionally includes a backup if the device cannot keep the parameters during update. The activity is shown in Figure 37.

Figure 37 – Prepare and Resume activities

The actual installation of Direct-Loading is done during the transfer. At the end there can be a manual power cycle (option). In some cases (if the Server is on the device that is updated) the Server is rebooted and the Client is required to reconnect to complete the installation. This is illustrated in Figure 38.

Figure 38 – Installation activity for Direct-Loading

For Cached-Loading and File System based Loading the installation is done using the InstallationStateMachineType. For Cached-Loading the InstallSoftwarePackage Method is used and for File System based Loading the InstallFiles Method is used. During this installation there can also be a manual power cycle request requiring operator input. The Client possibly is required to reconnect one or more times due to automatic reboots. If the Confirmation Object is available, the Client can use it during the installation. This is illustrated in Figure 39.

Figure 39 – Installation activity for Cached-Loading and File System based Loading

The resume activity can be handled equal for all types of loading. This optionally includes restore if the device cannot keep the parameters during update. The activity is shown in Figure 40.

Figure 40 – Resume activity

Especially for safety critical devices the update Client shall inform the user before performing critical activities. This includes the information if a manual power cycle is required, if the device will reboot or if it will lose its parameters during the update. This information can be accessed before the actual update is started. For safety all security considerations also apply.

Security is a critical aspect of software update. The basic requirements can be solved with the existing UA security mechanisms (secure transport, authorization and role-based authentication). Only authorized users shall be able to install and manage updates.

It is necessary that the Client verifies the identity of the device. This can be accomplished by identification information provided by OPC UA, by this specification or by companion specifications.

It is necessary that the authenticity (integrity and source) of the Software Package is verified. These aspects can be implemented by the device in a vendor specific way e.g., verify a digital signature of the Software Package. These mechanisms are out of scope of this specification.

The concrete process of the installation can depend on the device and on the software that is to be installed. Therfore the server provides the UpdateBehavior OptionSet (see 8.5.2). The UpdateBehavior can be determined with the UpdateBehavior Variable (see 8.4.4.3) of the DirectLoadingType or with one of the GetUpdateBehavior Methods of the CachedLoadingType (see 8.4.5.5) or the FileSystemLoadingType (see 8.4.6.3).

Instead of updating the whole software with a new version, sometimes the software is “patched”; i.e. only a part of it is replaced. The installation of such a patch can be implemented in the same way as the installation of a complete version. The only difference is that the result is not a new SoftwareRevision but an additional entry in the list of patch-identifiers stored in the PatchIdentifiers Variable (see 8.4.7.5).

If parameters or settings of an old software do not work with the new software, the installation of the new software can complete but the device still cannot start as before. In this case the Server should treat the installation as successful. It can inform the incompatibility using e.g., the IDeviceHealthType Interface (see 4.5.4) of the device / component. This issue can be resolved later by a client that fixes or updates the parameters.

To support an individual software update for the devices of a Server AddressSpace the software update model is defined using the AddIn model as it is described in OPC 10000-3. An instance of SoftwareUpdateType shall be attached to either Objects that implement the Interface IVendorNameplateType (see 4.5.2) or Objects that support an Identification FunctionalGroup (see B.2) that implements IVendorNameplateType. For the AddIn instance the fixed BrowseName “SoftwareUpdate” shall be used. This model gives any device, hardware- or software-component the opportunity to support SoftwareUpdate.

With this mechanism it is also possible to update parts of a software independently: A Server could expose parts as additional software components with their own update AddIn.

To identify the device / component that is the target for the software update, the IVendorNameplateType Interface is used. In this Interface at least the Variables Manufacturer, ManufacturerUri, ProductCode and SoftwareRevision shall be supported and have valid values. Optionally Model and HardwareRevision should be supported. These Properties can be shown to the operator. ManufacturerUri, ProductCode and HardwareRevision should be used to identify the component.

Note that the Properties SoftwareRevision, Manufacturer and ManufacturerUri also appears in the CurrentVersion of the PackageLoadingType. Their values can be different, if the manufacturer of the Device is not the same as the manufacturer of the software. The SoftwareRevision Object shall be the same at both places.

The ComponentType (see 4.5.7) already implements the Interface IVendorNameplateType. This makes it a good candidate for a SoftwareUpdate AddIn as illustrated in the example in Figure 41.

Figure 41 – Example how to add the SoftwareUpdate AddIn to a component

The SoftwareUpdateType defines an AddIn which can be used to extend Objects with software update features. All software update options are exposed as references of this AddIn. This way a Client can check for the references of the AddIn to determine which options are provided by a Server. If an option is available, it shall be used as specified.

The SoftwareUpdateType is illustrated in Figure 42 and formally described in Table 76.

Figure 42 – SoftwareUpdateType

Table 76 – SoftwareUpdateType definition

Attribute	Value
BrowseName	1:SoftwareUpdateType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:BaseObjectType defined in OPC 10000-5.
0:HasComponent	Object	1:Loading		1:SoftwareLoadingType	O
0:HasComponent	Object	1:PrepareForUpdate		1:PrepareForUpdateStateMachineType	O
0:HasComponent	Object	1:Installation		1:InstallationStateMachineType	O
0:HasComponent	Object	1:PowerCycle		1:PowerCycleStateMachineType	O
0:HasComponent	Object	1:Confirmation		1:ConfirmationStateMachineType	O
0:HasComponent	Object	1:Parameters		0:TemporaryFileTransferType	O
0:HasComponent	Variable	1:UpdateStatus	0:LocalizedText	0:BaseDataVariableType	O
0:HasProperty	Variable	1:SoftwareClass	SoftwareClass	0:PropertyType	O
0:HasProperty	Variable	1:SoftwareSubclass	0:String	0:PropertyType	O
0:HasProperty	Variable	1:SoftwareName	0:String	0:PropertyType	O
0:HasProperty	Variable	1:UnsignedPackageAllowed	0:Boolean	0:PropertyType	O
0:HasComponent	Variable	1:VendorErrorCode	0:Int32	0:BaseDataVariableType	O
0:HasProperty	Variable	0:DefaultInstanceBrowseName	0:QualifiedName	0:PropertyType
Conformance Units
DI SU Software Update

The optional Loading Object is of type SoftwareLoadingType, which is abstract. The Object can be one of the concrete sub-types DirectLoadingType (8.4.4), CachedLoadingType (8.4.5) or FileSystemLoadingType (8.4.6). SoftwareLoadingType is formally defined in 8.4.2.

The Loading Object is required for all variations of software installation, it is not required for read or restore of device parameters using the Parameters Object.

The optional PrepareForUpdate Object is of type PrepareForUpdateStateMachineType which is formally defined in 8.4.7.9.

This optional Installation Object is of type InstallationStateMachineType which is formally defined in 8.4.9.

This optional PowerCycle Object is of type PowerCycleStateMachineType which is formally defined in 8.4.10.

This optional Confirmation Object is of type ConfirmationStateMachineType which is formally defined in 8.4.11.

This optional Parameters Object is of type TemporaryFileTransferType (OPC 10000-5). It can be supported by devices that cannot retain parameters during update. If supported by the SoftwareUpdate AddIn a Client can read the parameters before the update and restore them after the update. This is not a general-purpose backup and restore function. It is intended to be used in the context of software update.

The GenerateFileForRead and GenerateFileForWrite Methods accept an unspecified generateOptions Parameter. This argument is not used, and Clients shall always pass null. Future versions of this specification can define concrete DataTypes.

If the restore of parameters succeeds but the software cannot run properly this should not be treated as an error of the restore. Instead, this should be indicated using the IDeviceHealthType Interface of the device / component.

This optional localized string provides status and error information for the update. This can be used whenever a long running update activity can provide detailed information to the user or when a state machine wants to provide error information to the user.

A Server can provide any text it wants to show to the operator of the software update. Important texts are the error messages in case anything went wrong, and the installation or preparation could not complete. These messages should explain what happened and how the operator could resolve the issue (e.g. “try again with a different version”). During preparation and installation, it is good practice to inform the operators about the current action to keep them patient and waiting for the completion. Also, if the installation gets stuck this text would help to find out the reason.

The UpdateStatus can be used together with the PrepareForUpdateStateMachineType (8.4.7.9), the InstallationStateMachineType (8.4.9) and for CachedLoadingType (8.4.5), DirectLoadingType (8.4.4) and FileSystemLoadingType (8.4.6) it can be used during the transfer of the Software Package.

The optional SoftwareClass Property is used to distinguish device firmware from executable applications and from supporting configuration. A Software Update Client can use this information together with the SoftwareSubclass and the SoftwareName to identify the associated component (See 8.3.2).

The optional SoftwareSubclass Property can be used to further specialize the type of software (See 8.3.2).

If there can be more than one instance of a software, the optional SoftwareName Property can be used distinguish the individual instances (see 8.3.2).

This Property indicates whether the server accepts Software Packages that are not signed.

The optional VendorErrorCode Property provides a machine-readable error code in case anything went wrong during the transfer, the installation, or the preparation. Comparable to an error message in UpdateStatus this Variable can provide additional information about the issue. The VendorErrorCode is an additional information for a Client. It is not required for normal operation and error handling.

The value 0 shall be interpreted as no error.

The VendorErrorCode can be used together with the PrepareForUpdateStateMachineType (8.4.7.9) for prepare and resume, in the InstallationStateMachineType (8.4.9) during the installation. For CachedLoadingType (8.4.5), DirectLoadingType (8.4.4) and FileSystemLoadingType (8.4.6) it can be used during the transfer of the Software Package.

The DefaultInstanceBrowseName Property – defined in OPC 10000-3 – is required for the AddIn model as specified in 8.3.11. It is used to specify the BrowseName of the instance of the SoftwareUpdateType. It always has the value “SoftwareUpdate”.

Table 77 – SoftwareUpdateType Attribute values for child Nodes

Source Path	Value
0:DefaultInstanceBrowseName	SoftwareUpdate

The SoftwareLoadingType is the abstract base for all different kinds of loading. The concrete information and behavior is modeled in its sub-types.

The SoftwareLoadingType is formally defined in Table 78.

Table 78 – SoftwareLoadingType definition

Attribute	Value
BrowseName	1:SoftwareLoadingType
IsAbstract	True
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:BaseObjectType defined in OPC 10000-5
0:HasSubtype	ObjectType	1:PackageLoadingType
0:HasSubtype	ObjectType	1:FileSystemLoadingType
0:HasComponent	Variable	1:UpdateKey	0:String	0:BaseDataVariableType	O
Conformance Units
DI SU Software Update

The optional write-only UpdateKey Object can be used if the underlying system requires some key to unlock the update feature. The format and where to get the key is vendor-specific and not described in this specification. If UpdateKey is supported, the Client shall set the key before the installation. If the PrepareForUpdateStateMachine is used, the UpdateKey shall be set before the Prepare Method is called. The Server shall not keep the value for more than one update.

The PackageLoadingType provides information about the Current Version and allows transfer of a Software Package to and from the Server.

The PackageLoadingType is illustrated in Figure 43 and formally defined in Table 79.

Figure 43 – PackageLoadingType

Table 79 – PackageLoadingType definition

Attribute	Value
BrowseName	1:PackageLoadingType
IsAbstract	True
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the SoftwareLoadingType
0:HasComponent	Object	1:CurrentVersion		1:SoftwareVersionType	M
0:HasComponent	Object	1:FileTransfer		0:TemporaryFileTransferType	M
0:HasComponent	Variable	1:ErrorMessage	0:LocalizedText	0:BaseDataVariableType	M
0:HasProperty	Variable	1:WriteBlockSize	0:UInt32	0:PropertyType	O
0:HasSubtype	ObjectType	1:DirectLoadingType
0:HasSubtype	ObjectType	1:CachedLoadingType
Conformance Units
DI SU Software Update

To identify the Current Version, the CurrentVersion Object provides ManufacturerUri, SoftwareRevision and PatchIdentifiers along with other information that allows the user to identify the currently used software. With this information the Client can determine a suitable update.

Note: This version information is about the installed software. The Manufacturer is not necessarily the same as the Manufacturer of the physical device that executes the software.

The FileTransfer Object is of type TemporaryFileTransferType as defined in OPC 10000-5. It is used to create temporary files for download and upload of the Software Package. See 8.7 for the definition of a standard packaging format.

In the TemporaryFileTransferType type the GenerateFileForRead and GenerateFileForWrite Methods take an unspecified generateOptions Parameter. For the FileTransfer Object an Enumeration of type SoftwareVersionFileType is used for this Parameter. It is used to select the file to upload or download. All allowed values are defined in Table 112. Additional Result Codes of the GenerateFileForRead and GenerateFileForWrite Methods are specified in Table 80.

Table 80 – TemporaryFileTransferType Result Codes

Result Code	Description
Bad_InvalidState	This result code is only used with DirectLoading.f the PrepareForUpdate is available, the UpdateBehavior requires preparation and the PrepareForUpdate state machine is not in the state PreparedForUpdate.
Bad_NotFound	If there is no file to read from the device.
Bad_NotSupported	If the device does not support to upload / download of the Software Package.

For all errors that occur during the file transfer the ErrorMessage Variable should provide an error message for the user.

It is implementation dependent which version (see SoftwareVersionFileType in 8.5.1) is readable and which one is writable. Additional restrictions are defined in the concrete sub-types of PackageLoadingType.

The software is transferred as a single package. File type and content are device specific. If WriteBlockSize is supported, the Client shall write the file in chunks of this size.

The software should be validated during the transfer process. Errors shall be indicated either in the Write Method, the CloseAndCommit Method or an asynchronous completion of the file transfer. If the validation is performed synchronous, the Method returns Bad_InvalidArgument; if the validation is performed asynchronous, the error is indicated by the Error state of the FileTransferStateMachineType. If the ErrorMessage Variable is provided, it shall contain an error message representing the validation error.

The FileTransfer Object can optionally support the transfer of a Software Package from the device to the Client.

If this transfer is not supported, the Server shall return the Result Code Bad_NotSupported. If it is supported but there is currently no data, the Result Code Bad_NotFound shall be used instead.

This is a textual information about errors that can occur with the file transfer. Whenever a method of the TemporaryFileTransferType returns an error, the ErrorMessage Variable should provide a localized error message for the user. For every new file transfer the value should be reset to an empty string.

Optional size of the Blocks (number of bytes) that a Client shall write to the file. The client shall write the Software Package in chunks of this size to the FileType object (the last Block can be smaller).

The DirectLoadingType provides information about the Current Version and allows transfer of a Software Package to and from the Server. Transfer of the Software Package to the Server also includes the installation. The Direct-Loading option is described in 8.3.4.3.

The DirectLoadingType is illustrated in Figure 44 and formally defined in Table 81.

Figure 44 – DirectLoadingType

Table 81 – DirectLoadingType definition

Attribute	Value
BrowseName	1:DirectLoadingType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 1:PackageLoadingType
0:HasComponent	Variable	1:UpdateBehavior	1:UpdateBehavior	0:BaseDataVariableType	M
0:HasProperty	Variable	1:WriteTimeout	0:Duration	0:PropertyType	O
Conformance Units
DI SU DirectLoading

The FileTransfer Object is inherited from the PackageLoadingType. In this sub-type the Current version shall be writable (see SoftwareVersionFileType in 8.5.1). Writing to this file also includes the actual installation.

The UpdateBehavior OptionSet informs the update Client about the specific behavior of the component during update via Direct-Loading.

Optional Property that informs the Client about the maximum duration of the call to the Write Method of FileType (maximum time the write of a block of data can take). If the write operation takes longer the Client can assume that the Server has an issue.

The CachedLoadingType provides information about the Current Version, the Pending Version and the Fallback Version (if supported). Additionally, it allows upload and download of different versions of the software. The Cached-Loading option is described in 8.3.4.4.

The CachedLoadingType is illustrated in Figure 45 and formally defined in Table 82.

Figure 45 – CachedLoadingType

Table 82 – CachedLoadingType definition

Attribute	Value
BrowseName	1:CachedLoadingType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 1:PackageLoadingType
0:HasComponent	Object	1:PendingVersion		1:SoftwareVersionType	M
0:HasComponent	Object	1:FallbackVersion		1:SoftwareVersionType	O
0:HasComponent	Method	1:GetUpdateBehavior			M
Conformance Units
DI SU CachedLoading

The FileTransfer Object is inherited from the PackageLoadingType. In this sub-type the Current version shall not be writable and the Pending version shall be writable (see SoftwareVersionFileType in 8.5.1).

The PendingVersion Object describes an already transferred new Software Package that is ready to be installed.

If there is no Software Package available, the values should be empty.

The optional FallbackVersion Object describes an alternate version on the device. This could be a factory default version or the version before the last update. Installing the Fallback Version can be used to revert to a reliable version of the software.

If a Fallback Version is supported by the device the object shall be available. If there is currently no Fallback Version on the device, the values should be empty.

With this Method the Client can check the specific update behavior for a specified software version. To identify the version the GetUpdateBehavior Method requires the ManufacturerUri, SoftwareRevision and PatchIdentifiers Properties of the SoftwareVersionType.

Signature

GetUpdateBehavior(

[in]0:String ManufacturerUri,

[in]0:String SoftwareRevision,

[in]0:String[] PatchIdentifiers,

[out]UpdateBehaviorUpdateBehavior);

Table 83 – GetUpdateBehavior Method Arguments

Argument	Description
ManufacturerUri	ManufacturerUri Property of either the Pending or Fallback SoftwareVersionType that should be installed.
SoftwareRevision	SoftwareRevision Property of either the Pending or Fallback SoftwareVersionType that should be installed.
PatchIdentifiers	PatchIdentifiers Property of either the Pending or Fallback SoftwareVersionType that should be installed. (or empty array if not supported by the SoftwareVersionType instance)
UpdateBehavior	Update behavior option set for the specified SoftwareVersionType instance

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NotFound	If the Software Package, identified by the parameters, does not exist.

Table 84 – GetUpdateBehavior Method AddressSpace definition

Attribute	Value
BrowseName	1:GetUpdateBehavior
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU CachedLoading

The FileSystemLoadingType enables software update based on an open file system. This enables the FileSystem based Loading option of 8.3.4.5.

It is illustrated in Figure 46 and formally defined in Table 85.

Figure 46 – FileSystemLoadingType

Table 85 – FileSystemLoadingType definition

Attribute	Value
BrowseName	1:FileSystemLoadingType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the SoftwareLoadingType
0:HasComponent	Object	0:FileSystem		0:FileDirectoryType	M
0:HasComponent	Method	1:GetUpdateBehavior			M
0:HasComponent	Method	1:ValidateFiles			O
Conformance Units
DI SU FileSystem Loading

The FileSystem Object is of type FileDirectoryType as it is defined in OPC 10000-5. It provides access to a hierarchy of directories and files of the device. The structure can be read and written by the Client however the device can restrict this for specific folders or files.

This Method can be used to check the specific update behavior for a set of files. The files are identified by the NodeId of their FileType instance in the FileSystem.

Signature

GetUpdateBehavior(

[in] 0:NodeId[] NodeIds,

[out] UpdateBehaviorUpdateBehavior);

Table 86 – GetUpdateBehavior Method Arguments

Argument	Description
NodeIds	NodeIds of the files to install.
UpdateBehavior	Update behavior OptionSet for the files specified by NodeId

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NotFound	If one or more NodeIds are not found.

Table 87 – GetUpdateBehavior Method AddressSpace definition

Attribute	Value
BrowseName	1:GetUpdateBehavior
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU FileSystem Loading

This Method can be used to check if the specified set of files are valid and complete for an installation. This should also include dependency checks if appropriate.

Note: In case of Direct-Loading or Cached-Loading these checks should be part of the transfer and this method shall not be supported since it is part of the file transfer (e.g., in CloseAndCommit).

Signature

ValidateFiles(

[in] 0:NodeId[] NodeIds,

[out] 0:Int32 ErrorCode,

[out] 0:LocalizedTextErrorMessage);

Table 88 – ValidateFiles Method Arguments

Argument	Description
NodeIds	NodeIds of the files to validate.
ErrorCode	0 for success or device specific number for validation issues.
ErrorMessage	Message for the user that describes how to resolve the issue.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NotFound	If one or more NodeIds are not found.

Table 89 – ValidateFiles Method AddressSpace definition

Attribute	Value
BrowseName	1:ValidateFiles
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU FileSystem Loading

The SoftwareVersionType identifies a concrete version of a software. It is used by the CachedLoadingType (8.4.5) and the DirectLoadingType (8.4.4) to store the version information.

The Description Attribute on the instances of the SoftwareVersionType should be used to provide additional information about the concrete version of the software to the user (e.g., change notes).

The SoftwareVersionType is illustrated in Figure 47 and formally defined in Table 90.

Figure 47 – SoftwareVersionType

Table 90 – SoftwareVersionType definition

Attribute	Value
BrowseName	1:SoftwareVersionType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:BaseObjectType defined in OPC 10000-5
0:HasProperty	Variable	1:Manufacturer	0:LocalizedText	0:PropertyType	M
0:HasProperty	Variable	1:ManufacturerUri	0:String	0:PropertyType	M
0:HasProperty	Variable	1:SoftwareRevision	0:String	0:PropertyType	M
0:HasProperty	Variable	1:PatchIdentifiers	0:String[]	0:PropertyType	O
0:HasProperty	Variable	1:ReleaseDate	0:DateTime	0:PropertyType	O
0:HasProperty	Variable	1:ChangeLogReference	0:String	0:PropertyType	O
0:HasProperty	Variable	1:Hash	0:ByteString	0:PropertyType	O
0:HasComponent	Method	1:Clear			O
Conformance Units
DI SU Software Update

The read only Manufacturer Property provides the name of the company that created the software.

In case of the Pending Version this shall be empty if there is no pending software to install.

The read only ManufacturerUri Property provides a unique identifier for the manufacturer of the software.

In case of the Pending Version this shall be empty if there is no pending software to install.

The read only SoftwareRevision Property defines the version of the software. The format and semantics of the string is vendor-specific. SemanticVersionString (a sub-type of String defined in OPC 10000-5) can be used when using the Semantic Versioning format.

In case of the Pending Version this shall be empty if there is no pending software to install.

The read only PatchIdentifiers Property identifies the list of patches that are applied to a software version. The format and semantics of the strings are vendor-specific. The order of the strings shall not be relevant.

The read only ReleaseDate Property defines the date when the software is released. If the version information is about patches, this should be the date of the latest patch. It is additional information for the user.

The read only ChangeLogReference Property can optionally provide a URL to a web site with detailed information about the particular version of the software (change notes). In case of a patched software, the web site should also inform about the patches.

The optional read only Hash Property can be read by a Client to get the hash of a previously transferred Software Package. The hash value is calculated by the Server with the SHA-256 algorithm. It can be used to verify if the transferred package matches the one at the Client.

This optional Method can be used to delete the previously transferred software from the device. For Pending and Fallback Versions this often makes sense to free memory. For configuration objects it can be possible to clear the Current Version. This Method supports the use case in 8.2.2.1.

Signature

Clear();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	The version object is already cleared.

The PrepareForUpdateStateMachineType can be used if the device requires to be prepared before the update. Another option is to delay the resuming of normal operation until all update actions are executed. This supports to prepare for update option of 8.3.4.2.

If a Server implements this state machine, a Client shall use it except if the UpdateBehavior indicates that this is not necessary for the transferred software. If preparation is required, the installation is only allowed if the PrepareForUpdateStateMachine is in the PreparedForUpdate state.

The state machine is illustrated in Figure 48, Figure 49 and formally defined in Table 91. The transitions are formally defined in Table 93.

Figure 48 – PrepareForUpdate state machine

Figure 49 – PrepareForUpdateStateMachineType

Table 91 – PrepareForUpdateStateMachineType definition

Attribute	Value
BrowseName	1:PrepareForUpdateStateMachineType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:FiniteStateMachineType defined in OPC 10000-5.
0:HasComponent	Variable	1:PercentComplete	0:Byte	0:BaseDataVariableType	O
0:HasComponent	Method	1:Prepare			M
0:HasComponent	Method	1:Abort			M
0:HasComponent	Method	1:Resume			O
0:HasComponent	Object	1:Idle		0:InitialStateType
0:HasComponent	Object	1:Preparing		0:StateType
0:HasComponent	Object	1:PreparedForUpdate		0:StateType
0:HasComponent	Object	1:Resuming		0:StateType
0:HasComponent	Object	1:IdleToPreparing		0:TransitionType
0:HasComponent	Object	1:PreparingToIdle		0:TransitionType
0:HasComponent	Object	1:PreparingToPreparedForUpdate		0:TransitionType
0:HasComponent	Object	1:PreparedForUpdateToResuming		0:TransitionType
0:HasComponent	Object	1:ResumingToIdle		0:TransitionType
Conformance Units
DI SU PrepareForUpdate

The component Variables of the PrepareForUpdateStateMachineType have additional Attributes defined in Table 92.

Table 92 – 1:PrepareForUpdateStateMachineType Attribute values for child Nodes

BrowsePath	Value Attribute
1:Idle 0:StateNumber	1
1:Preparing 0:StateNumber	2
1:PreparedForUpdate 0:StateNumber	3
1:Resuming 0:StateNumber	4
1:IdleToPreparing 0:TransitionNumber	12
1:PreparingToIdle 0:TransitionNumber	21
1:PreparingToPreparedForUpdate 0:TransitionNumber	23
1:PreparedForUpdateToResuming 0:TransitionNumber	34
1:ResumingToIdle 0:TransitionNumber	41

Table 93 – 1:PrepareForUpdateStateMachineType Additional References

SourceBrowsePath	Reference Type	Is Forward	TargetBrowsePath
Transitions
1:IdleToPreparing	0:FromState	True	1:Idle
	0:ToState	True	1:Preparing
	0:HasCause	True	1:Prepare
	0:HasEffect	True	0:TransitionEventType
1:PreparingToIdle	0:FromState	True	1:Preparing
	0:ToState	True	1:Idle
	0:HasCause	True	1:Abort
	0:HasEffect	True	0:TransitionEventType
1:PreparingToPreparedForUpdate	0:FromState	True	1:Preparing
	0:ToState	True	1:PreparedForUpdate
	0:HasEffect	True	0:TransitionEventType
1:PreparedForUpdateToResuming	0:FromState	True	1:PreparedForUpdate
	0:ToState	True	1:Resuming
	0:HasCause	True	1:Resume
	0:HasEffect	True	0:TransitionEventType
1:ResumingToIdle	0:FromState	True	1:Resuming
	0:ToState	True	1:Idle
	0:HasCause	True	1:Abort
	0:HasEffect	True	0:TransitionEventType

This percentage is a number between 0 and 100 that informs about the progress in the Preparing or the Resuming States. It can be used whenever the activity takes longer and the user should be informed about the completion. If the state machine is in Idle or PreparedForUpdate State it shall have the value 0.

This information is for the user only. It shall not be used to detect completion of the transition.

The Prepare Method can be called to prepare a device for an update. This call transitions the device into the state Preparing.

After the preparation is complete the state machine can perform an automatic transition to the state PreparedForUpdate.

If the preparation cannot complete and the device does not get prepared for update the state machine transitions back to Idle. In this case a message with the reason should be provided to the user via the UpdateStatus.

Signature

Prepare();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the PrepareForUpdateStateMachineType is not in Idle state.

An update client can use the Abort Method to bring the state machine from Resuming or Preparing back to the Idle state. This can be necessary, if the preparation takes too long or does not complete at all because the required internal conditions are not met. This call transitions the device back to the Idle state.

Note: If the transition from Preparing to Idle cannot complete instantly a Client can subscribe for the events or the state variable of the PrepareForUpdateStateMachine.

Signature

Abort();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the PrepareForUpdateStateMachineType is not in Preparing state.

A call to the optional Resume Method transitions the device into the state Resuming. After the resuming is complete the state machine performs an automatic transition to the Idle state. If the method is not supported, the transitions to Resuming and back to Idle shall be done by the Server automatically. If the method is supported, there shall not be an automatic transition to Resuming. Supporting this method enables the Client to group several activities like backup, install, restore on a single device or group the update of multiple devices before the devices are allowed to Resume their operation again.

Signature

Resume();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the PrepareForUpdateStateMachineType is not in PreparedForUpdate state or if the InstallationStateMachine is still in the state Installing.

The InstallationStateMachineType can be used if the device supports explicit installation (Cached-Loading or File System based Loading). This supports the installation option of 8.3.4.6. It is illustrated in Figure 50 and Figure 51 and formally defined in Table 94. The transitions are formally defined in Table 96.

Figure 50 – Installation state machine

Figure 51 – InstallationStateMachine

Table 94 – InstallationStateMachineType definition

Attribute	Value
BrowseName	1:InstallationStateMachineType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:FiniteStateMachineType defined in OPC 10000-5.
0:HasComponent	Variable	1:PercentComplete	0:Byte	0:BaseDataVariableType	O
0:HasComponent	Variable	1:InstallationDelay	0:Duration	0:BaseDataVariableType	O
0:HasComponent	Method	1:InstallSoftwarePackage			O
0:HasComponent	Method	1:InstallFiles			O
0:HasComponent	Method	1:Uninstall			O
0:HasComponent	Method	1:Resume			M
0:HasComponent	Object	1:Idle		0:InitialStateType
0:HasComponent	Object	1:Installing		0:StateType
0:HasComponent	Object	1:Error		0:StateType
0:HasComponent	Object	1:IdleToInstalling		0:TransitionType
0:HasComponent	Object	1:InstallingToIdle		0:TransitionType
0:HasComponent	Object	1:InstallingToError		0:TransitionType
0:HasComponent	Object	1:ErrorToIdle		0:TransitionType
Conformance Units
DI SU Software Update

The component Variables of the InstallationStateMachineType have additional Attributes defined in Table 95.

Table 95 – 1:InstallationStateMachineType Attribute values for child Nodes

BrowsePath	Value Attribute
1:Idle 0:StateNumber	1
1:Installing 0:StateNumber	2
1:Error 0:StateNumber	3
1:IdleToInstalling 0:TransitionNumber	12
1:InstallingToIdle 0:TransitionNumber	21
1:InstallingToError 0:TransitionNumber	23
1:ErrorToIdle 0:TransitionNumber	31

Table 96 – 1:InstallationStateMachineType Additional References

SourceBrowsePath	Reference Type	Is Forward	TargetBrowsePath
Transitions
1:IdleToInstalling	0:FromState	True	1:Idle
	0:ToState	True	1:Installing
	0:HasCause	True	1:InstallSoftwarePackage
	0:HasCause	True	1:InstallFiles
	0:HasCause	True	1:Uninstall
	0:HasEffect	True	0:TransitionEventType
1:InstallingToIdle	0:FromState	True	1:Installing
	0:ToState	True	1:Idle
	0:HasEffect	True	0:TransitionEventType
1:InstallingToError	0:FromState	True	1:Installing
	0:ToState	True	1:Error
	0:HasEffect	True	0:TransitionEventType
1:ErrorToIdle	0:FromState	True	1:Error
	0:ToState	True	1:Idle
	0:HasCause	True	1:Resume
	0:HasEffect	True	0:TransitionEventType

This percentage is a number between 0 and 100 that informs the user about the progress of an installation or uninstallation. It should be used whenever an update activity takes longer and the user should be informed about the completion. If the state machine is in Idle State it shall have the value 0. In case of an error the last value should be kept until the Resume is called.

This information is for the user only. It shall not be used to detect completion of the installation.

The optional InstallationDelay can be set by a Client to delay the actual installation after the call to InstallSoftwarePackage or InstallFiles is returned by the Server. This can be used when the installation is started on several devices in parallel and there is a risk that a reboot of one device could harm the connection to other devices. With a delay the install methods can be called on all devices before the devices actually start the installation. The InstallationDelay does not delay the transition from Idle to Installing.

This value could be preconfigured. If a Client wants to set this value it has to be done before the install method is called.

The Server is expected to stay operational at least during the delay.

With this Method the Client requests the installation of a Software Package. The package can be either the previously transferred Pending Version or the alternative Fallback Version. To identify the version and to prevent conflicts with a second Client that transfers a different version, the InstallSoftwarePackage Method requires the ManufacturerUri, the SoftwareRevision and PatchIdentifiers Properties of the SoftwareVersionType.

Optionally an additional hash value can be passed to the Method. This hash could be calculated by the Client or taken from a trusted source. Before installation the Server can compare the hash against the calculated hash of the Software Package. This mechanism can be used if there is a risk that the Software Package is altered during the transfer to the device and if the Server has no other mechanism to ensure that the Software Package is from a trustworthy source.

If the installation succeeds but the software cannot run properly this should not be treated as an error of the installation. Instead, this should be indicated using the IDeviceHealthType Interface of the device / component.

This Method shall not return before the state has changed to the Installing state.

Signature

InstallSoftwarePackage(

[in] 0:String ManufacturerUri,

[in] 0:String SoftwareRevision,

[in] 0:String[] PatchIdentifiers,

[in] 0:ByteString Hash);

Table 97 – InstallSoftwarePackage Method Arguments

Argument	Description
ManufacturerUri	ManufacturerUri Property of either the Pending or Fallback SoftwareVersionType that should be installed.
SoftwareRevision	SoftwareRevision Property of either the Pending or Fallback SoftwareVersionType that should be installed.
PatchIdentifiers	PatchIdentifiers Property of either the Pending or Fallback SoftwareVersionType that should be installed (or empty array if not supported on the SoftwareVersionType instance).
Hash	Hash of the Software Package that should be installed (or empty if not used).

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the InstallationStateMachineType is not in Idle state or if the PrepareForUpdate Object is available and the PrepareForUpdate state machine is not in the state PreparedForUpdate.
Bad_NotFound	If the specified Software Package does not exist.
Bad_InvalidArgument	If the Hash does not match the calculated hash of the Software Package.

Table 98 – InstallSoftwarePackage Method AddressSpace definition

Attribute	Value
BrowseName	1:InstallSoftwarePackage
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU Software Update

This Method can be called to request the installation of one or more files. The files are identified by the NodeId of their FileType instance in the FileSystem.

If the installation succeeds but the software cannot run properly this should not be treated as an error of the installation. Instead, this should be indicated using the IDeviceHealthType Interface of the device / component.

Signature

InstallFiles(

[in] 0:NodeId[] NodeIds);

Table 99 – InstallFiles Method Arguments

Argument	Description
NodeIds	NodeIds of the files to install.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the InstallationStateMachineType is not in Idle state or if the PrepareForUpdate Object is available and the PrepareForUpdate state machine is not in the state PreparedForUpdate.
Bad_NotFound	If one or more NodeIds are not found.

Table 100 – InstallFiles Method AddressSpace definition

Attribute	Value
BrowseName	1:InstallFiles
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU Software Update

The Uninstall Method can be called to request the uninstallation of the current software. This can be necessary e.g. for a project when uncommissioning a device or before deleting an application or configuration from the device (see SoftwareFolderType in 8.4.12.2).

The signature and specific result codes of this Method are specified below.

Signature

Uninstall();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the InstallationStateMachineType is not in Idle state or if the PrepareForUpdate Object is available and the PrepareForUpdate state machine is not in the state PreparedForUpdate.

This Method can be called to resume from the Error state. The Error state can be reached if there are issues during the installation. The state machine remains in this state until the Client calls the Resume Method to get back to the Idle state immediately.

Signature

Resume();

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidState	If the InstallationStateMachineType is not in Error state.

The PowerCycleStateMachineType is used to inform the user to perform a manual power cycle.

When the server requires a manual power cycle it indicates that to the client by changing the state to WaitingForPowerCycle. After restart of the Device, it transitions to NotWaitingForPowerCycle automatically.

There are no methods, all transitions originate from the installation process. The state machine is illustrated in Figure 52 and formally defined in Table 101. The transitions are formally defined in Table 103.

Figure 52 – PowerCycle state machine

Table 101 – PowerCycleStateMachineType definition

Attribute	Value
BrowseName	1:PowerCycleStateMachineType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:FiniteStateMachineType defined in OPC 10000-5.
0:HasComponent	Object	1:NotWaitingForPowerCycle		0:InitialStateType
0:HasComponent	Object	1:WaitingForPowerCycle		0:StateType
0:HasComponent	Object	1:NotWaitingForPowerCycleToWaitingForPowerCycle		0:TransitionType
0:HasComponent	Object	1:WaitingForPowerCycleToNotWaitingForPowerCycle		0:TransitionType
Conformance Units
DI SU Manual Power Cycle

The component Variables of the PowerCycleStateMachineType have additional Attributes defined in Table 102.

Table 102 – 1:PowerCycleStateMachineType Attribute values for child Nodes

BrowsePath	Value Attribute
1:NotWaitingForPowerCycle 0:StateNumber	1
1:WaitingForPowerCycle 0:StateNumber	2
1:NotWaitingForPowerCycleToWaitingForPowerCycle 0:TransitionNumber	12
1:WaitingForPowerCycleToNotWaitingForPowerCycle 0:TransitionNumber	21

Table 103 – 1:PowerCycleStateMachineType Additional References

SourceBrowsePath	Reference Type	Is Forward	TargetBrowsePath
Transitions
1:NotWaitingForPowerCycleToWaitingForPowerCycle	0:FromState	True	1:NotWaitingForPowerCycle
	0:ToState	True	1:WaitingForPowerCycle
	0:HasEffect	True	0:TransitionEventType
1:WaitingForPowerCycleToNotWaitingForPowerCycle	0:FromState	True	1:WaitingForPowerCycle
	0:ToState	True	1:NotWaitingForPowerCycle
	0:HasEffect	True	0:TransitionEventType

The ConfirmationStateMachineType is used to prove a valid Client – Server connection after a restart of the OPC UA Server. This supports the confirmation option of 8.3.4.9.

If several instances of this state machine are provided on a device (due to several instances of the SoftwareUpdateType), all instances should behave as if it is only a single instance. In particular it is sufficient to call one of the confirm methods after reboot.

The ConfirmationStateMachineType is illustrated in Figure 53 and Figure 54 and formally defined in Table 104. The transitions are formally defined in Table 106.

Figure 53 – Confirmation state machine

Figure 54 – ConfirmationStateMachineType

Table 104 – ConfirmationStateMachineType

Attribute	Value
BrowseName	1:ConfirmationStateMachineType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:FiniteStateMachineType defined in OPC 10000-5.
0:HasComponent	Method	1:Confirm			M
0:HasComponent	Variable	1:ConfirmationTimeout	0:Duration	0:BaseDataVariableType	M
0:HasComponent	Object	1:NotWaitingForConfirm		0:InitialStateType
0:HasComponent	Object	1:WaitingForConfirm		0:StateType
0:HasComponent	Object	1:NotWaitingForConfirmToWaitingForConfirm		0:TransitionType
0:HasComponent	Object	1:WaitingForConfirmToNotWaitingForConfirm		0:TransitionType
Conformance Units
DI SU Update Confirmation

The component Variables of the ConfirmationStateMachineType have additional Attributes defined in Table 105.

Table 105 – 1:ConfirmationStateMachineType Attribute values for child Nodes

BrowsePath	Value Attribute
1:NotWaitingForConfirm 0:StateNumber	1
1:WaitingForConfirm 0:StateNumber	2
1:NotWaitingForConfirmToWaitingForConfirm 0:TransitionNumber	12
1:WaitingForConfirmToNotWaitingForConfirm 0:TransitionNumber	21

Table 106 – 1:ConfirmationStateMachineType Additional References

SourceBrowsePath	Reference Type		Is Forward	TargetBrowsePath
Transitions
1:NotWaitingForConfirmToWaitingForConfirm	0:FromState	True		1:NotWaitingForConfirm
	0:ToState	True		1:WaitingForConfirm
	0:HasEffect	True		0:TransitionEventType
1:WaitingForConfirmToNotWaitingForConfirm	0:FromState	True		1:WaitingForConfirm
	0:ToState	True		1:NotWaitingForConfirm
	0:HasCause	True		1:Confirm
	0:HasEffect	True		0:TransitionEventType

The ConfirmationTimeout can be set by a Client to a value other then 0 to enable the confirmation feature. If the value is not 0 and the Client – Server connection is lost, the ConfirmationTimeout represents the maximum time that the Client is required to reconnect and call the Confirm Method. The Server shall automatically reset the value to 0 when the installation is complete.

After a reboot and with a ConfirmationTimeout other than 0 a Client shall call this Method to inform the Server that it has successfully reconnected. If this Method is not called after a lost connection the Server shall regard the update as unsuccessful and shall revert it. A Client is required to react within the time specified in the ConfirmationTimeout Variable.

Signature

Confirm();

The SoftwareFolderType is a subtype of FolderType. It allows adding and removing its items via the Add and Delete methods. With the SoftwareClass Variable the server exposes whether the folder holds a collection of applications or a collection of configurations. The ObjectType of the items is server specific, but the items shall at least support the SoftwareUpdate AddIn. They are identified by SoftwareSubclass and SoftwareName which is provided with the Add Method. After adding a new item, the SoftwareUpdate AddIn is used to transfer the initial software. After that it can be used to install updates. The SoftwareUpdate AddIn of each item shall support SoftwareClass, SoftwareSubclass and SoftwareName. SoftwareFolderType is defined in Table 107 and its usage is illustrated in Figure 55.

Figure 55 – Example use of SoftwareFolderType

Table 107 – SoftwareFolderType

Attribute	Value
BrowseName	1:SoftwareFolderType
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:FolderType defined in OPC 10000-5.
0:HasProperty	Variable	1:SoftwareClass	1:SoftwareClass	0:PropertyType	M
0:HasComponent	Method	1:Add			M
0:HasComponent	Method	1:Delete			M
Conformance Units
DI SU SoftwareFolder

The SoftwareClass Property is a SoftwareClass enumeration. It declares what items are managed by the folder. The value shall either be Application or Configuration.

The Add Method can be used to add a new item to the folder. The parameters Subclass and Name are exposed at the attached SoftwareUpdate AddIn as SoftwareSubclass and SoftwareName Properties. The Name shall be unique within the SoftwareFolderType.

Signature

Add(

[in] 0:String Subclass,

[in] 0:String Name);

Table 108 – Add Method Arguments

Argument	Description
Subclass	Subclass of the new item.
Name	Name of the new item.

Table 109 – Delete Method AddressSpace definition

Attribute	Value
BrowseName	1:Add
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU SoftwareFolder

The Delete Method can be used to delete an item from the folder. The Delete can require a call to Uninstall at the InstallationStateMachine (see 8.4.9).

Signature

Delete(

[in] 0:NodeId ObjectToDelete);

Table 110 – Delete Method Arguments

Argument	Description
ObjectToDelete	NodeId of the item to delete.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NotFound	The specified item does not exist.
Bad_InvalidState	If the item shall be uninstalled before deletion. (see InstallationStateMachineType 8.4.9).

Table 111 – Delete Method AddressSpace definition

Attribute	Value
BrowseName	1:Delete
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	M
Conformance Units
DI SU SoftwareFolder

This enumeration is used to identify the version in the methods of the TemporaryFileTransferType that is used in the PackageLoadingType (8.4.3). The Enumeration is defined in Table 112. Its representation in the AddressSpace is defined in Table 113.

Table 112 – SoftwareVersionFileType Items

Name	Value	Description
Current	0	The currently used version of the software identified by the CurrentVersion Object.
Pending	1	The Pending Version of the software that could be installed identified by the PendingVersion Object.
Fallback	2	The Fallback Version of the software identified by the FallbackVersion Object.

Table 113 – SoftwareVersionFileType definition

Attribute		Value
BrowseName		1:SoftwareVersionFileType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType
Conformance Units
DI SU Software Update

The UpdateBehavior OptionSet is based on UInt32. It describes how the device can perform the update. All possible options are described in Table 114. All other values are reserved for future versions of this specification. The OptionSet is used in the UpdateBehavior Property of the DirectLoadingType (8.4.4.3) and in the GetUpdateBehavior Methods on the CachedLoadingType (8.4.5.5) and in the FileSystemLoadingType (8.4.6.3).

Table 114 – UpdateBehavior OptionSet

Value	Bit No.	Description
KeepsParameters	0	If KeepsParameters is not set, the device will lose its configuration during update. The Client should do a backup of the parameters before the update and restore them afterwards.
WillDisconnect	1	If WillDisconnect is set, the OPC UA Server will restart during installation. This can be the case if the update is about the firmware of the device that hosts the OPC UA Server.
RequiresPowerCycle	2	If RequiresPowerCycle is set, the devices require a manual power off / power on for installation.
WillReboot	3	If WillReboot is set, the device will reboot during the update, inclusive of embedded infrastructure elements like an integrated switch. An update Client should take this into account since the devices behind an integrated switch are not reachable for that time.
NeedsPreparation	4	If NeedsPreparation is not set, the Client can install the update without maintaining the PrepareForUpdateStateMachine. This can be used to support an installation without stopping the software.

The UpdateBehavior OptionSet representation in the AddressSpace is defined in Table 115.

Table 115 – UpdateBehavior OptionSet Definition

Attribute	Value
BrowseName	1:UpdateBehavior
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Other
Subtype of 0:UInt32 defined in OPC 10000-5.
0:HasProperty	Variable	0:OptionSetValues	0:LocalizedText[]	0:PropertyType
Conformance Units
DI SU Software Update

This Enumeration is used to classify components, where instances of SoftwareUpdateType can be attached (see 8.3.2). The Enumeration is defined in Table 116. Its representation in the AddressSpace is defined in Table 117.

Table 116 – SoftwareClass Items

Name	Value	Description
Firmware	0	The software update is used for the firmware of a physical device.
Application	1	The software update is used for an executable software.
Configuration	2	The software update is used for the configuration of a device or application.
Solution	3	The software update is used to install a solution with several software package to several components.

Table 117 – SoftwareClass definition

Attribute		Value
BrowseName		1:SoftwareClass
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType
Conformance Units
DI SU Software Update

The UpdateParent ReferenceType is a concrete ReferenceType and can be used directly. It is a subtype of HierarchicalReferences.

The semantic of this ReferenceType is to link related components that are target for software update. These references are used by an update client to find related components for compatibility checks (see 8.7.3).

SourceNode and TargetNode of References of this type shall be objects that implement IVendorNameplateType.

A server shall support browsing of this ReferenceType in both directions.

Table 118 – UpdateParent ReferenceType definition

Attributes	Value
BrowseName	1:UpdateParent
InverseName	UpdateChild
Symmetric	False
IsAbstract	False
References	NodeClass	BrowseName	Comment
Subtype 0:HierarchicalReferences
Conformance Units
DI SU UpdateParent reference

The CanUpdate ReferenceType is a concrete ReferenceType and can be used directly. It is a subtype of HierarchicalReferences.

For components with SoftwareUpdate that accept Solution Packages this reference type is used to describe which subcomponents can be updated via the Solution Package. These references can be provided for use by clients to find related components when creating a Solution Package (see 8.7.5).

The source of this ReferenceType is a component that supports the SoftwareUpdate AddIn. The target of this ReferenceType is the component that can be updated.

SourceNode and TargetNode of References of this type shall be objects that implement IVendorNameplateType.

Table 119 – CanUpdate ReferenceType definition

Attributes	Value
BrowseName	1:CanUpdate
InverseName	CanBeUpdatedBy
Symmetric	False
IsAbstract	False
References	NodeClass	BrowseName	Comment
Subtype 0:HierarchicalReferences
Conformance Units
DI SU CanUpdate reference

The Software Package file format describes a standard format to share files for the software update. This enables Update Clients to use software from different vendors (i.e., it supports identification of the package, compatibility with the device, storage of the deployment and of supplementary files).

The Software Package is shared as a single ZIP file with all the content described in this section. The recommended file extension is “.uadipkg”. In some cases, parts of the ZIP file can be removed. For example, to retrieve just a lean metadata-only package with information about available updates without having to download many full Software Packages. Another example is removing the SUPPLEMENT folder to make the package smaller if the entire Software Package is deployed to the device.

On the root level, the Software Package can have the following folders:

The optional CONTENT folder holds the files or folders that are transferred to the device. The content of this folder is defined by the author of the Software Package. For Cached-Loading and Direct-Loading, this folder can contain a single file that shall be transferred to the device. Alternatively, it can contain multiple files, if the entire Software Package is sent to the device (see use case 8.2.2.14).

The mandatory META folder holds the Software Package’s metadata. It shall at least have the file package_metadata.json. This file describes what’s in the Software Package and to which components it is compatible (see use case 8.2.2.16).

The optional SUPPLEMENT folder can contain supplementary documents for use by the Update Client. These can include license details, release notes, or manuals related to the software. An Update Client can present them to the user as part of the software update (see use case 8.2.2.19).

The optional META-INF folder contains the digital signatures of the Software Package (see 8.7.4 8.2.2.20, 8.2.2.21).

In case of a Solution Package the optional SUBPACKAGES folder contains the content of the Software Packages that belong to the solution (see use case 8.2.2.22).

The package metadata file describes the identity of the Software Package, the target for the installation, the compatibility to the device and optionally the usage of individual files within the Software Package. The package_metadata.json is stored in the META folder.

The JSON schema for the package_metadata.json file associated with this version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/&v=1.05.0

The JSON schema associated with the latest version of the specification can be found here:

https://reference.opcfoundation.org/files/uamodel.di.packagemetadata.jsonschema.json?u=http://opcfoundation.org/UA/DI/

The JSON schema follows the conventions for the Compact DataEncoding defined in OPC 10000-6.

The elements of the JSON schema are described in Table 120, Table 124, Table 126, Table 128, Table 130, Table 132, Table 134, Table 136, Table 138 and Table 140.

A Software Package is uniquely defined with the ManufacturerUri, PackageType, TargetProductCodes, PackageRevision and Name.

The PackageMetadata structure and all contained types are encoded using the JSON VerboseEncoding.

Note: The following tables describe the package_metadata.json with structures and enumerations as a separate OPC UA namespace. These types typically do not show up in the AddressSpace of an OPC UA Server.

Table 120 – PackageMetadata structure

Name	Type	Description	Optional
PackageMetadata	0:Structure
Name	0:String	Names the package (the package file name can be changed)	False
Description	0:String	Description of the content of the Software Package.	True
ManufacturerUri	0:String	Identification of the manufacturer of the package (used with PackageType and SoftwareRevision to uniquely identify the package)	False
Manufacturer	0:String	Manufacturer of the package (for display purposes)	False
PackageRevision	0:String	Version of the software package	False
PackageType	2:PackageType	Type of the Software Package.Other values are reserved for future use.	False
SoftwareSubClass	0:String	Name of the application (in case of SoftwareClass Application)	True
DeployCompletePackage	0:Boolean	If true the complete package shall be sent to the device. Otherwise only the contained files that are marked as DeploymentItem are deployed (default: false).	True
SoftwareRevision	0:String	Version of the software in the package. Optional for solution packages.	True
ReleaseDate	0:DateTime	Additional information for the user	True
TargetManufacturerUri	0:String	Identification of the target Node on the device. Used to find suitable Software Packages for a device.	True
TargetManufacturer	0:String	Manufacturer of the target (for display purposes). Used to find suitable Software Packages for a device.	True
UpdateTargets[]	2:UpdateTarget	Identification of the target Node on the deviceUsed to find suitable Software Packages for a device.Optional for solution packages.	True
Files[]	2:FileDescriptor	Describes the files that require special treatment by the update client.	True
Compatibilities[]	2:CompatibilityOption	List of options: At least one of them must match to be compatible.	True
Assignments[]	2:Assignment	Assignments of Software Packages to components that support SoftwareUpdate Only for solution packages (see 8.7.5)	True

Table 121 – PackageMetadata definition

Attribute		Value
BrowseName		2:PackageMetadata
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 122 – UpdateTarget structure

Name	Type	Description	Optional
UpdateTarget	0:Structure
ProductCode	0:String	ProductCode of the target Node on the device.	False
Model	0:String	Model of the target Node on the device.	False

Table 123 – UpdateTarget definition

Attribute		Value
BrowseName		2:UpdateTarget
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 124 – FileDescriptor structure

Name	Type	Description	Optional
FileDescriptor	0:Structure
FileType	2:FileType	Describes how the client shall use the file.	False
FileName	0:String	Relative path and file name to the file in the ZIP package	False
MimeType	0:String	Machine understandable type of file (default: “application/octet-stream”)	True
Language	0:String	Used to support multiple languages of the same document	True

Table 125 – FileDescriptor definition

Attribute		Value
BrowseName		2:FileDescriptor
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 126 – CompatibilityOption structure

Name	Type	Description	Optional
CompatibilityOption	0:Structure	One set of compatibility requirements
CompatibilityRequirements[]	2:CompatibilityRequirement	List of requirements: All of them must match to be compatible	False

Table 127 – CompatibilityOption definition

Attribute		Value
BrowseName		2:CompatibilityOption
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 128 – CompatibilityRequirement structure

Name	Type	Description	Optional
CompatibilityRequirement	0:Structure
Variable	0:String	Path to a variable to compare with Examples: variable of a component or its Identification functional group or its parent device or an application on that device…	False
Values[]	0:BaseDataType	Comparison values (zero, one or more values depending on the comparison operator). Can be any Integer or String type.	False
Operation	2:ComparisonOperation	Operation that is used to compare Variable and Values.	False

Table 129 – CompatibilityRequirement definition

Attribute		Value
BrowseName		2:CompatibilityRequirement
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 130 – PackageType Items

Name	Value	Description
Firmware	0	The Software Package contains the firmware of a physical device.
Application	1	The Software Package contains an executable software.
Configuration	2	The Software Package contains the configuration of a device or application.
Solution	3	The Software Package contains a solution with several software package.

Table 131 – PackageType definition

Attribute		Value
BrowseName		2:PackageType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

Table 132 – FileType Items

Name	Value	Description
DeploymentItem	0	This file shall be deployed to the device. If Cached-Loading or Direct-Loading is used at most one file can be marked as DeploymentItem. If File System based Loading is used all files that are marked as DeploymentItem shall be copied to the server using the same file name. If the complete Software Package is deployed to the device the individual files are not marked explicitly.
ReleaseNotes	1	E.g. link for user to open the document
LicenseInfo	2	E.g. link for user to open the document
PreInstallNote	3	Text that shall be shown to the user at least once before installation

Table 133 – FileType definition

Attribute		Value
BrowseName		2:FileType
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

Table 134 – ComparisonOperation Items

Name	Value	Description
EqualTo	0	Value[0] = Variable
GreaterThan	1	Value[0] > Variable (proper comparison for SemanticVersionString shall be supported)
GreaterEqual	2	Value[0] >= Variable (proper comparison for SemanticVersionString shall be supported)
LessThen	3	Value[0] < Variable (proper comparison for SemanticVersionString shall be supported)
LessEqual	4	Value[0] <= Variable (proper comparison for SemanticVersionString shall be supported)
RegularExpression	5	Value[0] contains a regular expression which must match the value of the Variable
OneOf	6	The Values array must contain the value of the Variable
Exist	7	The Node that is described by the Variable must exist. The Values array shall be empty.

Table 135 – ComparisonOperation definition

Attribute		Value
BrowseName		2:ComparisonOperation
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of the 0:Enumeration type defined in OPC 10000-5
0:HasProperty	Variable		0:EnumStrings	0:LocalizedText []	0:PropertyType

The compatibility declaration describes the compatibility of a Software Package with a component on the server that supports the SoftwareUpdate AddIn.

This can be simple terms like a minimum SoftwareRevision or a specific HardwareRevision of the component. Or relations to other objects in the AddressSpace e.g. to describe the existence and version of an attached hardware or to restrict the use of an application to a specific firmware version of a device.

Typically, the compatibility declaration outlines the relationship between variables and the corresponding component on the server. However, certain compatibilities can only be articulated through associated components e.g. the device hosting the application or a necessarily attached hardware. For those cases the compatibility declaration can incorporate paths following the UpdateParentReferenceType references (see 8.6.1).

The UpdateParentReferenceType enables the definition of a tree of object on the server which is utilized to describe compatibility. Parent objects are referenced as “..” while child objects are indicated by the BrowseName of the node being referenced. The elements within this path are interconnected using a slash (“/”).

Examples:

“ManufacturerUri”, “ProductCode”, “SoftwareRevision” identify properties of the component that should be updated.

“../ManufacturerUri” and “../ProductCode” identify a specific parent component (e.g. the device that hosts the application).

“../ProfinetExtension/SoftwareRevision” can identify the firmware version of a hardware which is connected to the parent.

To prove authenticity and integrity the Software Packages can be signed.

Initially the Software Package should be signed by the author (e.g., the manufacturer signs a firmware for its devices when it is created). This signature proves that it is really from that author (authenticity) and that is not altered on the way to the client (integrity) (see use case 8.2.2.20).

The verification of these signatures can be done by the Update Client or by the device if the whole update package is deployed.

Typically, a PKI with a certificate hierarchy is used. In this case, the entire certificate chain shall be stored in the signature. Consequently, only the root certificate is required for verification.

Additional signatures can be added by machine builders or plant operators to approve a Software Package for use in a specific plant. With this in place the Update Client and OPC UA servers can be configured to only allow updates of Software Packages with an approval signature of a specific certificate hierarchy (see use case 8.2.2.21).

To create a signed Software Package, it is stored as a standard ASiC-E (Associated Signature Container) container and signed with a CAdES (CMS Advanced Electronic Signatures) signature.

Note: These *AdES signatures are commonly used for advanced digital signatures in engineering environments. Examples are FDI, Profinet or OPC UA FX descriptors. To be easier usable on constrained devices the Software Packages use the binary CAdES persistence instead of the XML based XAdES. ASiC-E is a minimalistic ZIP container from the same family of standards.

With ASiC-E the folder structure of the ZIP file does not change. ASiC-E adds one additional folder “META-INF” with the signature information and a mimetype file in the root folder. These signatures also remain intact if individual files are removed or if the folders are unzipped.

Depending on the industry and environment where the devices are used there are different requirements to the level of security of the signatures. Therefore, the CAdES signatures support different levels which all can be used for the Software Packages. The more advanced options extend the basic option so that all packages remain compatible and usable with any update client.

For the verification of the signature, all certificates up to the root certificate are required. To ensure ease of handling, the entire certificate chain should therefore be incorporated within the CAdES signature.

All security relevant details are described in the publicly available ETSI standards (see ASiC-E, CAdES).

Note: If the complete Software Package is transferred to the device the verification also shall be done on the device. For this case certificates are distributed and updated on all device in the plant. Solutions for certificate distribution are covered in detail in OPC 10000-12 and OPC 10000-21.

Note: To create and maintain keys and certificates for the signatures, a PKI (public key infrastructure) should be used. Since this has no impact on the singing and verification described in this document, it is out of scope of this specification.

A Solution Package can be used to combine several Software Packages. This can have several reasons:

1. Easier distribution of multiple Software Packages as a single file (e.g., a complete machine with several devices or one device with several updateable components).
2. Only a specific combination of Software Packages shall be installed (could be verified using a signature at the Solution Package).
3. A combination of several Software Packages shall be installed to a device as a single file. The device is then responsible for distribution / installation of the subpackages.

A Solution Package can include an assignment information that declares which subpackage shall be installed to which targets on the device. A target can be either a specific instance or a type. If a type is specified, the package should be installed to all instances of that type. Example: A FieldBus head with OPC UA Server manages the firmware update of the connected IO modules.

A Solution Package also contains the standard package_metadata.json file with manufacturer and optional version information about the solution. Here the PackageType shall be set to Solution.

If there are several components in a Device that support the Software Update the CanUpdateReferenceType can be used to describe which subcomponents can be updated via the Solution Package.

If a precise assignment of the contained Software Packages is required, the Assignments element of the PackageMetadata can be used. The structures for the Assignment are defined in Table 136.

Table 136 – Assignment structure

Name	Type	Description	Optional
Assignment	0:Structure
Subpackage	0:String	Name of the subfolder within the SUBPACKAGES folder.	False
InstallationOrder	0:UInt32	Optional order of installation (lower numbers shall be installed first).	True
Targets[]	2:PackageTarget	List of targets for the Software Package with at least one element.	False

Table 137 – Assignment definition

Attribute		Value
BrowseName		2:Assignment
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 138 – PackageTarget structure

Name	Type	Description	Optional
PackageTarget	0:Structure
TargetType	0:NodeId	Install to all instances of that ObjectType.	True
TargetNode	0:NodeId	Install to specific node on the server.	True
ProductInstanceUri	0:String	Specific target with the ProductInstanceUri (see 4.5.3).	True
AssetId	0:String	Specific target with the AssetId (see 4.5.3).	True
ManufacturerUri	0:String	ManufacturerUri (see 4.5.3).	True
ProductCode	0:String	ProductCode (see 4.5.3).	True
SerialNumber	0:String	SerialNumber (see 4.5.2).	True
FxPath[]	2:FxPathElement	Path to a UA FX Asset (OPC 10000-81).	True
FxScope[]	2:FxPathElement	The package shall only be installed to targets behind this node (OPC 10000-81).	True
BrowsePath[]	0:RelativePathElement	BrowsePath to a concrete target node (see RelativePathElement of OPC 10000-5).	True
TargetServer	0:String	ApplicationUri of a target OPC UA Server.	True

Table 139 – PackageTarget definition

Attribute		Value
BrowseName		2:PackageTarget
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

Table 140 – FxPathElement structure

Name	Type	Description	Optional
FxPathElement	0:Structure	Path based on OPC UA FX AssetConnectorTypes.
AssetConnectorType	0:NodeId	Connector type as defined in OPC 10000-81.Additionally either Id or Name shall be specified.	False
ConnectorId	0:UInt16	Id of the connector.	True
ConnectorName	0:String	Name of the connector.	True

Table 141 – FxPathElement definition

Attribute		Value
BrowseName		2:FxPathElement
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Other
Subtype of 0:Structure defined in OPC 10000-3

PackageTarget can describe either a single or multiple targets for the subpackage. For example, TargetType describes multiple targets (all instances of that ObjectType), while the combination of SerialNumber, ProductCode, and ManufacturerUri uniquely identifies a single target. The following options can be used to filter the list of targets:

1. If no target is specified, the subpackage shall be installed on all matching target nodes.
2. If a TargetType is specified, all targes that are subtypes of the specified ObjectType shall be updated.
3. If a TargetNode is specified, only this node shall be updated.
4. If a ProductInstanceUri is specified, only the target with the specified ProductInstanceUri in its IVendorNameplateType shall be updated.
5. If AssetId is specified, only the target with the specified AssetId in its ITagNameplate shall be updated.
6. If ManufacturerUri and ProductCode are specified, all targets identified with these properties in its IVendorNameplateType shall be updated.
7. If ManufacturerUri, ProductCode and SerialNumber are specified, only the target identified with these properties in its IVendorNameplateType shall be updated.
8. If an FxPath is specified, the target is identified following the AssetConnectors (see OPC 10000-81) identified by its type and either its Id or its Name.
9. If AssetsTypes of OPC 10000-81 are used, TargetScope can be used to restrict the installation to targets which are connected to that asset. This can, for example, be combined with FxPath.
10. If a TargetBrowsePath is specified, the target is identified by the specified path. This path starts at the Objects Node and shall only result in a single node.

If the distribution of the packages is done by the Update Client and the package shall be installed on a specific server, the TargetServer contains the ApplicationUri of that server.