< PreviousField Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100 , Ed. 1.2.0, 23 Jul 2019 Page 9 of 36 The Communication Server implemented scan service (defined in 5.6.1.7) provides the scan result through an XML document (the schema is defined in Clause A.5). The Gateway implemented scan service (defined in 5.6.2.7) provides the scan result by means of the Information Model that contains data structures created from EDD content as specified in 5.6.2.7. Common for both ways of presenting the scan result is that scan results contain device type identification and device instance identification. FDI host systems comparing the actual network topology configuration against the topology representation in the Information Model shall be enabled to handle the following situations: a) The physical Device instance identified at a specific device address is not logically present in the Information Model (as Instance): Enable the FDI Host system to find the appropriate FDI Device Package according to the device catalog information. b) The physical Device instance identified by the device address is logically present in the Information Model (as Instance): Enable the FDI Host system to compare device type information presented in scan result (see the identification in Clause A.5) and the device type specific information of the Instance present in the Information Model. The FDI Device Package contains device type identification information that can be compared to scan result based on the Catalog Schema in IEC 62769-4 defining the XML (simple) element types “DeviceModel” and “Manufacturer”. Both types are used in the (complex) element types “Protocol” and “RegDeviceType”. As a result of the FDI Package deployment the FDI Package information is then present in the Information Model as the specified FunctionalGroup Identification containing SerialNumer and Tag (see 5.4.3). The mapping between different device identification data sources is described in Table 3. Since scan results provided by the Communication Server or Gateway can convey data that is produced by the device (firmware) the device type identification mapping shall be supported by providing corresponding data in the FDI Device Package contained Catalog and Information Model. Table 3 – Device identification information mapping FDI Device Package Information Model Communication Server provided scan result Gateway provided scan result Catalog specified type Manufacturer FunctionalGroup: Identification Browse Name: Manufacturer Element (path): ConnectionPoint/Identification Attribute: Manufacturer COLLECTION ConnectionPoint. Identification: Manufacturer Catalog specified type DeviceModel FunctionalGroup: Identification Browse Name: DeviceModel Element (path): ConnectionPoint/Identification Attribute: DeviceModel COLLECTION ConnectionPoint. Identification. DeviceModel Since not all protocols that are intended to be used with this profile for generic protocols might support a mandatory discovery mechanism allowing to identify the type of device (Manufacturer and DeviceModel), the scan results provide the capability to exclude the identification of the device and only provide the address. In that case some host-specific mechanisms might be used to assign the desired FDI package to the device, e.g. by user interaction. Since some protocols might not even have mandatory capabilities to identify if there is a device at all for a specific protocol address hosts should provide the capability that some users can add devices by manually specifying address information. Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100, Ed. 1.2.0, 23 Jul 2019 Page 10 of 36 5.3.2 Device type revision mapping IEC 62769-4 envisions a concept that allows to determine the compatibility between an FDI Device Package and a Device. IEC 62769-4 specifies a life cycle management process bearing on a single version information provided for the entire device. This is captured in the DeviceRevision (see Table 4). Mapping of version information is protocol-specific and need to be defined in the PSD (see Annex C). Table 4 – Device revision information mapping FDI Device Package Information Model Communication Server provided scan result Gateway provided scan result Catalog specified type ListOfSupportedDeviceRevisions FunctionalGroup: Identification Browse Name: DeviceRevision Element (path): ConnectionPoint/Identification Attribute: DeviceRevision COLLECTION ConnectionPoint. Identification. DeviceRevision 5.4 Information Model mapping 5.4.1 ProtocolType definition In Table 5 a subtype of ProtocolType is defined to identify network communication using this profile. Table 5 – Protocol type GenericProtocol Attribute Value BrowseName GenericProtocol IsAbstract False References NodeClass BrowseName DataType TypeDefinition ModellingRule Subtype of the ProtocolType defined in IEC 62541-100. HasProperty Variable ProtocolIdentifier String PropertyType Mandatory The mandatory Variable ProtocolIdentifier defines which concrete protocol is represented using the GenericProtocol type. It shall match the ProtocolIdentifier defined for the CommunicationProfile in 5.2.2. The string is protocol specific and defined as ProfileIdentifier in the PSD (see Annex C). 5.4.2 DeviceType mapping Each device type inherits the properties of DeviceType. The mapping of the inherited properties from DeviceType is defined in Table 6. Note that only the attributes defined in Annex C and therefore expected by each generic protocol are used. Specific protocols might provide for example a SoftwareRevsion but since this is not accessible for the host this profile does not make use of it. Table 6 – Inherited DeviceType property mapping Property Generic Protocol Mapping SerialNumber SerialNumber (see Annex C) RevisionCounter -1 (not defined) Manufacturer String taken from FDI package catalog (ManufacturerName from PackageT) Model String taken from FDI package catalog (Name of DeviceTypeT, which is a localized name) DeviceManual empty text string (not supported) a DeviceRevision DeviceRevision (see Annex C) Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100 , Ed. 1.2.0, 23 Jul 2019 Page 11 of 36 SoftwareRevision empty string (not defined) HardwareRevision empty string (not defined) a Device manuals are exposed as attachments of the FDI Device Package. 5.4.3 FunctionalGroup identification definition As defined in IEC 62541-100:–, 5.3, each device representation in the FDI Server hosted Information Model shall contain a protocol specific FunctionalGroup named Identification. The Parameters of this FunctionalGroup are defined for generic protocol devices types as follows: Table 7 – Generic Protocol Device Types identification attributes BrowseName DataType Mandatory/Optional Manufacturer String Mandatory DeviceModel String Mandatory SerialNumber String Optional Tag String Optional DeviceRevision UInt16 Optional ProfileId String Optional The BaseDataVariable instances, shall be created from VARIABLE declarations with identifiers that correspond to the browse names listed in Table 7. 5.5 Topology elements 5.5.1 ConnectionPoint definition The ConnectionPoint type GenericConnectionPoint shall be used to parameterize network access points using the generic protocols. The ConnectionPoint type GenericConnectionPoint is a sub type of the abstract type ConnectionPointType defined in IEC 62541-100. Table 8 specifies the representation of the GenericConnectionPoint in the AddressSpace. Table 8 – ConnectionPoint type for Generic Protocols Attribute Value BrowseName GenericConnectionPoint IsAbstract False References NodeClass BrowseName DataType TypeDefinition ModellingRule Sub type of the ConnectionPointType defined in IEC 62541-100. HasProperty Variable Address String PropertyType Mandatory HasProperty Variable ProtocolIdentifier String PropertyType Mandatory The ConnectionPoint type GenericConnectionPoint shall be described by an EDD element contained in a Communication Device related FDI Package that can drive a generic protocol network. Actual ConnectionPoint properties are declared by VARIABLE constructs grouped together in a COLLECTION named ConnectionPoint. For this profile it shall only contain the CONNECTION_POINT_ADDRESS, mapped to the OPC UA Property Address. In addition, the PROTOCOL specified by the COMPONENT shall be mapped to the ProtocolIdentifier Property. The following EDDL source code is an example describing a Connection Point for an ExampleProtocol. The ProtocolIdentifier defined by the PSD (see Annex C) shall be used as PROTOCOL name in the EDD. COMPONENT ConnectionPoint_Generic { Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100, Ed. 1.2.0, 23 Jul 2019 Page 12 of 36 LABEL "Generic Connection Point"; CLASSIFICATION NETWORK_CONNECTION_POINT; CAN_DELETE FALSE; PROTOCOL ExampleProtocol; CONNECTION_POINT ConnectionPoint; } VARIABLE Address { LABEL "Address"; HELP "Address of the device"; TYPE EUC(<protocol-specific>); CLASS LOCAL; } COLLECTION ConnectionPoint { LABEL "Connection Point"; MEMBERS { CONNECTION_POINT_ADDRESS, Address; } } 5.5.2 Communication Device definition According to IEC 62769-7 each FDI Communication Package shall contain an EDD element describing the communication device. The following EDDL source code in is an example describing a Communication Server. COMPONENT Generic_Communication_Server { LABEL "Generic communication server"; PRODUCT_URI "urn:Company Name:Product Name"; CAN_DELETE TRUE; CLASSIFICATION NETWORK_COMPONENT; COMPONENT_RELATIONS { Generic_Communication_Device_Setup } } COMPONENT_RELATION Generic_Communication_Device_Setup { LABEL "Relation between Device and communication device"; RELATION_TYPE CHILD_COMPONENT; COMPONENTS { Generic_Communication_Device{AUTO_CREATE 1;} } MINIMUM_NUMBER 1; MAXIMUM_NUMBER 4; } According to IEC 62769-7 each FDI Communication Package shall contain at least one EDD element describing at least one communication device component. The following EDDL source code in is an example for a generic protocol communication device: COMPONENT Generic_Communication_Device Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100 , Ed. 1.2.0, 23 Jul 2019 Page 13 of 36 { LABEL "Generic communication device"; CAN_DELETE TRUE; CLASSIFICATION NETWORK_COMPONENT; COMPONENT_RELATIONS { Generic_Service_Provider_Relation } } COMPONENT_RELATION Generic_Service_Provider_Relation { LABEL "Relation to communication service provider"; RELATION_TYPE CHILD_COMPONENT; COMPONENTS { Generic_Service_Provider{AUTO_CREATE 1;} } MINIMUM_NUMBER 1; MAXIMUM_NUMBER 1; } In an actual communication device the ConnectionPoint_Generic needs to be adapted according to the supported protocol and the related connection point definitions given in 5.5. The attribute BYTE_ORDER shall not be used for this profile as the byte order handling shall be done in the gateway business logic. 5.5.3 Communication service provider definition According to IEC 62769-7 each FDI Communication Package shall contain at least one EDD element describing at least one communication service provider component. The following EDDL source code below is an example for a generic protocol communication service provider component: The component reference (ConnectionPoint_Generic) corresponds to the related connection point definition in 5.5. The attribute BYTE_ORDER shall not be used for this profile as the byte order handling shall be done in the gateway business logic. COMPONENT Generic_Service_Provider { LABEL "Generic Protocol communication service provider"; CAN_DELETE TRUE; CLASSIFICATION NETWORK_COMMUNICATION_SERVICE_PROVIDER; COMPONENT_RELATIONS { Generic_Service_Provider_Connection_Point_Relation } } COMPONENT_RELATION Generic_Service_Provider_Connection_Point_Relation { LABEL "Relation between communication service provider and Connection Point"; RELATION_TYPE CHILD_COMPONENT; ADDRESSING {Address} COMPONENTS { ConnectionPoint_Generic{ AUTO_CREATE 1;} } MINIMUM_NUMBER 1; MAXIMUM_NUMBER 1; } Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100, Ed. 1.2.0, 23 Jul 2019 Page 14 of 36 5.5.4 Network definition According to IEC 62769-7 each FDI Communication Package shall contain at least one EDD element describing network configuration constraints using the component construct. COMPONENT Network_Generic { LABEL "Generic Network"; CAN_DELETE TRUE; CLASSIFICATION NETWORK; COMPONENT_RELATIONS { Generic_Network_Connection_Point_Relation } } COMPONENT_RELATION Generic_Network_Connection_Point_Relation { LABEL "Relation between network and Connection Point"; RELATION_TYPE CHILD_COMPONENT; ADDRESSING {Address} COMPONENTS { ConnectionPoint_Generic } MINIMUM_NUMBER 1; MAXIMUM_NUMBER 32; } 5.6 Methods 5.6.1 Methods for FDI Communication Servers 5.6.1.1 General The Communication Server contained Information Model shall implement services according to method signatures described in 5.6.1. 5.6.1.2 Connect Signature: Connect( [in] ByteString CommunicationRelationId, [in] String Address, [out] Int32 ServiceError); Table 9 provides the description of the arguments. Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100 , Ed. 1.2.0, 23 Jul 2019 Page 15 of 36 Table 9 – Method Connect arguments Argument Description CommunicationRelationId The argument value contains the nodeId of the ConnectionPoint representing the connection between a device and a physical network which is directly connected to the Communication Server hardware. The nodeId allows finding the direct parent-child relation. Address The argument name shall match with the corresponding attribute name defined for the ConnectionPoint which is described by a corresponding EDD element specified in 5.5. The argument value holds the protocol-specific device’s network address that is unique within the network segment. ServiceError 0: OK / execution finished, connection established successfully -1: Connect Failed / canceled by caller -3: Connect Failed / device not found -4: Connect Failed / invalid device address -5: Connect Failed / invalid device identification 5.6.1.3 Disconnect Signature: Disconnect( [in] ByteString CommunicationRelationId, [out] Int32 ServiceError); Table 10 provides the description of the arguments. Table 10 – Method Disconnect arguments Argument Description CommunicationRelationId The argument value contains the nodeId of the ConnectionPoint representing the connection between a device and a physical network which is directly connected to the Communication Server hardware. The nodeId allows finding the direct parent-child relation. ServiceError 0: OK / disconnect finished successfully -1: Disconnect Failed / no existing communication relation -2: Disconnect Failed / invalid communication relation identifier 5.6.1.4 Transfer Signature Transfer( [in] ByteString CommunicationRelationId, [in] String Header, [in] ByteString RequestData, [in] EddDataTypeInfo[] RequestDataTypes, [in] EddDataTypeInfo[] ResponseDataTypes, [out] ByteString ResponseData, [out] ByteString RESPONSE_CODES, [out] Int32 ServiceError); Table 11 provides the description of the arguments. Table 11 – Method Transfer arguments Argument Description CommunicationRelationId The argument value contains the nodeId of the ConnectionPoint representing the Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100, Ed. 1.2.0, 23 Jul 2019 Page 16 of 36 Argument Description connection between a device and a physical network within the Information Model. Header The protocol-specific information on the data to be transferred. The Header is used in the COMMANDs of the EDD and the PSD (see Annex C) defines the format of this string per protocol. The first communication service treating this string shall validate the string according to its format defined in the PSD. RequestData The argument name shall match with the corresponding COMMAND sub-element name REQUEST. The byte stream submitted trough the argument is created from definitions provided by the REQUEST element of the corresponding COMMAND that shall be processed. RequestDataTypes This array contains information on what data types are used to create the RequestData ByteString The byte order used in the RequestData is EDD specific and providing the information allows the gateway or communication server to change it to a protocol-specific byte order of the data type or applying any other protocol-specific characteristics (e.g. bit order). An empty array can be provided if the protocol’s byte order matches the EDD specific byte order. If the protocol’s byte order does not match the EDD specific byte order, and the provided data types match only part of the RequestData data, the remaining data is considered to require no adaption with respect to the byte order. ResponseDataTypes This array contains information on what data types are expected when receiving the ResponseData ByteString. The knowledge about the expected data types is in the EDD of the device and therefore the gateway or communication server needs to get this information in order to apply protocol-specific characteristics to the response data and knows how to separate the response data into an array of ByteString. An empty array can be provided if the protocol’s byte order matches the EDD specific byte order. If the protocol’s byte order does not match the EDD specific byte order, and the provided data types match only part of the ResponseData, the remaining data is considered to require no adaption with respect to the byte order. ResponseData The argument name shall match with the corresponding COMMAND sub-element name REPLY. The byte stream returned by this argument applies to definitions provided by the REPLY element of the corresponding COMMAND that shall be processed. RESPONSE_CODES The argument name shall match with the COMMAND sub-element name RESPONSE_CODES. The argument value conveys the specific communication service response bytes. ServiceError 0: OK / execution finished -1: Transfer Failed / canceled by caller -3: Transfer Failed / no existing communication relation. -4: Transfer Failed / invalid communication relation identifier -5: Transfer Failed / invalid sendData content -6: Transfer Failed / invalid receiveData format The EddDataTypeInfo DataType defines the data type information of an EDD data type used in a COMMAND. Its elements are defined in Table 12. Table 12 – EddDataTypeInfo DataType Structure Name Type Description EddDataTypeInfo structure This structure specifies information about a data type used in an EDD COMMAND. eddDataType EddDataTypeEnum The EddDataType used. size UInt32 The size of the eddDataType. It shall always be provided, even if not explicitly specified by the EDD. In that case the default value for that data type shall be provided. For data types where no size can be defined (e.g. BOOLEAN) the value shall be set to 0. The EddDataTypeEnum DataType is an enumeration that defines the possible EDD data types. Its values are defined in Table 13. Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100 , Ed. 1.2.0, 23 Jul 2019 Page 17 of 36 Table 13 – EddDataTypeEnum Values Value Description BOOLEAN Data type as defined by IEC 61804-3 DOUBLE Data type as defined by IEC 61804-3 FLOAT Data type as defined by IEC 61804-3 INTEGER Data type as defined by IEC 61804-3 UNSIGNED_INTEGER Data type as defined by IEC 61804-3 DATE Data type as defined by IEC 61804-3 DATE_AND_TIME Data type as defined by IEC 61804-3 DURATION Data type as defined by IEC 61804-3 TIME Data type as defined by IEC 61804-3 TIME_VALUE Data type as defined by IEC 61804-3 BIT_ENUMERATED Data type as defined by IEC 61804-3 ENUMERATED Data type as defined by IEC 61804-3 ASCII Data type as defined by IEC 61804-3 BITSTRING Data type as defined by IEC 61804-3 EUC Data type as defined by IEC 61804-3 OCTET Data type as defined by IEC 61804-3 PACKED_ASCII Data type as defined by IEC 61804-3 PASSWORD Data type as defined by IEC 61804-3 VISIBLE Data type as defined by IEC 61804-3 5.6.1.5 GetPublishedData This method is not supported by the generic protocols profile. 5.6.1.6 SetAddress Signature SetAddress( [in] String OldAddress, [in] String NewAddress, [out] Int32 ServiceError); Table 14 provides the description of the arguments. Field Device Integration (FDI) – Part 100: Profiles – Generic Protocols RELEASED FCG TS62769-100, Ed. 1.2.0, 23 Jul 2019 Page 18 of 36 Table 14 – Method SetAddress arguments Argument Description OldAddress The argument value holds the current address of a device. The same semantic applies to this field as the Address parameter in the Connect method. NewAddress The argument value holds the new address for a device. . The same semantic applies to this field as the Address parameter in the Connect method. ServiceError 0: OK / execution finished successfully -1: SetAddress Failed / canceled by caller -3: SetAddress Failed / not initialized -4: SetAddress Failed / not connected to a network -5: SetAddress Failed / no device found responding to oldAddress -6: SetAddress Failed / duplicate address error -7: SetAddress Failed / device did not accept new address -8: SetAddress Failed / invalid oldAddress (in terms of syntax, data type, data format, and so on) -9: SetAddress Failed / invalid newAddress (in terms of syntax, data type, data format, and so on) -10: SetAddress Failed / not possible in status connected 5.6.1.7 Scan The method signature specified in IEC 62769-7 applies. The corresponding topologyScanResult schema is specified in Clause A.2. 5.6.1.8 ResetScan The method signature specified in IEC 62769-7 applies. 5.6.2 Methods for Gateways 5.6.2.1 General The methods signatures defined in 5.6.2 apply. The methods shall be implemented in the EDD element (IEC 62769-4) contained in a Gateway related FDI Package containing the communication device definitions. 5.6.2.2 Connect Subclause 5.6.2.2 describes the generic protocol specific implementation of the service Connect specified in IEC 62769-7. METHOD BeginConnect( DD_STRING CommunicationRelationId, DD_STRING Address, unsigned long ServiceId, unsigned long &DelayForNextCall, long &ServiceError) { ACCESS ONLINE; DEFINITION{<Gateway specific implementation>} } Next >