< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 19 of 145 3 Terms, definitions, abbreviated terms, acronyms and conventions 3.1 Terms and definitions For the purposes of this document, the terms and definitions given in FCG TS62769-1 as well as the following apply. Terms used for Services 3.1.1.1 Locking Services set of Services through which access to a Device is controlled 3.1.1.2 Device Model Services sub-set of the Device Access Services through which a UIP can access the information of a Device 3.1.1.3 Direct Access Services sub-set of the Device Access Services through which a UIP can directly access a Device Terms used for Device Access Services 3.1.2.1 Attribute information element of a Node Note 1 to entry: Some Attributes exist for all NodeClasses and some are specific to a given NodeClass. Note 2 to entry: Supersedes the definition given in FCG TS62769. 3.1.2.2 Device Model hierarchy of Nodes that represents an existing Device 3.1.2.3 Node element in the Device Model that can be addressed via the Device Access Services Note 1 to entry: Supersedes the definition given in FCG TS62769. 3.1.2.4 NodeClass either an Object or a Variable Note 1 to entry: Supersedes the definition given in FCG TS62769. 3.1.2.5 Object instance of the Object NodeClass Note 1 to entry: Supersedes the definition given in FCG TS62769. 3.1.2.6 Variable instance of the Variable NodeClass Note 1 to entry: Supersedes the definition given in FCG TS62769. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 20 of 145 3.2 Abbreviated terms and acronyms For the purposes of this document, the abbreviated terms and acronyms given in FCG TS62769 and the following apply. UTC Coordinated Universal Time XML Extended mark-up language 3.3 Conventions Conventions for service definitions are identical to IEC 62541-4. Basic data types used are defined in IEC 62541-3. “Parameter" is always an Information Model Parameter. "parameter" is the general use of the word. If ambiguous, additional context is given. 4 Overview An FDI Package provides the necessary information for a Device Type to allow managing the Device within the system. It is provided by a device vendor and deployed in an FDI Server. It may contain two types of user interface components that are available to the FDI Client for display to a user. An FDI Package may contain only one type or both types. The two types are referred to as User Interface Plug-ins and User Interface Descriptions. A User Interface Plug-in (UIP) is an executable element. A UIP is provided by an FDI Package and transferred to the FDI Client by the FDI Server. A UIP provides a set of UIP Services that the FDI Client uses to initialize and interact with the UIP. NOTE 1 FCG TS62769-6 and its sub parts define application programming interfaces for the services described in this document. User Interface Descriptions (UIDs) are defined using EDDL. A UID is provided to the FDI Client by the FDI Server. The FDI Client uses the UID Interpreter to interpret and execute the UID. A UID may make use of other UID and UIP components as subcomponents in order to provide a modular approach and make the best use of both descriptive and executable user interface elements. NOTE 2 UIPs can make use of other UIPs but not of other UIDs. The FDI Server makes UIDs and UIPs available to the FDI Client via the Information Model. The Information Model organizes the UIDs and UIPs by Device Type. The FDI Client provides the execution environment for UIPs. The FDI Client loads the UIP from the FDI Server. The FDI Client’s UIP execution environment consists of the following sets of services that are made available to the UIP: • Device Access Services • Hosting Services • User Interface Services • Printing Services (if available in the hosting environment) NOTE 3 It is implementation specific whether different UIPs get the same or different interface instances to access these services. The only requirement is that there is no side-effect if two UIPs use the same instance of an interface. Similar to the FDI Client, each UIP shall also provide a set of services (UIP Services) by which the FDI Client activates, controls and shuts down UIPs (see 6.1). Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 21 of 145 The Device Access Services enable interaction between the UIP and the FDI Server-maintained Information Model. The FDI Client takes care of the interaction with the FDI Server freeing the UIP to focus on the application level only. UIP access to the Information Model (IM) via the Device Access Services is restricted to the Device and its sub- devices. The Hosting Services are provided by the FDI Client for use by the UIP. The Hosting Services include services related to the FDI Client allowing the UIP to acquire information about the environment. The User Interface Services provide the means by which the UIP accesses the user interface services of the underlying operating system. These services provide access to the screen, keyboard, mouse, and other operating system resources. The User Interface Services are defined by the chosen implementation technology and therefore no additional definitions are included in this document (see FCG TS62769-6 and its sub parts for the individual technologies). UIPs shall use the Hosting Services to display message boxes or progress bars and shall never use comparable services provided by the underlying operating system. There are no printing services provided by the Client. If a UIP needs to generate a printout it accesses the printing services of the underlying operating system. No additional definitions are included in this document. The FDI Client uses the culture setting of the currently signed-in user for the execution environment of the UIP. It uses the culture when creating OPC UA Sessions and it sets the culture for each thread it creates. UIPs shall take care for culture setting in all threads that they create. The FDI Client provides a UID Interpreter that is used to interpret and execute UIDs. The UID XML Schema is defined in this document (see Annex A). Business Logic is executed in the FDI Server. Some Business Logic may be exposed to the FDI Client as Actions (see Clause 7) and can be triggered by FDI Clients. 5 FDI Client 5.1 Device Access Services General The Device Access Services provide access to both the online and offline information of a Device or its components as defined by the FDI Package, in particular for • browsing the Device Model, • reading / writing of data and subscribing to data changes, • controlling access to the Device, and • directly communicating with the Device. The scope for the Device Access Services will be a Device, Block, or Communication Server to which the UIP is assigned. The FDI Client is expected to map the Device Access Services to OPC UA services provided by the FDI Server. The main Services are the Device Model Services to view and access Parameters. The Locking Services are used to control simultaneous access to a Device. The Direct Access Services allow a UIP to communicate with the Device. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 22 of 145 Whether and how the different services are mapped to real interfaces is defined in FCG TS62769-6 and its subparts for the individual technologies. FCG TS62769-6 and its subparts also specify how interfaces are obtained. Device Model The Device Model defines the structure of all data that are available to a UIP. It is confined to a single device instance. The entities in the structure (Parameters, Images, and Documents) are built from FDI Package information. User interface elements, like Menus, Graphs, Waveforms, are not part of the UIP Device Model. All Device elements are organized as a defined hierarchy. The root of the hierarchy can be either a Device or a Block subject to where (by which MENU) the UIP is referenced in the User Interface Description of the FDI Package (see FCG TS62769-4). The Nodes in the hierarchy are either Objects or Variables, where the main difference is that Variables provide a Value. Figure 2 illustrates the overall structure of a Device. Figure 3 shows the structure of a block in more detail. The elements that will really be available depend on the contents of the respective FDI Package. Regular rectangles represent Object Nodes while the ones with rounded corners represent Variable Nodes. These NodeClasses are defined in 5.1.3. The top left Node is the root Node. The single hashed lines define the parent-child relationship in the hierarchy. As an example, the children of Device1 in Figure 2 are ParameterSet, ImageSet, Documentation, Blocks and SubDevices. The children of /SubDevices/Device_1b/ImageSet are Image_1 and Image_2. Modular Device Block-Oriented Device Device1 ParameterSet Param_1 Param_2 Param_n SubDevices Device_1a Device_1b Blocks ParameterSet Param_1 Param_2 Param_n Blocks ImageSet Image_1 Image_2 ImageSet Image_1 Image_2 Documentation Document_1 Document_2 Documentation Document_1 Document_2 Figure 2 – Overall structure of a Device Names that are in normal font are defined by the Device Access Services; names in italics are just place-holders for the real names as defined in the FDI Package. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 23 of 145 Device1 Blocks Block_x Block_y ParameterSet Param_1 Param_2 Param_n Figure 3 – Structure of Blocks Each Node in the hierarchy is uniquely qualified with its pathname. This pathname is a concatenation of the individual Node Name Attributes. The separator is “/”. EXAMPLE The following examples illustrate qualified pathnames: / -- the root Node (here “Device1”) /ParameterSet/Param_2 -- a Variable Node /SubDevices/Device_1b/ImageSet/Image_1 -- a picture Certain Variables in the FDI Package may be tagged as “private” meaning they are non-browsable. Though they are non-browsable, they exist in the Device Model and can be addressed with their pathname. Node model 5.1.3.1 General The information of a Device is organised as a hierarchy of Nodes. Each Node is either an Object or a Variable. Both Object and Variable are derived from the BaseNodeClass, as illustrated in Figure 4. Variable BaseNodeClass Object Figure 4 – Device Model NodeClasses 5.1.3.2 BaseNodeClass This is the abstract parent NodeClass for Object and Variable Nodes. The BaseNodeClass Attributes are shown in Table 1. The Attributes of this NodeClass are available in both Object and Variable NodeClasses. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 24 of 145 Table 1 – BaseNodeClass Attributes Attribute Datatype Description NodePath String Qualified path of the Node in the Device Model. This Attribute is returned by the Browse Service and cannot be read or written. Name String Name of Node according to device specific documentation. Label LocalizedText Human readable label of the Node. Description (optional) LocalizedText Human readable help string describing the Node. Additional Attributes will be available for derived NodeClasses. For example, a Variable will have Attributes that define the DataType and the AccessRights. 5.1.3.3 Object NodeClass Table 2 contains the list of Attributes for Objects beyond those inherited from the Base NodeClass: Table 2 – Object NodeClass Attributes Attribute Datatype Description LockedStatus Boolean This Attribute when “true” indicates that this Object is currently locked. The service result code Bad_AttributeInvalid defines that locking is not supported for this Object at all. 5.1.3.4 Variable NodeClass 5.1.3.4.1 General Variables are used to represent Parameters, images and documents. When reading Variables that represent images or documents the system will provide them as a ByteString. For documents, the Name Attribute will consist of the filename including the extension that can be used to identify the document type. FDI supports “.pdf” and “.txt”. For the representation of images see 5.1.3.4.2. Table 3 contains the list of Attributes for Variables beyond those inherited from the BaseNodeClass: Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 25 of 145 Table 3 – Variable NodeClass Attributes Attribute Datatype Description Value Variant The value of the Variable as returned from the device (i.e. without applying the ScalingFactor). The Variant is specified in 5.1.9.4. DataType UInt32 The DataType Attribute specifies the data type of the Value Attribute. One of the data types specified in 5.1.9. FCG TS62769-6 and its sub parts specify the assignment of unique identifiers to each type. ValueRank Int32 Indicates whether the Value Attribute is an array. It may have the following values: >1 (MoreDimensions) – the value is an array with the specified number of dimensions. 1 (OneDimension) – the value is an array with one dimension. 0 (OneOrMoreDimensions) – the value is an array with one or more dimensions. -1 (Scalar) – the value is not an array. -2 (Any) – the value can be a scalar or an array with any number of dimensions. -3 (ScalarOrOneDimension) – the value can be a scalar or a one dimensional array. ArrayDimensions (optional) UInt32[] Specifies the length of each dimension for an array value. The Attribute is intended to describe the capability of the Variable, not the current size. The number of elements shall be equal to the value of the ValueRank Attribute. Shall be null if ValueRank <= 0. A value of 0 for an individual dimension indicates that the dimension has a Variable length. For example, if a Variable is defined by the following C array: Int32 myArray[346]; then this Variable’s DataType would point to an Int32, the Variable’s ValueRank has the value 1 and the ArrayDimensions is an array with one entry having the value 346. AccessRights Byte The access rights for the Value. An enumeration with one of the following values: NONE_0 The Variable value cannot be accessed READ_1 The value of the Variable may be read WRITE_2 The value of the Variable may be written READORWRITE_3 The value of the Variable may be read or written UserAccessRights Byte This Attribute specifies the access rights to the Value for the currently authenticated user. They may be less than the potential access rights. The same enumeration as for AccessRights is used. ScalingFactor (optional) Double This Attribute specifies a suggested scaling factor. Note that the Value Attribute contains the raw value returned from the device. It is assumed, that the (raw) value is multiplied by this factor before being displayed. EngineeringUnits (optional) EUInformation EngineeringUnits specifies the units for the value (e.g., °C, hertz, seconds). See 5.1.9.3.8 for the definition of the EUInformation data type. Attributes for analog Variables (Variables that represent continuously-variable physical quantities (e.g., pressure, temperature)). EURange (optional) Range[] Defines one or more value ranges likely to be obtained in normal operation. They are intended for such use as automatically scaling a bar graph display. Sensor or instrument failure or deactivation can result in a returned item value that is actually outside this range. UIP software shall be prepared to deal with this. See 5.1.9.3.7 for the definition of the Range data type. Ranges may change during operation, for example by changing the operation mode of an instrument. Like the Value itself, Ranges are always unscaled (i.e. without applying the ScalingFactor). Attributes for discrete (enumerated) Variables (for data that may take on only a certain number of possible values (e.g., OPENING, OPEN, CLOSING, CLOSED). CurrentLabel String Enumerated Variables expose the current numeric state in their Value Attribute.The CurrentLabel Attribute provides the name of the current enumeration value. EnumValues EnumValuesType[] EnumValues is an array of {StateValue, Enumeration Name, and Help Information}. See 5.1.9.3.9 for the definition of this type. FDI Clients/UIPs may read this Attribute in advance and store it for lookup of name or help when they receive the numeric representation. Attributes for bit-enumerated Variables Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 26 of 145 Attribute Datatype Description (for data that represent a bit mask). OptionNames String[] Bit-enumerated Variables transmit a bit mask encoded in an unsigned integer of a length that is sufficient to represent all bits. The OptionNames Attribute provides a human-readable representation for each valid bit of the bit mask. The order of the bits of the bit mask points to a position of the array of Strings in the OptionNames Attribute, i.e., the first bit points to the first entry in the array, and so on. The array contains an empty String for each bit that has no specific meaning. 5.1.3.4.2 Representation of images All images have the DataType and are transferred as a ByteString. FDI supports three image formats. To identify the format of the image provided in the ByteString, the initial bytes have to be parsed as outlined in the following table. Image type Description GIF Defines an image in GIF (Graphics Interchange Format). GIF is specified in http://www.w3.org/Graphics/GIF/spec-gif89a.txt . The first bytes of a GIF image are as follows: Byte 1 2 3 Hex 47 49 46 JPG Defines an image in JPG (Joint Photographic Experts Group File Interchange Format). JPG is defined in ISO/IEC 10918-1. The first bytes of a JPG image are as follows: Byte 1 2 3 4 Hex FF D8 FF E0 PNG Defines an image in PNG (Portable Network Graphics format). PNG is defined in IEEE 754, IEEE Standard for Floating-Point Arithmetic IETF RFC 2083 and ISO/IEC 15948. The first bytes of a PNG image are as follows: Byte 1 2 3 4 5 6 7 8 Hex 89 50 4E 47 0D 0A 1A 0A 5.1.3.4.3 Representation of records A Variable hierarchy is used to represent EDDL RECORD Parameters. The root Variable represents the record itself. It will have component Variables that represent the EDDL RECORD MEMBERS (the MEMBERS of an EDDL RECORD are defined in EDDL by means of a reference to an EDDL VARIABLE.). An example of how a record is represented in the Device Model is shown in Figure 5. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 27 of 145 Param_A PARAMETERS { Param_A, rec1 ; Param_B, rec2 ; … RECORD rec1 { LABEL "Rec1"; MEMBERS { X, x_member1; Y, y_member1; } } VARIABLE x_member1 { LABEL "X"; TYPE FLOAT; HANDLING READ; } VARIABLE y_member1 { LABEL "Y"; TYPE ENUM (1); HANDLING WRITE; } … X (AccessLevel=Read) Y (AccessLevel=Write) Param_B X (AccessLevel=Read) Y (AccessLevel=Write) RECORD rec2 { LABEL "Rec2"; MEMBERS { X, x_member2; Y, y_member2; } } VARIABLE x_member2 { LABEL "X"; TYPE FLOAT; HANDLING READ; } VARIABLE y_member2 { LABEL "Y"; TYPE ENUM (1); HANDLING WRITE; } Some Device ParameterSet Figure 5 – Example: Variable hierarchy representing a RECORD The Name and Label Attributes of the root Variable are set to the name of the RECORD and the LABEL Attribute, respectively. The DataType Attribute of the “root” Variable is Variant. The ValueRank Attribute is used to specify that the Value contains an array. The Value Attribute represents the values of all members in the order as defined for the RECORD. According to the example in Figure 5, the first variant will be a FLOAT and the second will be an ENUM. For each component Variable that represents an EDDL RECORD MEMBER • the Name Attribute is set to the identifier of the corresponding EDDL VARIABLE, • the Label is the LABEL Attribute of the corresponding EDDL VARIABLE, • the Description is the HELP Attribute of the corresponding EDDL VARIABLE, and • the AccessRights Attribute is derived from the EDDL HANDLING Attribute. Each member of the record can be accessed with its pathname as specified above. Browsing can also be used. EXAMPLE Example of a pathname: /ParameterSet/Param_A/X. 5.1.3.4.4 Representation of arrays, and lists of members with simple data types A single Variable will represent an EDDL VALUE_ARRAY or LIST item when the data type of the referenced array element has a simple data type. The DataType Attribute is set to one of the base data types (see 5.1.9.2). Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 28 of 145 The ValueRank Attribute is used to specify that the Value contains an array. In case of an EDDL VALUE_ARRAY the number of elements is exposed via the ArrayDimensions Attribute. In the case of an EDDL LIST the number of elements is unspecified since the size can change dynamically. 5.1.3.4.5 Representation of arrays, and lists of RECORDs Value arrays or lists of non-simple EDDL Parameters will be represented as an array of Variable hierarchies. Figure 6 shows the EDDL sample code of a VALUE_ARRAY of RECORDs and the corresponding Variable hierarchy. ParameterSet v_arr va_elem_rec_1 va_elem_rec_2 X Y X Y PARAMETERS { Param_C, v_arr ; … } VALUE_ARRAY v_arr { LABEL “V Arr”; TYPE va_elem_rec; NUMBER_OF_ELEMENTS 2; } RECORD va_elem_rec { LABEL "VA Element"; MEMBERS { X, x_member3; Y, y_member3; } } VARIABLE x_member3 { LABEL "X"; TYPE FLOAT; HANDLING READ; } VARIABLE y_member3 { LABEL "Y"; TYPE ENUM (1); HANDLING WRITE; } Figure 6 –Variable hierarchy representing a VALUE_ARRAY of RECORDs The Name and Label Attributes of the root Variable are set to the name of the ARRAY and the LABEL Attribute, respectively. The DataType Attribute of the “root” DataVariable is Variant. The ValueRank Attribute is used to specify that the Value contains an array. The Value Attribute represents all VALUE_ARRAY entries. The first Variant corresponds to the first array entry and so on. Each Variant in turn contains an array. This may either be an array of simple types or an array of Variants. A RECORD is always represented as an array of Variant. The VALUE_ARRAY element, which is in fact a RECORD, is represented as a component Variable hierarchy. The Name and Label Attributes of each root Variable representing a RECORD are set to the name of the RECORD and the LABEL Attribute, respectively. The array index (_1, _2) is appended to allow unique identification. Note that the index always begins with ‘1’. The RECORD MEMBERS are also represented as component Variables as specified in 5.1.3.4.3. Members of each record can be accessed with a pathname. Browsing can also be used. EXAMPLE Example of a pathname: /ParameterSet/v_arr/va_elem_rec_2/Y. Services 5.1.4.1 General All Services specified in this part of FCG TS62769 rely on the conventions defined in 5.1.4.2. They are specified in an abstract manner with request and response parameters in a single table. Next >