The SoftwareUpdateTypedefines an AddInwhich may be used to extend Objectswith software update features. All software update options are exposed as references of this AddIn. This way a Clientcan 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 SoftwareUpdateTypeis illustrated in Figure 41and formally described in Table 65.

image044.png

Figure 41– SoftwareUpdateType

Table 65– SoftwareUpdateType definition

Attribute

Value

BrowseName

SoftwareUpdateType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the BaseObjectTypedefined in OPC 10000-5.

HasComponent

Object

Loading

SoftwareLoadingType

Optional

HasComponent

Object

PrepareForUpdate

PrepareForUpdateStateMachineType

Optional

HasComponent

Object

Installation

InstallationStateMachineType

Optional

HasComponent

Object

PowerCycle

PowerCycleStateMachineType

Optional

HasComponent

Object

Confirmation

ConfirmationStateMachineType

Optional

HasComponent

Object

Parameters

TemporaryFileTransferType

Optional

HasComponent

Variable

UpdateStatus

LocalizedText

BaseDataVariableType

Optional

HasComponent

Variable

VendorErrorCode

Int32

BaseDataVariableType

Optional

HasProperty

Variable

0:DefaultInstanceBrowseName

QualifiedName

PropertyType

Conformance Units

DI SU Software Update

The optional Loading Objectis of type SoftwareLoadingType, whichisabstract. The Objectcan be one of the concrete sub-types DirectLoadingType (8.4.4), CachedLoadingType (8.4.5) or FileSystemLoadingType (8.4.6). SoftwareLoadingTypeis formally defined in 8.4.2.

The Loading Objectis 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 Objectis of type PrepareForUpdateStateMachineTypewhich is formally defined in 8.4.8.

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

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

This optional Confirmation Objectis of type ConfirmationStateMachineTypewhich is formally defined in 8.4.11.

This optional Parameters Objectis of type TemporaryFileTransferType (OPC 10000-5). It may be supported by devices that cannot retain parameters during update. If supported by the SoftwareUpdate AddIna 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 GenerateFileForReadand GenerateFileForWrite Methodsaccept an unspecified generateOptions Parameter. This argument is not used, and Clientsshall always pass null. Future versions of this specification may 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 may 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 Servermay 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 UpdateStatusmay be used together with the PrepareForUpdateStateMachineType (8.4.8), the InstallationStateMachineType (8.4.9) and for CachedLoadingType (8.4.5), DirectLoadingType (8.4.4) and FileSystemLoadingType(8.4.6) it may be used during the transfer of the Software Package.

The optional VendorErrorCode Propertyprovides a machine-readable error code in case anything went wrong during the transfer, the installation or the preparation. Comparable to an error message in UpdateStatusthis Variablecan provide additional information about the issue. The VendorErrorCodeis 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 may be used together with the PrepareForUpdateStateMachineType (8.4.8) for prepare and resume, in theInstallationStateMachineType (8.4.9) during the installation. For CachedLoadingType (8.4.5), DirectLoadingType (8.4.4) and FileSystemLoadingType (8.4.6) it may be used during the transfer of the Software Package.

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

Table 66– SoftwareUpdateType Attribute values for child Nodes

Source Path

Value

0:DefaultInstanceBrowseName

SoftwareUpdate

The SoftwareLoadingTypeis 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 71.

Table 67– SoftwareLoadingType definition

Attribute

Value

BrowseName

SoftwareLoadingType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the BaseObjectTypedefined in OPC 10000-5

HasSubtype

ObjectType

PackageLoadingType

HasSubtype

ObjectType

FileSystemLoadingType

HasComponent

Variable

UpdateKey

String

BaseDataVariableType

Optional

Conformance Units

DI SU Software Update

The optional write-only UpdateKey Objectcan 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 UpdateKeyis supported, the Clientshall set the key before the installation. If the PrepareForUpdateStateMachineis used, the UpdateKeyshall be set before the Prepare Methodis called. The Servershall not keep the value for more than one update.

The PackageLoadingTypeprovides information about the Current Versionand allows transfer of a Software Packageto and from the Server.

The PackageLoadingType is illustrated in Figure 42and formally defined in Table 68.

image045.png

Figure 42– PackageLoadingType

Table 68– PackageLoadingType definition

Attribute

Value

BrowseName

PackageLoadingType

IsAbstract

True

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the SoftwareLoadingType

HasComponent

Object

CurrentVersion

