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 |
||
|
2 |
||
|
3 |
||
|
12 |
||
|
21 |
||
|
23 |
||
|
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. |