< PreviousField Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5 , Ed. 1.2.0, 22 Jul 2019 Page 29 of 67 Dev_99 InstanceSpaceTypeSpace XYZ-DeviceType ActionServiceType ActionSet InvokeAction AbortAction RespondAction Action_B Action_A Figure 16 – Action Service This Object is used as container for the ActionService Methods and shall have the BrowseName ActionSet. It is formally defined in Table 29. HasComponent is used to reference from a TopologyElement (for example, a Device) to its “ActionService” Object. The ActionServiceType and each ActionSet Object share the same Methods. Actions will typically be shared by all instances of the same Device Type. InvokeAction Method InvokeAction is used to start an Action. It immediately returns after the state machine has been created. The “ActionSet” component of the TopologyElement (Device) on behalf of which the Action shall be invoked is specified via the ObjectId argument of the Call Service. Explicit locking is required. If the Device has not been locked, the FDI Server will reject the request. After InvokeAction returns, the FDI Client shall subscribe to the Value Attribute of the ActionNodeId. The Value Attribute contains an XML element (DataType = String)) that reflects the current state of the Action as well as additional data (depending on state). The FDI Client therefore will get a DataChange notification whenever the state of the Action changes. See FCG TS62769-2 for the Action state diagrams as well as the XML Schema of the ActionNodeId value. FDI Servers shall cache Action state data for an appropriate period of time (a few seconds) so that no state information is lost until the FDI Client had a chance to subscribe. The signature of this Method is specified below. Table 8 and Table 9 specify the arguments and AddressSpace representation, respectively. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5, Ed. 1.2.0, 22 Jul 2019 Page 30 of 67 Signature InvokeAction( [in] String ActionName, [in] String MethodArguments, [out] NodeId ActionNodeId, [out] Int32 InvokeActionError); Table 8 – InvokeAction Method Arguments Argument Description ActionName String portion of the BrowseName of the Action as used in the ActionServiceType instance. MethodArguments XML document that contains the Action input arguments (if any). The ListOfActionArguments XML Schema defined in FCG TS62769-2 is used for the MethodArguments parameter. ActionNodeId Non-browsable node of type Variable. This node is used both to identify the instance of the Action state machine and for access to the Action state information. InvokeActionError 0 – OK. -1 - E_LockRequired – the element is not locked as required -2 - E_UnknownAction – the passed name is not a valid action for this element. Table 9 – InvokeAction Method AddressSpace Definition Attribute Value BrowseName InvokeAction References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory RespondAction Method RespondAction is used by the FDI Client to provide the requested value or selection of a UI function request (if applicable). The “ActionSet” component of the TopologyElement on behalf of which the Action had been invoked is specified via the ObjectId argument of the Call Service. The signature of this Method is specified below. Table 10 and Table 11 specify the arguments and AddressSpace representation, respectively. Signature RespondAction( [in] NodeId ActionNodeId, [in] String Response, [out] Int32 RespondActionError); Table 10 – RespondAction Method Arguments Argument Description ActionNodeId NodeId of a transient Variable that represents and identifies the executing Action. This Id is returned by the InvokeAction Method. Response XML document that contains the response (value or selection). See FCG TS62769-2 for the Xml Schema for the Response parameter. RespondActionError 0 – OK -1 – E_InvalidAction – the NodeId does not refer to an existing action -2 – E_InvalidResponse – the passed response data could not be interpreted Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5 , Ed. 1.2.0, 22 Jul 2019 Page 31 of 67 Table 11 – RespondAction Method AddressSpace Definition Attribute Value BrowseName RespondAction References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory AbortAction Method AbortAction is used by the FDI Client to abort an Action execution. This Method call immediately returns. The FDI Client is informed via a notification event on the ActionNodeId Variable when the Action enters the Aborting state. The “ActionSet” component of the TopologyElement on behalf of which the Action had been invoked is specified via the ObjectId argument of the Call Service. The signature of this Method is specified below. Table 12 and Table 13 specify the arguments and AddressSpace representation, respectively. Signature AbortAction( [in] NodeId ActionNodeId, [out] Int32 AbortActionError); Table 12 – AbortAction Method Arguments Argument Description ActionNodeId NodeId of a transient Variable that represents and identifies the executing Action. This Id is returned by the InvokeAction Method. AbortActionError 0 – OK -1 – E_InvalidAction – the NodeId does not refer to an existing action Table 13 – AbortAction Method AddressSpace Definition Attribute Value BrowseName AbortAction References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory 8 Network and connectivity Network and connection information elements are required to create communication topologies. A Network represents the communication means for Devices that are connected to it. It includes wired and wireless technologies. ConnectionPoints represent the interface (interface card) of a Device to a Network. A specific sub-type shall be defined for each protocol. These elements are described and formally defined in IEC 62541-100. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5, Ed. 1.2.0, 22 Jul 2019 Page 32 of 67 9 Utility functions 9.1 Overview Clause 9 provides specific services for certain FDI information elements. 9.2 Locking Locking is the means to avoid concurrent modifications to a Device or Network and their components. FDI Clients shall use the Locking Services for any changes (e.g., write operations and Action invocations). The main purpose of locking a Device is avoiding concurrent device modifications. The main purpose of locking a Network is avoiding concurrent topology changes. When locking a Device, the lock always applies to both the online and the offline version. When locking a Modular Device, the lock applies to the complete device (including all modules). Equally, when locking a Block Device, the lock applies to the complete device (including all blocks). If no lock is applied to the top-level Device (for Modular Device or for Block Device), the sub-devices or blocks, respectively, can be locked independently. When locking a Network, the lock applies to the Network and all connected Devices. If any of the connected Devices provides access to a sub-ordinate Network (such as a Gateway), the sub-ordinate Network and its connected Devices are locked as well. The LockingService is fully described and formally defined in IEC 62541-100. 9.3 EditContext Overview An EditContext can be used to make changes to Variable values visible to the Server without applying them to the Device. The FDI Server provides the EditContext concept to support Clients in their editing task. The EditContext is specified in IEC 62541-3. Following is the OPC UA Information Model including the Methods to maintain EditContext instances. EditContext is exposed as an AddIn capability which is comparable to the interface technology found in some programming languages. The EditContext service is modelled as an ObjectType and instances of this type are added to the Device with a pre-defined BrowseName. Additional AddIn examples are defined in IEC 62541-100. When reading or subscribing to Variable values registered in an EditContext, the following FDI-specific StatusCodes may occur (see Clause 11): • Good_Edited distinguishes values that have been edited but have not been written to the Device. • Uncertain_DominantValueChanged indicates that dependent values are invalid and will be recalculated after the dominant value has been applied to the device. In the offline case the dependent value has to be written by the Client as well. • Good_DependentValueChanged indicates that a dependent value has been changed but the change has not been applied to the device. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5 , Ed. 1.2.0, 22 Jul 2019 Page 33 of 67 EditContext Type The EditContextType comprises the EditContext Methods. It is formally defined in Table 14. Table 14 – EditContextType Definition Attribute Value BrowseName EditContextType IsAbstract False References NodeClass BrowseName DataType TypeDefinition ModellingRule Subtype of the BaseObjectType defined in IEC 62541-5. HasComponent Method GetEditContext Mandatory HasComponent Method RegisterNodesById Mandatory HasComponent Method RegisterNodesByRelativePath Mandatory HasComponent Method Apply Mandatory HasComponent Method Reset Mandatory HasComponent Method Discard Mandatory The StatusCode Bad_MethodInvalid shall be returned from the Call Service for elements where the EditContext Methods are not supported. Bad_UserAccessDenied shall be returned if the Client User does not have the permission to call the Methods. EditContext Object The support of EditContext for an Object is declared by aggregating an instance of the EditContextType as illustrated in Figure 17. DeviceType MD002 InstanceSpace TypeSpace XYZ-DeviceType EditContextType Register... Apply GetEditContext BaseObjectType EditContext Reset Discard Figure 17 – EditContext type and instance This Object is used as container for the EditContext Methods and shall have the BrowseName EditContext. HasComponent is used to reference from a Device to its “EditContext” Object. The EditContextType and each instance may share the same Methods. GetEditContext Method Returns an EditContext as specified in IEC 62541-3. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5, Ed. 1.2.0, 22 Jul 2019 Page 34 of 67 The signature of this Method is specified below. Table 15 and Table 16 specify the arguments and AddressSpace representation, respectively. Signature GetEditContext( [in] String ParentId, [in] WindowMode TargetWindowMode, [out] String EditContextId, [out] Int32 GetEditContextStatus); Table 15 – GetEditContext Method Arguments Argument Description ParentId If Null, a root instance is requested. Otherwise, the Client passes the identifier of a previously acquired EditContext, indicating that it will create a sub-window. TargetWindowMode An enumeration that indicates the User Interface element used for this context. 1 – Modal Window 2 – NonModal Window 3 – UIP EditContextId A string identifier created by the Server. GetEditContextStatus 0 – OK -1 – E_NotSupported – the element does not support the EditContext Service Table 16 – GetEditContext Method AddressSpace Definition Attribute Value BrowseName GetEditContext References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory RegisterNodes Method This Method is used to register Nodes with an EditContext. It returns new NodeIds that have to be used to address this Node within the EditContext. The signature of this Method is specified below. Table 17 and Table 18 specify the arguments and AddressSpace representation, respectively. Signatures RegisterNodes( [in] String EditContextId, [in] RegistrationParameters[] NodesToRegister, [out] RegisterNodesResult RegisterNodesStatus); Table 17 – RegisterNodes Method Arguments Argument Description EditContextId Identifier of an EditContext that was previously acquired with a GetEditContext call. NodesToRegister An array of structures for each node to register. RegisterNodesStatus A structure with overall execution status and result data for each Node to register. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5 , Ed. 1.2.0, 22 Jul 2019 Page 35 of 67 Table 18 – RegisterNodes Method AddressSpace Definition Attribute Value BrowseName RegisterNodes References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory The RegistrationParameters DataType defines a single Node to be registered. Its elements are defined in Table 20. Table 19 – RegistrationParameters DataType Structure Name Type Description RegistrationParameters structure This structure specifies one of the nodes to register. path RelativePath RelativePath for this Node to register. The RelativePath type is defined in IEC 62541-4. selectionFlags UInt32 A bit mask that identifies the EditContext-specific NodeIds to be returned in the RegisterNodesResult structure. The value of this parameter shall contain at least one of the following values. No value will be rejected with E_InvalidSelectionFlags. Bit Value NodeId to return 0x0000 0001 Online / ContextNodeId 0x0000 0002 Online / DeviceNodeId 0x0000 0004 Offline / ContextNodeId 0x0000 0008 Offline / DeviceNodeId The RegisterNodesResult DataType includes overall status information and result data for each Node to be registered. Its elements are defined in Table 20. Table 20 – RegisterNodesResult DataType Structure Name Type Description RegisterNodesResult structure This structure specifies the registration result. status Int32 0 – OK – the field registeredNodes contains a result for each Node to register -1 – E_InvalidId – the specified EditContext is unknown the registeredNodes field is empty registeredNodes RegisteredN ode[] The list contains EditContext-specific NodeIds for the registered Node. The Client has to use these NodeIds for all subsequent OPC UA Service calls nodeStatus Int32 0 – OK -1 – E_InvalidNode – an invalid Node has been registered. See IEC 62541-3 for details. -2 – E_InvalidSelectionFlags – the RegistrationParameters for this Node contained no value onlineContextNodeId NodeId This NodeId shall be used to address the online representation of the Node in the EditContext. See IEC 62541-3 for details. onlineDeviceNodeId NodeId This NodeId shall be used to address the online representation of the Node in the Device. See IEC 62541-3 for details. offlineContextNodeId NodeId This NodeId shall be used to address the online representation of the Node in the EditContext. See IEC 62541-3 for details. offlineDeviceNodeId NodeId This NodeId shall be used to address the online representation of the Node in the Device. See IEC 62541-3 for details. Apply Method This Method is used to apply values that have been modified in the EditContext. Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5, Ed. 1.2.0, 22 Jul 2019 Page 36 of 67 The signature of this Method is specified below. Table 21 and Table 22 specify the arguments and AddressSpace representation, respectively. Signature Apply( [in] String EditContextId, [out] ApplyResult ApplyStatus); Table 21 – Apply Method Arguments Argument Description EditContextId Identifier of an EditContext that was previously acquired with a GetEditContext call. ApplyStatus A structure with overall execution status and status information for each transferred Variable. Table 22 – Apply Method AddressSpace Definition Attribute Value BrowseName Apply References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory The ApplyResult DataType includes overall Apply status information and status information for each Variable that could not be transmitted. Its elements are defined in Table 23 and Table 20. Table 23 – ApplyResult DataType Structure Name Type Description ApplyResult structure This structure is returned in case of errors. No result data are returned. Further calls with the same TransferId are not possible. status Int32 0 – OK – the transferIncidents field may include individual Variables that failed -1 – E_InvalidId – the specified EditContext is unknown transferIncidents TransferIncident[] If the service returns normally and the TransferIncidents list is empty, all changes have been applied and the edited values are cleared. Otherwise, the list contains Variables that could not be transferred successfully. The edited Values are preserved. contextNodeId NodeId The NodeId returned from RegisterNodesById or RegisterNodesByRelativePath. statusCode StatusCode OPC UA StatusCode as defined in IEC 62541-4 and in IEC 62541-8. diagnostics DiagnosticInfo Diagnostic information. This parameter is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in the processing of the request. The DiagnosticInfo type is defined in IEC 62541-4. Reset Method Clears all modified values in the EditContext. The signature of this Method is specified below. Table 24 and Table 25 specify the arguments and AddressSpace representation, respectively. Signature Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5 , Ed. 1.2.0, 22 Jul 2019 Page 37 of 67 Reset( [in] String EditContextId, [out] Int32 ResetStatus); Table 24 – Reset Method Arguments Argument Description EditContextId Identifier of an EditContext that was previously acquired with a GetEditContext call. ResetStatus 0 – OK -1 – E_InvalidId – the specified EditContext is unknown Table 25 – Reset Method AddressSpace Definition Attribute Value BrowseName Reset References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory Discard Method This Method releases the EditContext. Any modified values that have not been applied are lost. The signature of this Method is specified below. Table 26 and Table 27 specify the arguments and AddressSpace representation, respectively. Signature Discard( [in] String EditContextId, [out] Int32 DiscardStatus); Table 26 – Discard Method Arguments Argument Description EditContextId Identifier of an EditContext that was previously acquired with a GetEditContext call. DiscardStatus 0 – OK -1 – E_InvalidId – the specified EditContext is unknown -2 – E_ChildExists – the specified EditContext cannot be discarded, because a child instance exists. Table 27 – Discard Method AddressSpace Definition Attribute Value BrowseName Discard References NodeClass BrowseName DataType TypeDefinition ModellingRule HasProperty Variable InputArguments Argument[] PropertyType Mandatory HasProperty Variable OutputArguments Argument[] PropertyType Mandatory 9.4 Direct Device Access General DirectDeviceAccess provides the means to communicate with a device in the Device Topology. It will be used by UIPs for operations that cannot or at least not easily be performed through Information Model access. Use cases include the transmission of large data buckets from or to the device, for example, historical data or firmware. It Field Device Integration (FDI) – Part 5: Information Model RELEASED FCG TS62769-5, Ed. 1.2.0, 22 Jul 2019 Page 38 of 67 is generally assumed that directly accessed data will not be reflected in the Information Model as well. DirectDeviceAccess shall not influence the structure and the data integrity of the Information Model. FDI Servers may be restrictive about when they enable the use of these Methods. A DirectDeviceAccess Object shall exist for every Device where the FDI Server allows direct access via a UIP. The following behaviour applies when using DirectDeviceAccess: • Only one FDI Client can use DirectDeviceAccess at a given time. • DirectDeviceAccess requires a lock. If the Device has not been locked, the request will be rejected. • Due to the lock, no write operations and no Method invocations from other FDI Clients are permitted during DirectDeviceAccess. This includes the execution of Actions. • If Attribute values of Parameters might have changed due to DirectDeviceAccess, the UIP shall set the InvalidateCache in the EndDirectAccess argument to True. DirectDeviceAccess Type The DirectDeviceAccessType provides the Methods needed to open and close a connection and to transfer data. Figure 18 shows the DirectDeviceAccessType definition. It is formally defined in Table 28. DirectDeviceAccess Type InitDirectAccess EndDirectAccess Transfer BaseObjectType Figure 18 – DirectDeviceAccessType Table 28 – DirectDeviceAccessType Definition Attribute Value BrowseName DirectDeviceAccessType IsAbstract False References NodeClass BrowseName DataType TypeDefinition ModellingRule Subtype of the BaseObjectType defined in IEC 62541-5. HasComponent Method InitDirectAccess Mandatory HasComponent Method Transfer Mandatory HasComponent Method EndDirectAccess Mandatory The DirectDeviceAccessType and each instance of this Type share the same Methods. The NodeId of these Methods will be fixed and defined in this standard. FDI Clients therefore do not have to browse for these Methods. They can use the fixed NodeId as the MethodId of the Call Service. The OPC UA StatusCode Bad_MethodInvalid shall be returned from the Call Service for elements where the DirectDeviceAccess Methods are not supported. Next >