SoftwareVersionType

Mandatory

HasComponent

Object

FileTransfer

TemporaryFileTransferType

Mandatory

HasComponent

Variable

ErrorMessage

LocalizedText

BaseDataVariableType

Mandatory

HasProperty

Variable

WriteBlockSize

UInt32

PropertyType

Optional

HasSubtype

ObjectType

DirectLoadingType

HasSubtype

ObjectType

CachedLoadingType

Conformance Units

DI SU Software Update

To identify the Current Version, the CurrentVersion Objectprovides ManufacturerUri, SoftwareRevisionand PatchIdentifiersalong with other information that allows the user to identify the currently used software. With this information the Clientcan determine a suitable update.

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

The FileTransfer Objectis of type TemporaryFileTransferTypeas defined in OPC 10000-5. It is used to create temporary files for download and upload of the software.

In the TemporaryFileTransferTypetype the GenerateFileForReadand GenerateFileForWrite Methodstake an unspecified generateOptions Parameter. For the FileTransfer Objectan Enumerationof type SoftwareVersionFileTypeis used for this Parameter. It is used to select the file to upload or download. All allowed values are defined in Table 86. Additional Result Codesof the GenerateFileForReadand GenerateFileForWrite Methodsare specified in Table 69.

Table 69– TemporaryFileTransferType Result Codes

Result Code

Description

Bad_InvalidState

If the PrepareForUpdateis available, the UpdateBehaviorrequires preparation and the PrepareForUpdatestate 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 theErrorMessage Variableshould provide an error message for the user.

It is implementation dependent which version (see SoftwareVersionFileTypein 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 WriteBlockSizeis supported, the Clientshall 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,theCloseAndCommit Methodor an asynchronous completion of the file transfer. If the validation is performed synchronous, the Methodreturns Bad_InvalidArgument; if the validation is performed asynchronous, the error is indicated by the Errorstate of the FileTransferStateMachineType. If the ErrorMessage Variableis provided, it shall contain an error message representing the validation error.

The FileTransfer Objectmay optionally support the transfer of a Software Packagefrom the device to the Client.

If this transfer is not supported, the Servershall return the Result Code Bad_NotSupported. If it is supported but there is currently no data, the Result Code Bad_NotFoundshall 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 Variableshould 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 Clientshall write to the file. The client shall write the Software Packagein chunks of this size to the FileTypeobject (the last block may be smaller).

The DirectLoadingTypeprovides information about the Current Versionand allows transfer of a Software Packageto and from the Server. Transfer of the Software Packageto the Serveralso includes the installation. The Direct-Loadingoption is described in 8.3.4.3.

The DirectLoadingType is illustrated in Figure 43and formally defined in Table 70.

image046.png

Figure 43– DirectLoadingType

Table 70– DirectLoadingType definition

Attribute

Value

BrowseName

DirectLoadingType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the PackageLoadingType

HasComponent

Variable

UpdateBehavior

UpdateBehavior

BaseDataVariableType

Mandatory

HasProperty

Variable

WriteTimeout

Duration

PropertyType

Optional

Conformance Units

DI SU DirectLoading

The FileTransfer Objectis inherited from the PackageLoadingType. In this sub-type the Current versionshall be writable (see SoftwareVersionFileTypein 8.5.1). Writing to this file also includes the actual installation.

The UpdateBehavior OptionSetinforms the update Clientabout the specific behavior of the component during update via Direct-Loading.

Optional Propertythat informs the Clientabout the maximum duration of the call to the Write Methodof FileType(maximum time the write of a block of data can take). If the write operation takes longer the Clientcan assume that the Serverhas an issue.

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

The CachedLoadingTypeis illustrated in Figure 44and formally defined in Table 71.

image047.png

Figure 44– CachedLoadingType

Table 71– CachedLoadingType definition

Attribute

Value

BrowseName

CachedLoadingType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the PackageLoadingType

HasComponent

Object

PendingVersion

SoftwareVersionType

Mandatory

HasComponent

Object

FallbackVersion

SoftwareVersionType

Optional

HasComponent

Method

GetUpdateBehavior

Mandatory

Conformance Units

DI SU CachedLoading

The FileTransfer Objectis inherited from the PackageLoadingType. In this sub-type the Current versionshall not be writable and the Pending versionshall be writable (see SoftwareVersionFileTypein 8.5.1).

The PendingVersion Objectdescribes an already transferred new Software Packagethat is ready to be installed.

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

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

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

With this Methodthe Clientmay check the specific update behavior for a specified software version. To identify the version the GetUpdateBehavior Methodrequires the ManufacturerUri, SoftwareRevision and PatchIdentifiers Propertiesof the SoftwareVersionType.

Signature

GetUpdateBehavior(

[in]String ManufacturerUri,

[in]String SoftwareRevision,

[in]String[] PatchIdentifiers,

[out]UpdateBehaviorUpdateBehavior);

Argument

Description

ManufacturerUri

ManufacturerUri Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed.

SoftwareRevision

SoftwareRevision Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed.

PatchIdentifiers

PatchIdentifiers Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed. (or empty array if not supported by the SoftwareVersionTypeinstance)

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.

The FileSystemLoadingTypeenables software update based on an open file system. This enables the FileSystem based Loadingoption of 8.3.4.5.

It is illustrated in Figure 45and formally defined in Table 72.

image048.png

Figure 45– FileSystemLoadingType

Table 72– FileSystemLoadingType definition

Attribute

Value

BrowseName

FileSystemLoadingType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the SoftwareLoadingType

HasComponent

Object

0:FileSystem

0:FileDirectoryType

Mandatory

HasComponent

Method

GetUpdateBehavior

Mandatory

HasComponent

Method

ValidateFiles

Optional

Conformance Units

DI SU FileSystem Loading

The FileSystem Objectis of type FileDirectoryTypeas it is defined in OPC 10000-5. It provides access to a hierarchy of directories and files of the device. The structure may be read and written by the Clienthowever the device may restrict this for specific folders or files.

This Methodmay be used to check the specific update behavior for a set of files. The files are identified by the NodeIdof their FileTypeinstance in the FileSystem.

Signature

GetUpdateBehavior(

[in] NodeId[] NodeIds,

[out]UpdateBehaviorUpdateBehavior);

Argument

Description

NodeIds

NodeIds of the files to install.

UpdateBehavior

Update behavior OptionSetfor the files specified by NodeId

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_NotFound

If one or more NodeIdsare not found.

This Methodmay 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-Loadingor Cached-Loadingthese 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] NodeId[]NodeIds,

