< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 29 of 145 Programmatic access to the services may be synchronous or asynchronous (see FCG TS62769-6 and its subparts for the individual technologies). However, asynchronicity exists to maintain responsiveness of the User Interface. Service execution shall always be assumed to be sequential. 5.1.4.2 Conventions for service definitions The service specifications use tables to describe service parameters, as shown in Table 4. Parameters are organised in this table into request parameters and response parameters. Table 4 – Service Definition Table Name Type Description Request Defines the request parameters of the service simple Parameter Name simple data type Description of this parameter constructed Parameter Name structure Description of the constructed parameter component Parameter Name structure or simple data type Description of the component parameter Response Defines the response parameters of the service The Name, Type and Description columns contain the name, data type and description of each parameter. All parameters are mandatory, although some may be unused under certain circumstances. The description column specifies the value to be supplied when a parameter is unused. Parameter names always begin with a lower case character. This allows differentiating if name and type are the same, for example, name = “nodeId”, type = “NodeId”. Two types of parameters are defined in these tables, simple and constructed. Simple parameters have a simple data type, such as Boolean or String. Constructed parameters are composed of two or more component parameters, which can be simple or constructed. Component parameter names are indented below the constructed parameter name. The data types used in these tables may be base types or service-specific types. Base data types are listed in 5.1.9. Data types that are service-specific are defined in the parameter table of the service. 5.1.4.3 Auditing Auditing is a requirement in many systems. It provides a means for tracking activities that occur as part of normal operation of the system. It also provides a means for tracking abnormal behaviour. It is also a requirement from a security standpoint. When an audit trail is maintained by the system, audit trail records for the Write Service invoked by the UIP will be implicitly created by the system. In addition, UIPs have means for providing additional audit context information for things that the system cannot know: • They can call the LogAuditTrailMessage service (see 5.2.2.5). This shall be executed in particular when the DirectAccess Services are used. The UIP shall include sufficient information in the message for precise description of the activity performed. • They can provide a context text when using the Locking Services (see 5.1.7) or the Direct Access Services (see 5.1.8). Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 30 of 145 5.1.4.4 Result codes for services and operations Several of the Device Model Services (e.g. Read and Write) allow specifying an array of elements that shall be processed. The processing of each individual element is called an “operation”. This is an important differentiation for error handling as a service execution is considered successful even if individual operations fail. The following list explains the differences between the service result code and operation result codes. • Service result code If a service succeeds, the service result code is “Good” and the response parameters are valid. If it fails, the result code is any of the “Bad_...” service failure codes defined in Table 5. In such a case an InnerErrorInfo (see 5.1.9.3.4) may be provided as well. Programmatic access to service failure codes is specific to the technology and may be based on exceptions (see FCG TS62769-6). • Operation result code The result code for each operation is returned as part of the service-specific response parameters. The status codes for all operation level results are specified in FCG TS62769-5. Each service, which returns operation level status codes defines its applicable subset. Operations can return an InnerErrorInfo with each result code other than “Good” if returnInnerErrorInfo=”true” in the service request. The general structure of the StatusCode used for service results and operational results is specified in FCG TS62769-5. Table 5 defines result codes for the services. The column Service in Table 5 lists which code may be returned by which service. Result codes that are specific to an individual service are also specified with the service. Table 5 - Service result codes Symbolic id Description Service Bad_AlreadyLocked The Node is already locked by another FDI Client. InitLock Bad_LockRequired The passed Node is not yet locked. Write, DirectAccess Bad_MaxAgeInvalid The max age parameter is invalid. Read Bad_NodeInvalid The identifier does not refer to a valid Node in the Device Model. This result code is used both as service- and as operation-level result code. Browse, InitLock, ExitLock Bad_NothingToDo There was nothing to do because the caller passed an empty list of operations. Read, Write, Subscribe, Unsubscribe Bad_NotSupported The Service is not supported for the specified Node or for the Device/Block in general. Locking, DirectAccess Bad_RequestCancelled The request was cancelled by Client / UIP. All Bad_SubscriptionIdInvalid The subscription id is not valid. Subscribe, Unsubscribe, DeleteSubscription Bad_Timeout The operation timed out. All Bad_TooManySubscriptions The FDI Server has reached its maximum number of subscriptions. CreateSubscription Bad_InvalidState The specified Node is in a state that does not permit this operation. Services for Locking Bad_TooManyOperations The request could not be processed because it specified too many operations. Read, Write, Subscribe Bad_UnexpectedError An unexpected error occurred. All UIPs shall always check the StatusCode associated with a result before using it. Results that have an uncertain/warning status associated with them shall be used with care since these results might not be valid in all situations. Results with a bad/failed status shall never be used. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 31 of 145 Base Property Services 5.1.5.1 Overview The Base Property Services provide access to basic Device Access properties. 5.1.5.2 Get DeviceAccess interface version 5.1.5.2.1 Description This service returns the version of the interface that the UIP is using. 5.1.5.2.2 Parameters Table 6 defines the parameters for the service. Table 6 – GetDeviceAccessInterfaceVersion Service parameters Name Type Description Request Response version String FDI Technology Version of the DeviceAccess interface. The format of the value is xx.yy.zz as defined in FCG TS62769-4. 5.1.5.2.3 Service results There are no service results other than the common codes specified in 0. 5.1.5.3 GetOnlineAccessAvailability 5.1.5.3.1 Description This service returns a hint as to whether online access is available in principle. This is general information. It does not clarify whether online access to a specific device is possible. 5.1.5.3.2 Parameters Table 7 defines the parameters for the service. Table 7 – GetOnlineAccessAvailability Service parameters Name Type Description Request Response onlineAccess Boolean This value when “false” specifies that online access is not available. “true”indicates basic availability. 5.1.5.3.3 Service results There are no service results other than the common codes specified in 0. Device Model Services 5.1.6.1 Overview The Device Model Services include: • Browse Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 32 of 145 • Read • Write • Subscription – CreateSubscription – Subscribe – Unsubscribe – DeleteSubscription The services provide access to the offline representation and the online representation of the Device. The online Nodes for a Device are always present. However, access to data that require communication may be rejected with proper status codes such as Bad_NotConnected. NOTE The online model does not contain SubDevices. If the UIP uses a path that includes SubDevices to access an online Node, this path will be evaluated in the offline hierarchy. Cancel services are available for Browse, Read, and Write. The exact definition and mechanics depend on the technology used for the implementation of these services. 5.1.6.2 Browse 5.1.6.2.1 Description Browses a single level in the hierarchy in the Device Model and returns Attributes for all children of the specified Node. 5.1.6.2.2 Parameters Table 8 defines the parameters for the service. Table 8 – Browse Service parameters Name Type Description Request nodeToBrowse NodeSpecifier The identifier of the Node to be browsed. See 5.1.9.3.2 for the definition of the NodeSpecifier type. Response browseResult[] structure List of Nodes that are on the next level down in the hierarchy. For each Node the following Attributes will be returned. nodePath String See BaseNodeClass in 5.1.3.2. name String See BaseNodeClass in 5.1.3.2. label LocalizedText See BaseNodeClass in 5.1.3.2. 5.1.6.2.3 Service results No specific Service result codes are defined for Browse. Common StatusCodes are defined in . 5.1.6.3 CancelBrowse 5.1.6.3.1 Description Calling CancelBrowse indicates that the UIP has no further interest in the results of this service. Execution will be stopped when possible. Cancel is a suggestion to the system. Due to asynchronous execution, the service may already be fully or partially completed. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 33 of 145 5.1.6.3.2 Parameters Table 9 defines the parameters for the service. Table 9 – CancelBrowse Service parameters Name Type Description Request serviceId <technology dependent> The identifier of the service to cancel. Response 5.1.6.3.3 Service results No specific Service result codes are defined for CancelBrowse. Successfully cancelled Browse requests shall respond with Bad_RequestCancelled. Common StatusCodes are defined in . 5.1.6.4 Read 5.1.6.4.1 Description This service is used to read Attributes of Object or Variable Nodes. UIPs that need to monitor Variable Attributes for changes shall use the Subscription services instead of Read. 5.1.6.4.2 Parameters Table 10 defines the parameters for the service. Table 10 – Read Service parameters Name Type Description Request returnInnerErrorInfo Boolean A value of “true”requests error information from calls to an underlying system to be returned when available. “false”defines that this information shall not be returned. attributesToRead[] Structure The Attributes to read. node NodeSpecifier The identifier of the Node that contains the Attribute to read. See 5.1.9.3.2 for the definition of the NodeSpecifier type. attributeId AttributeId Numeric identifier of the Attribute to Read. See 5.1.9.3.3. indexRange NumericRange This parameter is used to identify a single element of an array, or a single range of indexes for arrays. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). This parameter is ignored if the specified Attribute is not an array or a structure. However, if the specified Attribute is an array or a structure, and this parameter is null (Null or empty String), then all elements are to be included in the range. See 5.1.9.3.6 for a detailed definition. maxAge UInt32 Maximum age of the value to be read in milliseconds. If the FDI Server has a cached value no older than maxAge, it will return the cached value rather than requesting a new value from the device. If maxAge is set to 0, the FDI Server shall read a new value from the data source. Values greater than 231 -1 (0x7fff ffff) are invalid for maxAge. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 34 of 145 Response readResult [] DataValue The StatusCode, Value and timestamps for each Node Attribute that was read. The order of this list matches the order of the attributesToRead request parameter. 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 attributesToRead request parameter. This list is empty if inner error information was not requested or if no information was encountered in the processing of the request. 5.1.6.4.3 Service results Table 11 defines values for the Service result code. Other common StatusCodes are defined in . Table 11 – Read Service result codes Result code Description Bad_MaxAgeInvalid The max age parameter is invalid. 5.1.6.4.4 Operation result codes Table 12 defines values for the operation status code contained in the DataValue of each readResult element. All operational status codes with their description are in . Table 12 – Read operation result codes Result code Good Good_LocalOverride Good_PostActionFailed Good_DependentValueChanged Uncertain Uncertain_NoCommunicationLastValue Uncertain_LastUsableValue Uncertain_SubstituteValue Uncertain_InitialValue Uncertain_SensorNotAccurate Uncertain_EngineeringUnitsExceeded Uncertain_SubNormal Uncertain_DominantValueChanged Bad Bad_UserAccessDenied Bad_ConfigurationError Bad_NotConnected Bad_DeviceFailure Bad_SensorFailure Bad_OutOfRange Bad_OutOfService Bad_NodeInvalid Bad_AttributeInvalid Bad_IndexRangeInvalid Bad_NotReadable Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 35 of 145 5.1.6.5 CancelRead 5.1.6.5.1 Description Calling CancelRead indicates that the UIP has no further interest in the results of this service. Execution will be stopped when possible. Cancel is a suggestion to the system. Due to asynchronous execution, the service may already be fully or partially completed. 5.1.6.5.2 Parameters Table 13 defines the parameters for the service. Table 13 – CancelRead Service parameters Name Type Description Request serviceId <technology dependent> The identifier of the service to cancel. Response 5.1.6.5.3 Service results No specific Service result codes are defined for CancelRead. Successfully cancelled Read requests shall respond with Bad_RequestCancelled. Common StatusCodes are defined in . 5.1.6.6 Write 5.1.6.6.1 Description This service is used to write values to one or more Variables. For array values, this service allows writing the entire array, writing individual elements or writing ranges of elements. Explicit locking is required (see 5.1.7). If the Node is not locked, the request will be rejected with Bad_LockRequired. The service response is not returned until the write operation has been executed by the system. Rollback is the responsibility of the FDI Client/UIP. The values shall have the correct data type. NOTE No automatic data type translation takes place (see Bad_TypeMismatch operation result code). 5.1.6.6.2 Parameters Table 14 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 36 of 145 Table 14 – Write Service parameters Name Type Description Request returnInnerErrorInfo Boolean A value of “true” requests error information from calls to an underlying system to be returned when available. “false”defines that this information shall not be returned. variablesToWrite[] structure List of Variables to write to. No assumptions should be made about the order of processing this list. If the order matters, separate service requests shall be used. node NodeSpecifier The identifier of the Node that contains the Attribute to write. See 5.1.9.3.2 for the definition of the NodeSpecifier type. indexRange NumericRange See 5.1.9.3.6 for a detailed definition. value Variant Value to write. Response writeResult[] UInt32 Status codes for operation results as defined in Table 15. The order of this list matches the order of the variablesToWrite request parameter. 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 variablesToWrite request parameter. This list is empty if inner error information was not requested or if no information was encountered in processing of the request. 5.1.6.6.3 Service results There are no service results other than the common codes specified in 0. 5.1.6.6.4 Operation result codes Table 15 defines values for the operation status code contained in the writeResult elements. All operational status codes with their description are in . Table 15 – Write operation result codes Result code Good Good_PostActionFailed Bad Bad_UserAccessDenied Bad_NodeInvalid Bad_IndexRangeInvalid Bad_TypeMismatch Bad_OutOfRange Bad_NotWritable 5.1.6.7 CancelWrite 5.1.6.7.1 Description Calling CancelWrite indicates that the UIP has no further interest in the results of this service. Execution will be stopped when possible. Cancel is a suggestion to the system. Due to asynchronous execution, the service may already be fully or partially completed. 5.1.6.7.2 Parameters Table 16 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 37 of 145 Table 16 – CancelWrite Service parameters Name Type Description Request serviceId <technology dependent> The identifier of the service to cancel. Response 5.1.6.7.3 Service results No specific Service result codes are defined for CancelWrite. Successfully cancelled Write requests shall respond with Bad_RequestCancelled. Common StatusCodes are defined in . 5.1.6.8 Subscriptions 5.1.6.8.1 Subscription mechanism Subscriptions allow the UIP to receive unsolicited callbacks from the FDI Client when the subscribed Node Attributes change. Subscriptions are a more efficient way to get periodic updates of data than by issuing repeated calls to the Read service, i.e., polling. The UIP creates a subscription by calling the CreateSubscription service (see 5.1.6.8.2). When the CreateSubscription service is called the UIP shall supply a callback parameter with the UIP-specific DataChangeCallback service (see 5.1.6.8.6). After receiving the subscription identifier in the CreateSubscription response the UIP shall add Node Attributes of interest to the Subscription by calling the Subscribe service. Once the initial values have been reported, the DataChangeCallback service is only called when Node Attributes change and only the Node Attributes that have changed are reported to the callback. The UIP controls the maximum frequency at which the callback should be invoked by specifying a rate in milliseconds. After Node Attributes have been subscribed, their values may not be immediately available and may become available at different times. As such, the initial callback may not include all of the subscribed Node Attributes. Furthermore, it is possible that the initial update for a subscribed Node Attribute will return a Bad or Uncertain StatusCode. Furthermore, the time span between when a change happens and when the callback is invoked depends on where the information to be changed is maintained. Some values are maintained by the system, which allows immediate notification; others are located in the physical device so that communication is required to access it. 5.1.6.8.2 CreateSubscription Service 5.1.6.8.2.1 Description This service is used to create a subscription. 5.1.6.8.2.2 Parameters Table 17 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 38 of 145 Table 17 – CreateSubscription Service parameters Name Type Description Request requestedUpdateRate UInt32 The fastest rate, in milliseconds, at which the UIP requests to be called back with data changes, specified by the minimum milliseconds to elapse between updates. Regardless of the requested rate, a callback only occurs if data has changed. A rate of “0” indicates that the caller wants to be notified of changes as soon as possible. The service will return the fastest possible rate as revisedUpdateRate. dataChangeCallback DataChangeCallback Callback for sending data change updates to the UIP. See 5.1.6.8.6. The DataChangeCallback is a service implemented and provided by the UIP. Response revisedUpdateRate UInt32 The actual rate that the FDI Server will use, expressed as the minimum milliseconds to elapse between updates (if data has changed since the previous update). subscriptionId SubscriptionId The callee-assigned identifier for the subscription. The SubscriptionId type is technology dependent. 5.1.6.8.2.3 Service results Table 18 defines values for the service result. Common results are defined in . Table 18 – CreateSubscription Service result codes Result code Description Bad_TooManySubscriptions The FDI Server has reached its maximum number of subscriptions. 5.1.6.8.3 Subscribe Service 5.1.6.8.3.1 Description This service is used to add one or more Node Attributes to an existing subscription. Subscribing is permitted for all Node Attributes. 5.1.6.8.3.2 Parameters Table 19 defines the parameters for the service. Table 19 – Subscribe Service parameters Name Type Description Request subscriptionId SubscriptionId The identifier for an existing subscription that was returned by the CreateSubscription service. returnInnerErrorInfo Boolean A value of “true” requests error information from calls to an underlying system to be passed in DataChangeCallbacks, when available. “false”defines that this information shall not be returned. monitoredItemsToAdd[] structure The Attributes to add to the subscription. node NodeSpecifier The identifier of the Node that contains the Attribute to subscribe. See 5.1.9.3.2 for the definition of the NodeSpecifier type. attributeId AttributeId Numeric identifier of the Attribute to subscribe. See 5.1.9.3.3. indexRange NumericRange This parameter is used to identify a single element of an array, or a single range of indexes for arrays. If a range of elements is specified, the values are returned as a composite. The first element is identified by index 0 (zero). This parameter is ignored if the specified Attribute is not an array or a Next >