8 Software update model ToC Previous Next

8.4 ObjectTypes ToC Previous Next

8.4.9 InstallationStateMachineType ToC Previous Next

8.4.9.1 Overview ToC Model

The InstallationStateMachineType may 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 49 and Figure 50 and formally defined in Table 77. The transitions are formally defined in Table 79.

readme_files/image051.png Figure 49 – Installation state machine

readme_files/image052.png Figure 50 – InstallationStateMachine

Table 77 – InstallationStateMachineType definition

Attribute Value        
BrowseName InstallationStateMachineType        
IsAbstract False        
References Node Class BrowseName DataType TypeDefinition ModellingRule
Subtype of the FiniteStateMachineType defined 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 Variables of the InstallationStateMachineType have additional Attributes defined 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

8.4.9.2 PercentComplete ToC

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 State it shall have the value 0. In case of an error the last value should be kept until the Resume is called.

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

8.4.9.3 InstallationDelay ToC

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.

8.4.9.4 InstallSoftwarePackage Method ToC

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 needs the ManufacturerUri, the SoftwareRevision and PatchIdentifiers Properties of the SoftwareVersionType.

Optionally an additional hash value may be passed to the Method. This hash could be calculated by the Client or taken from a trusted source. Before installation the Server may 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] String		ManufacturerUri,
[in] String		SoftwareRevision,
[in] String[]	PatchIdentifiers,
[in] ByteString   Hash);
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.

8.4.9.5 InstallFiles Method ToC

This Method may 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] 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 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.

8.4.9.6 Resume Method ToC

This Method may 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.

Previous Next