[out]ErrorCodeInt32,

[out]ErrorMessageLocalizedText);

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 NodeIdsare not found.

The SoftwareVersionTypeidentifies 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 Attributeon the instances of the SoftwareVersionTypeshould be used to provide additional information about the concrete version of the software to the user (e.g. change notes).

The SoftwareVersionTypeis illustrated in Figure 46and formally defined in Table 73.

image049.png

Figure 46– SoftwareVersionType

Table 73– SoftwareVersionType definition

Attribute

Value

BrowseName

SoftwareVersionType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the BaseObjectTypedefined in OPC 10000-5

HasProperty

Variable

Manufacturer

LocalizedText

PropertyType

Mandatory

HasProperty

Variable

ManufacturerUri

String

PropertyType

Mandatory

HasProperty

Variable

SoftwareRevision

String

PropertyType

Mandatory

HasProperty

Variable

PatchIdentifiers

String[]

PropertyType

Optional

HasProperty

Variable

ReleaseDate

DateTime

PropertyType

Optional

HasProperty

Variable

ChangeLogReference

String

PropertyType

Optional

HasProperty

Variable

Hash

ByteString

PropertyType

Optional

Conformance Units

DI SU Software Update

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

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

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

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

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

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

The read only PatchIdentifiers Propertyidentifies 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 Propertydefines 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 Propertymay 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 Propertymay be read by a Clientto get the hash of a previously transferred Software Package. The hash value needs to be calculated by the Serverwith the SHA-256 algorithm. It can be used to verify if the transferred package matches the one at the Client.

The PrepareForUpdateStateMachineTypemay 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 Serverimplements this state machine, a Clientshall use it except if the UpdateBehaviorindicates that this is not necessary for the transferred software. If preparation is required, the installation is only allowed if the PrepareForUpdateStateMachineis in the PreparedForUpdatestate.

The state machine is illustrated in Figure 47, Figure 48and formally defined in Table 74. The transitions are formally defined in Table 76.

image050.png

Figure 47– PrepareForUpdate state machine

image051.png

Figure 48– PrepareForUpdateStateMachineType

Table 74– PrepareForUpdateStateMachineType definition

Attribute

Value

BrowseName

