< PreviousField Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200 , Ed. 1.2.0, 27 Jun 2019 Page 9 of 22 Figure 3 - Examples of UIP supplementary data files include javascript files, css files, and images External libraries and supplementary files The UIP can depend on external libraries (3 rd party libraries) and other components, for example, specific user control libraries, icons, or images. FDI Clients dynamically load and execute the UIP in the HTML5 runtime. To support this usage, as well as the requirement to prevent possible problems of conflicting libraries, the following rules are specified for external libraries and supplementary files. External libraries and supplementary files shall: • be contained within the UIP variant, except of the FDI Host Type LIbrary (fdi.js and host.js), which are provided by the FDI Client; • not require any installation procedure other than copying into the UIP installation directory or its subfolders; • adhere to the access restrictions described in 4.7.2; • be compatible with the platforms and runtimes the UIP Variant is built for. The FDI Client loads the HTML5 UIP by navigating to the main entry file given by the <StartElementName>- Attribute of the HTML5 UIP Package. Referenced external libraries and supplementary files have to be loaded explicitly by the UIP itself (e.g. stated as <script src=”./scripts/myExternalLibrary.js”/> ). All references to external libraries and supplementary files within the UIP shall be specified as relative URLs. 4.3 UIP compatibility rules Overview The compatibility rules for different versions of the UIP variant are specified in FCG TS62769-4. An FDI Client shall provide the versions of the FDI Host Type Library (fdi.js andhost.js) and the HTML5 runtime supporting the feature set, which correspond to the RuntimeId of the UIP variant. FDI Type Library Compatibility Strategy The UIP shall check for the FDI Technology Version of the FDI Client using the HostingService GetClientTechnologyVersion. The following rules ensure the compatibility of the UIP with the FDI Host Type Library: • If the UIP variant was built for a completely compatible FDI Technology Version (same major and minor version), the UIP can be directly started in the FDI Client. Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200, Ed. 1.2.0, 27 Jun 2019 Page 10 of 22 • If the minor version of the FDI Technology of the FDI Client is lower than the minor version of FDI Technology the UIP has been built for, the UIP may only use the interface methods defined in the FDI Technology Version supported by the FDI Client. • If the UIP variant to be started was built for an incompatible FDI Technology Version (different major versions), the FDI Client shall start the UIP using the matching FDI Host Type Library and Runtime. Runtime compatibility strategy In different runtime versions, UIPs may use a different, potentially incompatible feature set. The feature set, which shall be supported by any runtime version identified by a specific RuntimeId is specified in FCG TS10099. FDI Clients supporting a specific RuntimeId shall support at least the features listed in FCG TS10099 for the individual RuntimeId. UIP variants built for a specific RuntimeId can rely on the features specified in FCG TS10099 for this RuntimeId. If a UIP uses features, which are not listed in the standard feature set of the corresponding RuntimeId, the UIP shall check for the availability of the feature in the respective FDI Client and implement a fallback strategy as for example an information message to the user. If an FDI Client detects that a UIP variant is built for a RuntimeId requiring another feature set from the runtime, the FDI Client can use the appropriate runtime, e.g. the HTML5+ runtime, to execute the UIP. This is shown in Figure 4. HTML5 Runtime FDI UIP Hosting HTML5 UIP UIP Hosting <<FDI 1.2.0>> host.ts <<FDI 1.2.0>> uip.ts <<FDI 1.2.0>> fdi.ts <<FDI 1.2.0>> HTML5+ Runtime HTMLx UIP UIP Hosting <<FDI x.y.z>> host.ts <<FDI x.y.z>> uip.ts <<FDI x.y.z>> fdi.ts <<FDI x.y.z>> FDI Client Figure 4 – Compatibility strategy to host UIPs built for different Runtime Versions UIP executable compatibility rules A HTML5 based UIP is not compiled to machine code. Therefore, the element “CpuInformation” in the catalog.xml file, which holds the compilation target platform information, shall not be used for HTML5 based UIPs. 4.4 UIP Deployment The general UIP installation rules are outlined in FCG TS62769-2. If the UIP is stored on the local file system, the FDI Client and the FDI Server shall ensure the integrity of the UIP. The FDI Client implementation ensures that UIP deployment works independently from current user credentials. (See the NOTE below.) Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200 , Ed. 1.2.0, 27 Jun 2019 Page 11 of 22 NOTE: Certain operating system managed folders require specific access rights, for example, modifications in folder “Program Files” require “Administrator” rights. The Windows operating system provides several means to allow an application running with restricted user rights, to execute actions with administrator privileges transparent to the user, for example, special restriction handling for identified directories, services with administration rights, executables that are configured to automatically run with administration rights. The alternative is to copy UIP into folders writeable for “normal” users. 4.5 UIP Life-cycle General The UIP state machine, outlined in FCG TS62769-2, is composed of the Loaded, Created, Operational, Deactivated and Disposed states. The mechanisms affecting state changes are described in this section. After UIP deployment (see section 4.3.4), the FDI Client loads the HTML5 runtime dynamically into the memory and executes the related logic of the UIP by calling the corresponding FDI specified interface functions. Figure 5 gives an overview on the UIP lifecycle. Figure 5 - UIP Life-cycle Subclauses 4.5.2 and 4.5.3 specify the rules about how the FDI Client shall activate and deactivate the UIP. UIP activation steps 4.5.2.1 Load The FDI Client shall load its HTML5 runtime. Within the HTML5 runtime the creation of the UIP shall be done by creating a browsing context for the UIP and navigating this browsing context to the main HTML entry page given by the <StartElementName>-Attribute of the HTML5 UIP Package. The <StartElementName>-Attribute is contained in the file uipcatalog.xml of the UIP Package. 4.5.2.2 Create The UIP is created within the HTML5 runtime. All resources referenced in the main HTML entry page shall be loaded as specified in W3C HTML5. When the UIP is created successfully, the HTML5 runtime shall send the Javascript event “onload” to the UIP. Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200, Ed. 1.2.0, 27 Jun 2019 Page 12 of 22 4.5.2.3 Activate The UIP shall bind its startup method to the Javascript event “onload”. Within this method, the UIP implements its startup and initialization sequence. Within the startup method the UIP shall call the method Fdi.Model.registerUIP() to enable the FDI Client to call the methods on the UIP as specified in FCG TS62769-2, chapter 6.1 UIP Services. After registration of the UIP Services interface implementation of the specific UIP, the FDI Client shall call the method Fdi.UIPSerice.setSystemLabel() to specify a human identifier of the UIP instance in the context of the FDI Client. To finish UIP activation, the FDI Client calls Fdi.UIPSerice.activate() . The invocation of Fdi.UIPSerice.activate() includes information on localization (RegionInfo, CultureInfo) and the calling context including the FDI client specific implementation of the interfaces DeviceAccessServices and HostingServices. With successful completion of Fdi.UIPSerice.activate() the activation process of the UIP is finished and the UIP is operational. The whole activation process is shown in Figure 6. Figure 6 - UIP activation process UIP deactivation For UIP deactivation the FDI Client shall call the method Fdi.UIPService.deactivate() using the implementation of the UIP Services interface registered during the activation process. Afterwards the FDI Client shall delete all references to the UIP instance. General rules for UIP activation and deactivation The activation logic shall be limited to instantiate the object in terms of the internal data structure and load of all referenced libraries. The deactivation implementation shall be limited to destroy the object in terms of releasing memory resources. The activation and the deactivation shall not: • throw errors, Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200 , Ed. 1.2.0, 27 Jun 2019 Page 13 of 22 • invoke any call-back to the FDI Client; and • invoke any user interaction. 4.6 Interaction between an FDI Client and a UIP Handling of standard UI elements UIPs shall delegate the presentation and handling of standard UI elements to the FDI Client. The standard UI elements are • UI Actions with standardized semantics (Apply/Close/Online Help), and • specific UI Actions (UI actions, which are specific to one UIP, e.g. Reset, Reconnect). To ensure a consistent user interface interaction across UIPs from different vendors, a UIP may delegate presentation and handling of additional UIP specific actions to the FDI Client. Nonetheless UIPs are allowed to implement non-standard UI actions within their own UI area. The set of standard UI actions and their respective semantics is fixed. However, the availability of these actions may change at any time depending on the internal state of the UIP. The set of additional UIP specific actions and their individual availability is not fixed. A UIP may add, remove, rename, enable or disable the UIP specific actions at any time depending on its requirements. The UIP has to inform the FDI Client whenever the availability of its standard actions or UIP specific actions changes (see methods Fdi.HostingServices.StandardActionItemSetChanged() and Fdi.HostingServices. . ApplicationSpecificActionItemSetChanged() ). An FDI Client may use dedicated UI elements, e.g. button controls, to provide direct access to the standard actions, as well as indirectly invoke them in the context of user interaction with other FDI Client UI elements. FDI Client shall always show all custom actions exposed by a UIP with dedicated UI elements. Non-blocking service execution 4.6.2.1 FDI Client internal functions The productive (time consuming) part of a service named OperationName shall be performed asynchronously by the FDI Client. For the asynchronous service execution, the async/await pattern based on Promises is used. Therefore any method of the FDI interface implementation returns a Promise. If the request cannot be executed, the FDI Client shall release the Promise with “reject” to indicate that the requested operation didn’t start. Any other response shall release the Promise with “resolve”. The return value provided with the “resolve” shall include an appropriate error message and one of the status codes defined with Fdi.Model.StatusCode , if the time consuming operation resulted in an error or has been cancelled. Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200, Ed. 1.2.0, 27 Jun 2019 Page 14 of 22 Figure 7 –Asynchronous service execution example (FDI Client) The implementation of CancelOperationName is not implemented as separate service call. Instead, service calls that can be cancelled have an argument cancelToken of type Fdi.Model.CancelToken. If the UIP cancels the service execution, it calls the method cancelToken.cancel() which shall invoke the resolve of the Promise with Fdi.Model.StatusCode.Bad_RequestCancelled and an appropriate error message. Service Read processing UIP UIP FDI Client Implementation (host.js) read(fdi.model.ReadSpecifier, …) Promise<fdi.model.ReadResult> Read Service Request FDI Client Service Status: Started CancelToken.Cancel() Cancel Service Request Service Status: Cancelled Promise.reject( Fdi.Model.Bad_Cancelled) Figure 8 - Cancelled asynchronous service execution example (FDI Client) The handling of the operation within theUIP is described in the following section 4.6.2.2. Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200 , Ed. 1.2.0, 27 Jun 2019 Page 15 of 22 4.6.2.2 UIP internal functions The implementation of every service interface function that is called from the UIP, returns an asynchronous object of class Promise<OperationResult>”. The UIP evaluates the Promise by implementing its “.then”-handler. In addition the “.catch()”-Handler should be implemented to catch unexpected errors. Each “.then”-handler shall have two async functions, one for “resolve” and one for “reject”. An operation, which results in “resolve”, has been executed successfully. An operation, which results in “reject”, has either been cancelled or the service execution in the FDI Client has resulted in an error. The “.catch”-handler additionally handles exceptions that may be thrown within the host specific implementation (e.g. failed type conversions, missing arguments). Service Read processing FDI Client UIP FDI Client Implementation (host.js) invokeStandardUIAction (Fdi.Model.StandardActionId) Promise<fdi.model.Result> invokeStandardUIAction Service Request UIP Service Status: Started Service Response Promise.resolve(fdi.model.Result) Evaluation of result of invokeStandard UIAction call Service Read processing invokeStandard UIAction Service processing Figure 9 - Asynchronous service execution example (UIP) The use of Promise implies, that the respective interface function is called from a function declared with the “async” keyword aus shown in the code example in Figure 10. The “async” keyword enables asynchronous handling of the function. The interface function itself shall be called with the “await” statement. All implementation inside the “.then()”- or “.catch()”-handler shall be executed in a separate thread by the HTML5 engine and thus shall not block the UI. Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200, Ed. 1.2.0, 27 Jun 2019 Page 16 of 22 Figure 10 – Simplified code sample to illustrate the described function implementation Threading 4.6.3.1 Implementation rules The UIP and FDI Client shall not block the user interface thread. The user interface shall always stay responsive. The FDI Client, in particular the implementation provided with host.js, shall not block the UIP on method calls on the interfaces Fdi.BasePropertyServices, Fdi.DeviceModelServices, Fdi.DirectAccessSerives, Fdi.LockingServices and Fdi.HostingServices . The FDI Client shall only start an asynchronous operation and return a Promise object for evaluation of asynchronous method execution result. The caller shall not be blocked. The UIP shall not block the FDI Client on method calls on the UIPServices interface. The UIP shall only start an asynchronous operation and return a Promise object for the evaluation of asynchronous method execution result. The caller shall not be blocked. Timeout The interfaces specified in Clause 5 enable asynchronous service execution. The time for the execution of such services depends on performance constraints related to bus communication or FDI Client/FDI Server performance. The rules listed below target the system interoperability regarding the prevention of “Race Conditions”. The general rule is that the component is allowed to manage timeout handling only for those processes that are completely under the control of that component. The following list shows which elements of the entire system are allowed to implement the timeout detection function. • UIP: The UIP shall not implement timeout detection. • FDI Client: The FDI Client shall implement timeout detection. In case of OPC UA, the related support is built into the OPC UA communication stacks. Timeout detected during operations performed on behalf of the UIP shall be forwarded as negative function result codes. Exception handling An important specification goal is to make a clear distinction between software quality problems and anticipated processing states. Therefore the specification defines two general Exception categories: Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200 , Ed. 1.2.0, 27 Jun 2019 Page 17 of 22 a) Exceptions that indicate software states or events that have not been anticipated during the software development are considered as software quality issues (Run-time error). b) Exceptions indicating anticipated software operation failures. Examples of software quality issues indicated by exceptions are: • Function argument type mismatch; • Function argument value range mismatch; • Division by zero; • NULL Pointer reference. Examples of anticipated error handling are: • Communication problem handling; • General IO data processing; • User input errors. Figure 11 - Component interaction According to the FDI Architecture exceptions can occur in different steps of the service processing, see Figure 11: a) Passing the request from the UIP to the FDI Client specific service implementation (host.js): b) Request forwarding from FDI Client specific service implementation (host.js) to FDI Client base component; c) FDI client base component receives and processes service request d) Request forwarding to FDI server; e) FDI client base component receives and processes the response from the FDI Server; f) Forwarding the response to the FDI Client specific service implementation (host.js); g) Response receiving from FDI client base component and processing; h) Forwarding the response to UIP; i) Response processing inside the UIP Field Device Integration (FDI) – Part 6-200: Technology Mapping – HTML5 RELEASED FCG TS62769-6-200, Ed. 1.2.0, 27 Jun 2019 Page 18 of 22 Service processing problems detected inside the FDI Server and beyond are handled through OPC UA defined service results. Regarding the implementation of the asynchronous pattern the following rules apply. – Any failure occurring within step a) shall be reported by an error thrown by the call of OperationName and shall be evaluated with .catch()-Handler on the returned Promise. – Any failure occurring within steps b) to g) shall be reported by an error thrown by the call of OperationName and shall be evaluated with the second .then()-Handler on the returned Promise. Type safe interfaces The Information Model hosts device variables of different types. The values of such variables are transferred using the class Fdi.Model.DataValue , defined in FDI Interface definition fdi.ts. The Device Access Services support writing or reading multiple variables within one service. The data type chosen for data transport is Fdi.Model.DataValue . ´Type safe transport is implemented using the Fdi.Model.DataValue property Fdi.Model.Datatype , which describes the value data type by means of the enumeration Fdi.Model.Datatype . Because the Fdi.Model.DataValue property Value get/set functions use data type Object to convey the actual value, the data receiver (UIP) shall verify the data type before processing the data. Globalization and localization Different Javascript libraries are available to support UIP localization. The FDI Client shall set the locale and country information that shall be used by the UIP by means of the arguments currentRegion and currentCulture that are submitted with the invocation of method Fdi.UIPServices.activate() .The data type for currentRegion is Fdi.Model.RegionInfo . The data type for currentCulture is Fdi.Model.CultureInfo . 4.7 Security General The goal of security is to protect a system against threats compromising the system stability, integrity and sensitive data. System wide security begins with the design process, which is out of the standardization scope. From the system perspective security is about controlling access to resources, such as application components, data, and hardware. The HTML5 runtime already constraints access to resources and provides means to control the execution of extensions like plugins. A complimentary approach is based on certification and authentication. Since any FDI Package needs compliance testing and certification the presumption is that such certified FDI Packages don’t pose any threats to a system. This means a UIP could be executed with the permissions specified in FCG TS62769-2. While an over-constrained system could lead into functional problems an un-constrained permissions can be seen as security threat. Thus subclause 4.7 represents a compromise between both ways. Access permissions 4.7.2.1 General Within this section technology specific permissions and restrictions are specified in addition to the one specified in FCG TS62769-2. The permissions and restrictions shall be enforced by the FDI Client. The implementation rules define how this shall be implemented. Next >