This Annex includes examples referenced in the normative sections.
The examples in Figure B.1 and Figure B.2 illustrate the use of FunctionalGroups:
Figure B.1 – Analyser Device use for FunctionalGroups
Figure B.2 – PLCopen use for FunctionalGroups
The Properties of a TopologyElement, like Manufacturer, SerialNumber, will usually be sufficient as identification. If other Parameters or even Methods are required, all required elements shall be organized in a FunctionalGroup called Identification. Figure B.3 illustrates the Identification FunctionalGroup with an example.
Note that companion standards are expected to define the Identification contents for their model.
Figure B.3 – Example of an Identification FunctionalGroup
The software update model provides several options and variants for advanced use cases. The Update Client must be prepared for the option that the server provides (see 8.3.4.1) and how the concrete update behaves (see 8.3.8).
This example shows a typical application for a simple server with a minimal implementation. The subsequent examples additionally address generic clients and describe all the optional parts that can be supported.
This example uses the Cached-Loading option. If the memory is limited and the installation can be done during the transfer of the Software Package, the Direct-Loading model is another simple option.
First the client determines what version is currently installed by reading the Properties of CurrentVersion of the Loading object.
Then the client can transfer the Software Package to the device using the Loading.FileTransfer object. At the end of the transfer the server checks whether the new Software Package is compatible (FileTransfer.CloseAndCommit).
With a call to InstallSoftwarePackage() of the Installation state machine the actual installation is started. The end of the installation could be an automatic reboot of the device or the state machine transitions back to Idle. A transition to Error would indicate an issue during the installation.
During the whole installation, the progress and error messages for the user can be determined subscribing the UpdateStatus property.
To verify if the update was success the client verifies that Loading.CurrentVersion now describes the desired updated version.
Figure B.4 – Example of simple update sequence
This example illustrates the use of software update of several devices from the Client point of view.
This is only one example for a specific domain. There will be different Clients for different types of systems or industries (e.g., for process domain the process will not be stopped and before a sensor is updated a replacement value is configured in the controller).
The example (illustrated in Figure B.5) describes a production line with several production cells. Each cell contains a robot and a main PLC that can be updated. A switch connects the cells and is also updateable via OPC UA.
A Client would perform the following steps:
- Analyze the system
An example sequence of Direct-Loading is shown in Figure B.6.
If the Server does not implement the properties PrepareForUpdate, PowerCycle or Parameters of the SoftwareUpdateType, the associated options are not supported by the component and Client-Server interaction becomes simpler.
In the first steps the device identity and the kind of supported Server options of the device must be discovered as described in Figure 35.
How to look up and transfer files for an installation is described in Figure 36.
The preparation can be done as described in Figure 37.
The installation itself is described in Figure 38.
Figure B.6 – Example sequence of Direct-Loading
An example sequence of Cached-Loading is shown in Figure B.7.
If the Server does not implement the properties PrepareForUpdate, PowerCycle or Parameters of the SoftwareUpdateType, the associated options are not supported by the component and Client-Server interaction becomes simpler.
In the first steps the device identity and the kind of supported Server options of the device must be discovered as described in Figure 35.
How to look up and transfer files for an installation is described in Figure 36.
The preparation can be done as described in Figure 37.
The installation itself is described in Figure 39.
Figure B.7 – Example sequence of Cached-Loading
An example sequence of File System based Loading is shown in Figure B.8.
In this example the server provides the PrepareForUpdate state machine and a preparation for an installation can only be done locally at the device. So, the Resume activity described in Figure 39 cannot be commanded by a Client.
In the first steps the device identity and the kind of supported Server options of the device must be discovered as described in Figure 35.
How to look up and transfer files for an installation is described in Figure 36.
The preparation can be done as described in Figure 37.
The installation itself is described in Figure 39.
Figure B.8 – Example sequence of File System based Loading
This example explains how an optimized firmware update for a modular device or machine can look like. Therefore, multiple firmware packages are gathered into one solution package and send to the OPC UA server all at once to avoid multiple transfer sequences.
A modular or complex device or a machine are consisting of several modules, components or sub-devices. Each of them has their own firmware (or even configuration). In the traditional way each of them has an own instance of the SoftwareUpdateType object and each of them requires a download and install activity for the firmware. This can lead to duplicated download firmware package and/or often executed sequentially, means each firmware packages are transferred separately by opening each a new connection/channel for the download, which takes a lot of time in cases of larger installations.
Following a standardized way of managing modular devices or device with multiple content to loaded all at once:
- Create a solution package see 8.7.5 to put all firmware, configuration or application into one package.
- The UA server contains a SoftwareUpdateType instance which is classified as SoftwareClass Solution to identify that a solution package download/handling is supported. The object has the loading type FileSystemLoadingType, due to optional version as a solution package may not have a version number.. The version check will be done with ValidateFiles operation, where device will check each sub-package against the assigned information.
Example of a UA address space “Modular Device”:
Figure B.9: Solution Package example “Modular Device”.
Figure B.10: UA address space example for the server “Modular Device”.
Example of a UA address space “Single Device”:
Figure B.11: Solution Package example “Single Device”.
Figure B.12: UA address space example for the server “Single Device”.
Example of a UA solution package metadata “Single Device” showing the assignment:
Figure B.13: Solution package metadata "Single Device” example
Figure B.14: Update sequence for a modular device using a solution package.
Steps of the workflow:
- Connect to the device via the UA server.
- The client finds the entry point of the modular device, that can happen by:
- Knowing the structure such as UADI:DeviceType or UAFX:AssetType
- Finding the object with software class “Solution” behind,
- In cases of a sever hosting multiple devices, the user selects the right one or the client knows the identification of the target device.
- Browse the references CanUpdate of the “Solution” object to know devices can be updated via a solution package. Afterwards read the identification of the linked modules.
- Check the flag “UnsignedPackagesAllowed” to know if a solution package is required to be signed.
- User selects the FW version or config/application and modules/targets that should be updated.
- Client creates a new solution package with the selected content. It includes:
- Creating of the solution package and pack the sub-packages into it.
- Creating a package metadata file that contains the assignment information.
- Optionally sign the solution package with a customer provided certificate or service.
- Client downloads the solution package to the device.
- Device is doing an overall check on the package level if its valid and intended for this device.
- Optional checking the package signature
- Client calls ValidateFiles to trigger a check of the metadata data about assignments
- For the successful matched elements, the sub-packages are copied or linked to the SoftwareUpdate instances of each device into the PendingVersion.
- Server is returning the info which elements are ready for update and which are not supported
- Client tiggers the installation process by calling InstallSoftwareFiles. This triggers the real installation process on the device side.
- Device is installing the selected version. That can happen in parallel or sequential or combined way depending on the device capabilities. This is up to the devices.
- Client is subscribing to [a] or/and [b] to get progress and status of the installation process.
- A global event (aggregates all progress and status updates via the module and update ID, so that the client can see the details on module is referred)
- Each individual module
- Device is sending the progress and status information.
- After client received the message for end of installation, he is reading the module identification with software revision to check if installation was really successful.
A 3 rd instance has created a solution package. The assignment of sub-packages to target modules is in the package metadata.
Variation 1: The tool knows the solution package format and can check metadata and signature. The solution package is a Whitebox for the tool and the tool can make a pre-check on matching and compatibility before downloading the solution package to the device.
Figure B.15: Update sequence for a modular device using an imported solution package.
Variation 2: The tools is not able to process the solution package (unknown format), it can’t check the package and it’s package metadata. The solution package is a Blackbox for the tool. The solution package is loaded to the device without any pre-check, may the selection to target device needs to be done manually, and device is take over this part of doing match and compatibility check directly after receiving the solution package.
Figure B.16: Update sequence for a modular device using unknow solution package.
Variation 3: The tool knows the solution package format and can check metadata and signature. But in the package, there may be some sub-packages which the format is unknown (proprietary) to the tool, The tool can’t process the sub-package and its metadata.
The main idea of the solution package is to create a consistent description of all the content that is gathered within the package to be able to do a pre-check before sending any content to a target, means there should be some description of each subpackage in terms of what it is and what to be checked by the tool to enable a successful execution of the package on the target.
Therefore, the unknown (proprietary) content or package need to be descripted at least with a minimal set of parameters. A full and final check needs to be done anyhow by the target itself. That means creating a kind of wrapper to this UA package format by adding a package metadata file, containing at least the minimal set of information to a description about what the package is and for whom is it made for.
Figure B.17: Example of wrapping an unknown content within a solution package
In case a solution Package is NOT signed, due to:
- the user doesn’t have the certificate from the device (individual creation of a solution package at customer site by the customer to update).
- the device using customer specific certificates (tool that creates the solution package may not have access to these certificates).
- no PKI infrastructure is available.
It represents a potential security risk and to mitigates it, following considerations has been done:
- Sub-package(s) itself are still signed by the vendor such as firmware packages, means no execution of unsigned data in the server though the sub packages. Sub-packages that can’t be signed by the vendor like configurations or applications, shall be signed by the customer or the tool shall inform the user about a usage unsigned content in a sub-package.
- Trust relation between tool and server is in place based on UA connections and sessions.
- Solution packages is created by the tool that has this trust relation.
- For 3rd instance created packages that has been imported, the tool should inform user Users shall be informed about possible risks when using this option of unsigned solution packages. (Informative)
Instruction for the need that a solution package must be signed:
- Use an attribute “UnsignedPackagesAllowed” and set value to “FALSE”.
- Implement recommended security settings and behaviour that only an admin or security expert can change this setting