PrepareForUpdateStateMachineType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the FiniteStateMachineTypedefined in OPC 10000-5.

HasComponent

Variable

PercentComplete

Byte

BaseDataVariableType

Optional

HasComponent

Method

Prepare

Mandatory

HasComponent

Method

Abort

Mandatory

HasComponent

Method

Resume

Optional

HasComponent

Object

Idle

InitialStateType

HasComponent

Object

Preparing

StateType

HasComponent

Object

PreparedForUpdate

StateType

HasComponent

Object

Resuming

StateType

HasComponent

Object

IdleToPreparing

TransitionType

HasComponent

Object

PreparingToIdle

TransitionType

HasComponent

Object

PreparingToPreparedForUpdate

TransitionType

HasComponent

Object

PreparedForUpdateToResuming

TransitionType

HasComponent

Object

ResumingToIdle

TransitionType

Conformance Units

DI SU PrepareForUpdate

The component Variablesof the PrepareForUpdateStateMachineTypehave additional Attributesdefined in Table 75.

Table 75– PrepareForUpdateStateMachineType Attribute values for child Nodes

BrowsePath

Value Attribute

Idle

0:StateNumber

1

Preparing

0:StateNumber

2

PreparedForUpdate

0:StateNumber

3

Resuming

0:StateNumber

4

IdleToPreparing

0:TransitionNumber

12

PreparingToIdle

0:TransitionNumber

21

PreparingToPreparedForUpdate

0:TransitionNumber

23

PreparedForUpdateToResuming

0:TransitionNumber

34

ResumingToIdle

0:TransitionNumber

41

Table 76– PrepareForUpdateStateMachineType Additional References

SourceBrowsePath

Reference Type

Is Forward

TargetBrowsePath

Transitions

IdleToPreparing

FromState

True

Idle

ToState

True

Preparing

HasEffect

True

TransitionEventType

PreparingToIdle

FromState

True

Preparing

ToState

True

Idle

HasEffect

True

TransitionEventType

PreparingToPreparedForUpdate

FromState

True

Preparing

ToState

True

PreparedForUpdate

HasEffect

True

TransitionEventType

PreparedForUpdateToResuming

FromState

True

PreparedForUpdate

ToState

True

Resuming

HasEffect

True

TransitionEventType

ResumingToIdle

FromState

True

Resuming

ToState

True

Idle

HasEffect

True

TransitionEventType

This percentage is a number between 0 and 100 that informs about the progress in the Preparingor the Resuming States. It may be used whenever the activity takes longer and the user should be informed about the completion. If the state machine is in Idleor PreparedForUpdate Stateit shall have the value 0.

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

The Prepare Methodmay 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 may 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.

If the preparation takes too long or does not complete at all because the required internal conditions are not met the Abort Methodmay be called to abort the preparation. This call transitions the device back to the Idlestate.

Note: If the transition from Preparingto Idlecannot complete instantly a Clientneeds to 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 Methodtransitions the device into the state Resuming. After the resuming is complete the state machine performs an automatic transition to the Idlestate. If the method is not supported, the transitions to Resumingand back to Idleshall be done by the Serverautomatically. If the method is supported, there shall not be an automatic transition to Resuming.Supporting this method enables the Clientto 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 InstallationStateMachineTypemay be used if the device supports explicit installation (Cached-Loadingor File System based Loading). This supports the installation option of 8.3.4.6. It is illustrated in Figure 49and Figure 50and formally defined in Table 77. The transitions are formally defined in Table 79.

image052.png

Figure 49– Installation state machine

image053.png

Figure 50– InstallationStateMachine

Table 77– InstallationStateMachineType definition

Attribute

Value

BrowseName

InstallationStateMachineType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the FiniteStateMachineTypedefined in OPC 10000-5.

HasComponent

Variable

PercentComplete

Byte

BaseDataVariableType

Optional

HasComponent

Variable

InstallationDelay

Duration

BaseDataVariableType

Optional

HasComponent

Method

InstallSoftwarePackage

Optional

HasComponent

Method

InstallFiles

Optional

HasComponent

Method

Resume

Mandatory

HasComponent

Object

Idle

InitialStateType

HasComponent

Object

Installing

StateType

HasComponent

Object

Error

StateType

HasComponent

Object

IdleToInstalling

TransitionType

HasComponent

Object

InstallingToIdle

TransitionType

HasComponent

Object

InstallingToError

TransitionType

