< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 39 of 145 Name Type Description Request structure. However, if the specified Attribute is an array or a structure, and this parameter is null, then all elements are to be included in the range. See 5.1.9.3.6 for a detailed definition. samplingInterval Int32 The interval that defines the fastest rate at which the Attribute should be accessed and evaluated. This interval is defined in milliseconds. The value 0 indicates that the FDI Server should use the fastest practical rate. The value -1 indicates that the default sampling interval defined by the UpdateRate of the Subscription is used. See 5.1.6.8.3.3 for further details on the sampling interval. uIPHandle UInt32 A handle (an identifier) provided by the UIP for the subscribed Node Attribute. This handle will be passed together with the data in the DataChangeCallback service so that the UIP can easily associate each changed value with the subscribed Node Attribute. The uiPHandle is likely an index into a table somewhere. It does not have to be unique (there could be multiple subscribed items pointing to the same table entry). Response subscribeResult [] structure List of results for the subscribed Attributes. The size and order of the list matches the size and order of the attributesToSubscribe request parameter. statusCode UInt32 Status code for the respective Attribute to subscribe as defined in Table 20. monitoredItemId UInt32 FDI Server-assigned id for the subscribed Attribute. This id is unique within the Subscription and shall be used when calling Unsubscribe. This parameter is present only if the statusCode indicates that the Attribute was successfully subscribed. revisedSamplingInterval Int32 The actual sampling interval that will be used. This value is based on a number of factors, including the capabilities of the underlying system. Subscribing will succeed even if the current user is not authorized to access the Node Attribute. If this is the case, the initial callback will return the operation result “Bad_UserAccessDenied”. Once this denial is cleared away (for instance, after a more powerful user identity is provided) the UIP will receive data changes for this Node Attribute. It is possible to subscribe to any Attribute – not just the Value. While it may not make sense for all Attributes, monitoring of some Attributes provides additional possibilities. Some examples include: • monitoring the LockedStatus to determine when the lock by some other client is removed; • monitoring the CurrentLabel of Enumerations to receive a displayable name rather than a numeric value. 5.1.6.8.3.3 Sampling interval Each subscribed item is assigned a sampling interval that is either inherited from the updateRate of the Subscription or that is defined specifically to override that rate. The sampling interval indicates the fastest rate at which the value should be sampled in the device for data changes. The assigned sampling interval defines a “best effort” cyclic rate that is used to sample the item from its source. “Best effort” in this context means that the system does its best to sample at this rate. Sampling at rates faster than this rate is acceptable, but not necessary to meet the needs of the UIP. How the system deals with the sampling rate and how often it actually polls its data source internally is a system implementation detail. However, the time between values returned to the UIP shall be greater than or equal to the sampling interval. The FDI Client may also specify 0 for the sampling interval, which indicates that the system should use the fastest practical rate. It is expected that systems will support only a limited set of sampling intervals to optimize Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 40 of 145 their operation. If the exact interval requested by the UIP is not supported, then the most appropriate interval as determined by the system will be assigned and returned to the UIP. Data may be collected based on a sampling model or generated based on an exception-based model. The fastest supported sampling interval may be equal to 0, which indicates that the data item is exception-based rather than being sampled at some period. When it is exception-based the underlying system does not require sampling. In many cases, the system has no knowledge of the data update logic. In this case, even though the system samples at the negotiated rate, the data might be updated by the underlying system at a much slower rate. In this case, changes can only be detected at this slower rate. UIPs should also be aware that the sampling by the system and the update cycle of the device are usually not synchronized, which may lead to additional delays. 5.1.6.8.3.4 Service results There are no service results other than the common codes specified in 0. 5.1.6.8.3.5 Operation result codes Table 20 defines values for the operation statusCode contained in the results. All operational status codes with their description are in . Table 20 – Subscribe operation result codes Result code Good Bad Bad_NodeInvalid Bad_AttributeInvalid Bad_NotReadable Bad_UserAccessDenied 5.1.6.8.4 Unsubscribe Service 5.1.6.8.4.1 Description This service is used to unsubscribe to one or more Node Attributes. 5.1.6.8.4.2 Parameters Table 21 defines the parameters for the service. Table 21 – Unsubscribe Service Parameters Name Type Description Request subscriptionId Subscriptio nId The identifier for an existing subscription that was returned by the CreateSubscription service. monitoredItemIds[] UInt32 Identifiers for subscribed Attributes that were returned by the Subscribe service. Response unsubscribeResult[] UInt32 Status codes for operation results as defined in Table 22. The order of this list matches the order of the monitoredItemIds request parameter. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 41 of 145 5.1.6.8.4.3 Service results There are no service results other than the common codes specified in 0. 5.1.6.8.4.4 Operation result codes Table 22 defines values for the operation status code contained in unsubscribeResult. All operational status codes with their description are in . Table 22 – Unsubscribe operation result codes Result code Good Bad Bad_UIPHandleInvalid 5.1.6.8.5 DeleteSubscription Service 5.1.6.8.5.1 Description This service is used to delete a subscription. Due to the asynchronous nature of the callbacks, the UIP may receive additional callbacks for a subscription after the subscription is deleted 5.1.6.8.5.2 Parameters Table 23 defines the parameters for the service. Table 23 – DeleteSubscription Service parameters Name Type Description Request subscriptionId SubscriptionId The identifier for an existing subscription that was returned by the CreateSubscription service. Response 5.1.6.8.5.3 Service results There are no service results other than the common codes specified in 0. 5.1.6.8.6 DataChangeCallback Service 5.1.6.8.6.1 Description This service is used for sending data change updates to the UIP. This service is implemented and provided by the UIP when calling the CreateSubscription service. Due to the asynchronous nature of the callbacks, the UIP may receive additional callbacks for a subscription after the subscription is deleted. 5.1.6.8.6.2 Parameters Table 24 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 42 of 145 Table 24 – DataChangeCallback Service parameters Name Type Description Request subscriptionId SubscriptionId Identifier that was returned by the CreateSubscription service dataChangeData[] structure Data that has changed. No specific order of array elements is ensured. uIPHandle UInt32 The handle provided by the UIP in the Subscribe service value DataValue The StatusCode, Value and timestamps of the subscribed Node Attribute. The DataValue is defined in 5.1.9.3.3. innerErrorInfos [] InnerErrorInfo List of error information from calls to an underlying system. See 5.1.9.3.4. Matches the size and order of the dataChangeData parameter. This list is empty if inner error information was not requested or if no information was encountered in the processing of the request. Response 5.1.6.8.6.3 Operation result codes Table 25 defines values for the operation status code contained in the DataChangeData structure of each values element. In addition, all Read operation status codes apply also (see Table 12). All operational status codes with their description are in . Table 25 – DataChangeCallback result codes Result code Bad_WaitingForInitialData Locking Services 5.1.7.1 Overview Locking is the means to avoid concurrent modifications to a Device or a Block and its Parameters. UIPs shall use the locking services before making changes (for example, write operations and Direct Access Services). 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. While locked, requests from other FDI Clients to write to Parameters, or to perform Direct Access will be rejected. The lock is removed when ExitLock is called. 5.1.7.2 InitLock service 5.1.7.2.1 Description InitLock reserves the specified Device or Block. During a lock other FDI Clients will not be able to write to the Parameters of this element. A lock for an element that is already locked by another FDI Client will be rejected. A UIP can subscribe to the LockedStatus Attribute in order to be informed when the lock is removed by the other Client. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 43 of 145 FDI Clients shall allow “nested” InitLock calls from the same UIP. The FDI Client expects the same number of ExitLock calls before it actually removes the lock. FDI Clients are responsible for preventing simultaneous locks to a Device or Block by independent components that this Client hosts. Such components include the Client itself, independent UIPs or the UID Interpreter. 5.1.7.2.2 Parameters Table 26 defines the parameters for the service. Table 26 – InitLock Service parameters Name Type Description Request node NodeSpecifier The identifier of the Node (representing a device or block) to be locked. See 5.1.9.3.2 for the definition of the NodeSpecifier type. context String Used to provide context information about the current activity going on in the UIP. This will be used to enhance the Audit Trail. Response 5.1.7.2.3 Service results Table 27 defines values for the Service result code. Other common StatusCodes are defined in . Table 27 – InitLock Service result codes Result code Description Bad_NotSupported The Node does not support locking. Bad_AlreadyLocked The Node is already locked by another FDI Client or another independent component within the FDI Client. 5.1.7.3 ExitLock service 5.1.7.3.1 Description ExitLock removes the lock. 5.1.7.3.2 Parameters Table 28 defines the parameters for the service. Table 28 – ExitLock Service parameters Name Type Description Request node NodeSpecifi er The identifier of the Node (representing a device or block) to be unlocked. See 5.1.9.3.2 for the definition of the NodeSpecifier type. Response 5.1.7.3.3 Service results Table 29 defines values for the Service result code. Other common StatusCodes are defined in . Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 44 of 145 Table 29 – ExitLock Service result codes Result code Description Bad_ InvalidState The Node is not locked. Direct Access Services 5.1.8.1 Overview Direct Access Services provide direct communication with a Device. This can be used for operations that cannot or at least not easily be performed through the Device Model Services. Use cases include the transmission of large data buckets from or to the Device, for example, historical data or firmware. The Direct Access Services should not influence the structure and the data integrity of the Device Model. Support of Direct Access Services is mandatory for FDI Hosts. However, Host Systems shall provide means to disable/enable Direct Access Services on demand. Commissioning engineers or plant operators can then disallow the use of Direct Access in specific scenarios. This can be temporary or even permanent and might apply to the complete or specific parts of the plant. Therefore, UIPs shall not depend on the availability of Direct Access for the initial setup of a Device (e.g. needed for commissioning). The following behaviour applies when using Direct Access. • Only one FDI Client/UIP can use DirectAccess at a given time. While in Direct Access mode, other FDI Clients or OPC UA Clients, or other UIPs or the UID will not be able to access this Device (not even for Reading). • The Device shall have been locked prior to entering this mode. • If Variable Attributes may have changed due to DirectAccess, the UIP shall set the InvalidateCache in the EndDirectAccess argument to “true”. The Direct Access Services include: • InitDirectAccess • Transfer • ExitDirectAccess Guideline: These services are not to be used as alternative to Information Model access. Instead, DirectAccess is used for the transfer of data that are not reflected in the Information Model. 5.1.8.2 InitDirectAccess 5.1.8.2.1 Description This service initializes the Device for the use of DirectAccess. 5.1.8.2.2 Parameters Table 30 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 45 of 145 Table 30 – InitDirectAccess Service parameters Name Type Description Request context String Used to provide context information about the current activity going on in the UIP. This will be used to enhance the Audit Trail. Response 5.1.8.2.3 Service results Table 31 defines values for the Service result code. Other common StatusCodes are defined in . Table 31 – InitDirectAccess Service result codes Result code Description Bad_NotSupported DirectAccess is (currently) not supported. Bad_LockRequired The Node has not been locked. Bad_InvalidState DirectAccess is already initialized. 5.1.8.3 ExitDirectAccess 5.1.8.3.1 Description This service ends the use of DirectAccess. 5.1.8.3.2 Parameters Table 32 defines the parameters for the service. Table 32 – ExitDirectAccess Service parameters Name Type Description Request invalidateCache Boolean If “true”, any cached values for Device Parameters will be invalidated. This means that these Parameters will be re-read from the Device the next time they are used again. Response 5.1.8.3.3 Service results Table 33 defines values for the Service result code. Other common StatusCodes are defined in . Table 33 – ExitDirectAccess Service result codes Result code Description Bad_InvalidState The device is not in DirectAccess mode. 5.1.8.4 Transfer 5.1.8.4.1 Description This service is used to transfer data to and from the Device. The format of send or receive data is protocol specific. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 46 of 145 Direct Access by its nature does not allow automatic generation of Audit Trail information that complies with the various regulations. Therefore, UIPs shall invoke the LogAuditTrailMessage Service (see 5.2.2.5) to provide explicit information about what is being transferred. For other service calls that affect the Device indirectly via the Device Model (Write), the service parameters provide sufficient information. 5.1.8.4.2 Parameters Table 34 defines the parameters for the service. Table 34 – Transfer Service parameters Name Type Description Request sendData String XML document based on the TransferSendDataT as specified in the communiction profile-specific XML schema. Response receiveData String XML document based on the TransferResultDataT as specified in the communiction profile-specific XML schema. 5.1.8.4.3 Service results Table 35 defines values for the Service result code. Other common StatusCodes are defined in . Table 35 – Transfer Service result codes Result code Description Bad_InvalidState The device is not in DirectAccess mode. Data types 5.1.9.1 General Subclause 5.1.9 specifies the data types used for Service parameters, Variable values, and the values of other Node Attributes. They may occur either scalar or as an array. 5.1.9.2 Base data types Table 36 lists base data types, i.e., types that are typically supported native by programming languages. Table 36 – Base data types DataType Description Boolean Defines a value that is either “true” or “false”. String Represents text as a series of Unicode characters. The actual string representation depends on the technology mapping. See FCG TS62769-6 and its subparts. ByteString A value that is a sequence of Byte values preceded by a 32-Bit Length. UtcTime A DateTime used to define Coordinated Universal Time (UTC) values. All time values are UTC values. FDI Clients shall provide any conversions between UTC and local time. UtcTime is a 64-bit signed integer that represents the number of 100 nanosecond intervals since January 1, 1601. It corresponds to the Windows FILETIME. Int8 A signed integer between -128 and 127 inclusive. Int16 A signed integer between -32 768 and 32 767 inclusive. Int32 A signed integer between -2 147 483 648 and 2 147 483 647 inclusive. Int64 A signed integer between -9 223 372 036 854 775 808 and 9 223 372 036 854 775 807 inclusive. Byte A value in the range of 0 to 255. UInt16 An unsigned integer between 0 and 65 535 inclusive. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 47 of 145 DataType Description UInt32 An unsigned integer between 0 and 4 294 967 295 inclusive. UInt64 An unsigned integer between 0 and 18 446 744 073 709 551 615 inclusive. Float Defines a value that shall be according to the IEEE 754 single precision data type definition. Double Defines a value that shall be according to the IEEE 754 double precision data type definition. Duration Same representation as Double. 5.1.9.3 Special types 5.1.9.3.1 AttributeIds AttributeIds are represented as UInt32. Table 37 lists the Attributes and their identifiers. Table 37 – Identifiers assigned to Attributes Attribute Identifier Name 10 Label 11 Description 12 … LockedStatus 30 … Value 100 DataType 101 ValueRank 102 ArrayDimensions 103 AccessRights 105 UserAccessRights 106 ScalingFactor 107 … EURange 111 EngineeringUnits 112 … EnumValues 120 CurrentLabel 121 OptionNames 122 ÖpmgLabel 123 5.1.9.3.2 NodeSpecifier Each Node in the Device Model (see 5.1.2) is uniquely addressable with its path name qualified by an online/offline specifier. When online is specified, the service shall operate in the online version of the Device Model. When offline is specified, it shall operate in the offline model. The path name follows the hierarchy of the device model as illustrated in 5.1.2, It is a concatenation of the individual names, separated by slash (‘/’) characters. See 5.1.2 for example path names. All parameters are identified via “/ParameterSet/<ParamName>” , all images via “/ImageSet/<ImageName>”, and so on. Subclauses 5.1.3.4.3 and 5.1.3.4.5 specify the representation of parameters that hold record values or arrays of record values. A pathname for record elements is built by extending the path to the Parameter. See examples in the referenced subclauses. The components of this parameter are defined in Table 39. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 48 of 145 Table 38 – NodeSpecifier Name Type Description NodeSpecifier structure Specifies a Node in the device model. nodePath String The path description that enables finding a Node in the Information Model. useOnline Boolean If “true” the path addresses a Node in the online model; with “false” a Node in the offline model is referenced. An empty path name identifies the Root. 5.1.9.3.3 DataValue This type describes the value of a Node Attribute in the response of a Read and in the DataChangeCallback. The components of this parameter are defined in Table 39. Table 39 – DataValue Name Type Description DataValue structure The value and associated information. value Variant The Node Attribute value. For the definition of Variant see 5.1.9.4. statusCode UInt32 The StatusCode that defines the ability to access/provide the value. The StatusCode type is defined in 0. sourceTimestamp UtcTime The source timestamp for the value. serverTimestamp UtcTime The server timestamp for the value. The statusCode is used to indicate the conditions under which a Node Attribute value was generated, and thereby can be used as an indicator of the usability of the value. It is required to check the StatusCode (as a minimum the Severity) of all results before accessing and using the value. The sourceTimestamp reflects the timestamp that was applied by the data source. The sourceTimestamp is only returned with the Value Attribute of Variable Nodes. For all other Attributes the returned sourceTimestamp is set to null. In the case of a bad or uncertain status sourceTimestamp is used to reflect the time that the source recognized the non-good status or the time the FDI Server last tried to recover from the bad or uncertain status. The serverTimestamp is used to reflect the time that the FDI Server received a Variable value or knew it to be accurate. In the case of a bad or uncertain status, serverTimestamp is used to reflect the time that the FDI Server received the status or that the FDI Server last tried to recover from the bad or uncertain status. The serverTimestamp is updated each time a new value is received. Next >