HasComponent

Object

ErrorToIdle

TransitionType

Conformance Units

DI SU Software Update

The component Variablesof the InstallationStateMachineTypehave additional Attributesdefined in Table 78.

Table 78– InstallationStateMachineType Attribute values for child Nodes

BrowsePath

Value Attribute

Idle

0:StateNumber

1

Installing

0:StateNumber

2

Error

0:StateNumber

3

IdleToInstalling

0:TransitionNumber

12

InstallingToIdle

0:TransitionNumber

21

InstallingToError

0:TransitionNumber

23

ErrorToIdle

0:TransitionNumber

31

Table 79– InstallationStateMachineType Additional References

SourceBrowsePath

Reference Type

Is Forward

TargetBrowsePath

Transitions

IdleToInstalling

FromState

True

Idle

ToState

True

Installing

HasEffect

True

TransitionEventType

InstallingToIdle

FromState

True

Installing

ToState

True

Idle

HasEffect

True

TransitionEventType

InstallingToError

FromState

True

Installing

ToState

True

Error

HasEffect

True

TransitionEventType

ErrorToIdle

FromState

True

Error

ToState

True

Idle

HasEffect

True

TransitionEventType

This percentage is a number between 0 and 100 that informs the user about the progress of an installation. 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 Stateit shall have the value 0. In case of an error the last value should be kept until the Resumeis called.

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

The optional InstallationDelaycan be set by a Clientto delay the actual installation after the call to InstallSoftwarePackageor InstallFilesis 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 InstallationDelaydoes not delay the transition from Idleto Installing.

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

The Serveris expected to stay operational at least during the delay.

With this Methodthe Clientrequests the installation of a Software Package. The package can be either the previously transferred Pending Versionor the alternative Fallback Version. To identify the version and to prevent conflicts with a second Clientthat transfers a different version, the InstallSoftwarePackage Methodneeds the ManufacturerUri, the SoftwareRevision and PatchIdentifiers Propertiesof the SoftwareVersionType.

Optionally an additional hash value may be passed to the Method. This hash could be calculated by the Clientor taken from a trusted source. Before installation the Servermay compare the hash against the calculated hash of the Software Package. This mechanism can be used if there is a risk that the Software Packageis altered during the transfer to the device and if the Serverhas no other mechanism to ensure that the Software Packageis 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 Methodshall not return before the state has changed to the Installingstate.

Signature

InstallSoftwarePackage(

[in] String ManufacturerUri,

[in] String SoftwareRevision,

[in] String[]PatchIdentifiers,

[in] ByteString Hash);

Argument

Description

ManufacturerUri

ManufacturerUri Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed.

SoftwareRevision

SoftwareRevision Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed.

PatchIdentifiers

PatchIdentifiers Property of either the Pendingor Fallback SoftwareVersionTypethat should be installed. (or empty array if not supported on the SoftwareVersionType instance).

Hash

Hash of the Software Packagethat should be installed (or empty if not used).

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidState

If the InstallationStateMachineTypeis not in Idlestate or if the PrepareForUpdate Objectis available and the PrepareForUpdatestate machine is not in the state PreparedForUpdate.

Bad_NotFound

If the specified Software Packagedoes not exist.

Bad_InvalidArgument

If the Hash does not match the calculated hash of the Software Package.

This Methodmay be called to request the installation of one or more files. The files are identified by the NodeIdof their FileTypeinstance 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] NodeId[] NodeIds);

Argument

Description

NodeIds

NodeIds of the files to install.

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidState

If the InstallationStateMachineTypeis not in Idlestate or if the PrepareForUpdate Objectis available and the PrepareForUpdatestate machine is not in the state PreparedForUpdate.

Bad_NotFound

If one or more NodeIds are not found.

This Methodmay be called to resume from the Errorstate. The Errorstate can be reached if there are issues during the installation. The state machine remains in this state until the Clientcalls the Resume Methodto get back to the Idlestate immediately.

Signature

Resume();

Method Result Codes (defined in Call Service)

Result Code

Description

Bad_InvalidState

If the InstallationStateMachineTypeis not in Error state.

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

When the server needs a manual power cycle it indicates that to the client by changing the state to WaitingForPowerCycle. After restart of the device it transitions to NotWaitingForPowerCycleautomatically.

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

image054.png

Figure 51– PowerCycle state machine

Table 80– PowerCycleStateMachineType definition

Attribute

Value

BrowseName

PowerCycleStateMachineType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the FiniteStateMachineTypedefined in OPC 10000-5.

HasComponent

Object

NotWaitingForPowerCycle

InitialStateType

HasComponent

Object

WaitingForPowerCycle

StateType

HasComponent

Object

NotWaitingForPowerCycleToWaitingForPowerCycle

TransitionType

HasComponent

Object

WaitingForPowerCycleToNotWaitingForPowerCycle

TransitionType

Conformance Units

DI SU Manual Power Cycle

The component Variablesof the PowerCycleStateMachineTypehave additional Attributesdefined in Table 81.

Table 81– PowerCycleStateMachineType Attribute values for child Nodes

BrowsePath

Value Attribute

NotWaitingForPowerCycle

0:StateNumber

1

WaitingForPowerCycle

0:StateNumber

2

NotWaitingForPowerCycleToWaitingForPowerCycle

0:TransitionNumber

12

WaitingForPowerCycleToNotWaitingForPowerCycle

0:TransitionNumber

21

Table 82– PowerCycleStateMachineType Additional References

SourceBrowsePath

Reference Type

Is Forward

TargetBrowsePath

Transitions

NotWaitingForPowerCycleToWaitingForPowerCycle

FromState

True

NotWaitingForPowerCycle

ToState

True

WaitingForPowerCycle

HasEffect

True

TransitionEventType

WaitingForPowerCycleToNotWaitingForPowerCycle

FromState

True

WaitingForPowerCycle

ToState

True

NotWaitingForPowerCycle

HasEffect

True

TransitionEventType

The ConfirmationStateMachineTypeis used to prove a valid Client – Serverconnection 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 ConfirmationStateMachineTypeis illustrated in Figure 52and Figure 53and formally defined in Table 83. The transitions are formally defined in Table 85.

image055.png

Figure 52– Confirmation state machine

image056.png

Figure 53– ConfirmationStateMachineType

Table 83– ConfirmationStateMachineType

Attribute

Value

BrowseName

ConfirmationStateMachineType

IsAbstract

False

References

NodeClass

BrowseName

DataType

TypeDefinition

ModellingRule

Subtype of the FiniteStateMachineTypedefined in OPC 10000-5.

HasComponent

Method

Confirm

Mandatory

HasComponent

Variable

ConfirmationTimeout

Duration

BaseDataVariableType

Mandatory

HasComponent

Object

NotWaitingForConfirm

InitialStateType

HasComponent

Object

WaitingForConfirm

StateType

HasComponent

Object

NotWaitingForConfirmToWaitingForConfirm

TransitionType

HasComponent

Object

WaitingForConfirmToNotWaitingForConfirm

TransitionType

Conformance Units

DI SU Update Confirmation

The component Variablesof the ConfirmationStateMachineTypehave additional Attributesdefined in Table 84.

Table 84– ConfirmationStateMachineType Attribute values for child Nodes

BrowsePath

Value Attribute

NotWaitingForConfirm

0:StateNumber

1

WaitingForConfirm

0:StateNumber

2

NotWaitingForConfirmToWaitingForConfirm

0:TransitionNumber

12

WaitingForConfirmToNotWaitingForConfirm

0:TransitionNumber

21

Table 85– ConfirmationStateMachineType TargetBrowsePath

SourceBrowsePath

Reference Type

Is Forward

TargetBrowsePath

Transitions

NotWaitingForConfirmToWaitingForConfirm

FromState

True

NotWaitingForConfirm

ToState

True

WaitingForConfirm

HasEffect

True

TransitionEventType

WaitingForConfirmToNotWaitingForConfirm

FromState

True

WaitingForConfirm

ToState

True

NotWaitingForConfirm

HasEffect

True

TransitionEventType

The ConfirmationTimeout may be set by a Clientto a value other then 0 to enable the confirmation feature. If the value is not 0 and the ClientServerconnection is lost, the ConfirmationTimeoutrepresents the maximum time that the Clientmay need to reconnect and call the Confirm Method. The Servershall automatically reset the value to 0 when the installation is complete.

After a reboot and with a ConfirmationTimeoutother than 0 a Clientshall call this Methodto inform the Serverthat it has successfully reconnected. If this Methodis not called after a lost connection the Servershall regard the update as unsuccessful and shall revert it. A Clientneeds to react within the time specified in the ConfirmationTimeout Variable.

Signature

Confirm();