< PreviousField Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4 , Ed. 1.2.0, 21 Jun 2019 Page 39 of 79 Annex D (informative) Example D.1 General The purpose of Annex D is to provide an overview of ISO/IEC 29500-2 and an example FDI Device Package implementation. It is not intended to provide all the details that might be necessary for the implementation of an FDI Package. Unless otherwise stated in Annex D, the acronym OPC refers to Open Packaging Conventions. D.2 Open Packaging Conventions D.2.1 Overview The Open Packaging Conventions (OPC) are a container-file technology specified in ISO/IEC 29500-2. OPC-based documents are ZIP archives that contain XML, binary and other types of files. They combine the advantages of maintaining the independence and the integrity of the files embedded in the document while having a single integrated package. An OPC package consists of parts and relationships as shown in Figure D.1. Parts refer to the content being packaged such as binary and text files. Relationships define associations between the package, parts and external resources. Package Relationship Part A1 Relationship Part A2 Relationship Part A3 Relationship Part A4 Figure D.1 – Parts and relationships in a package D.2.2 Parts OPC packages can store parts that contain any type of data (text, images, XML, binary, whatever). Parts can be organized as a hierarchy of folders that is similar to a file system. The OPC specification allows any folder organization that is convenient for the application. Every part in a package has a unique URI-compliant part name along with a specified content-type expressed in the form of a MIME media type. The MIME media types for all the parts stored in the package are defined in an XML file named "/[Content_Types].xml". Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4, Ed. 1.2.0, 21 Jun 2019 Page 40 of 79 In an FDI package, the parts include the package catalog, EDD, UIPs and attachments. D.2.3 Relationships In addition to a hierarchy of folders and parts, OPC allows the definition of relationships among parts. Relationships provide a layer of indirection so dependencies are not hardcoded into the content. Relationships allow problem domain and application specific relationships to be defined and enforced by systems and tools. By navigating through the network of associations one can have random access to related content. Relationships are composed of four elements: • an identifier (ID) • an optional source (the package or a part within the package) • a relationship type (a URI-style expression that defines the type of the relationship) • a target (a URI to another part within the package or to an external resource) The relationships are stored in XML files with the extension ".rels" within subfolders named "/_rels". In an FDI package, the relationships are used to express the association of the package to the package catalog, the EDD, the UIP and the attachments. The following clause, for instance, defines the relationship identified as “rIdUip1”, which establishes the association between the package and the package catalog. <Relationship Id="rIdUip1" Type="http://fdi-cooperation.com/2010/relationships/package-catalog" Target="fdipackage/catalog.xml"/> D.2.4 OPC Core Features D.2.4.1 Overview The content types file /[Content_Types].xml, the package relationships file /_rels/.rels, and the part relationships files in the subfolders _rels are the core parts of an OPC package. The filename [Content_Types].xml in any folder, the subfolder name _rels, and the file extension .rels within such directory are the only three reserved names for files stored in an OPC package. D.2.4.2 Content Types The file /[Content_Types].xml defines the MIME media types for all the parts stored in the package. It defines default mappings based on file extensions, along with overrides for specific parts with content-types that are different from the file extension defaults. Table D.1 and Table D.2 show examples of standard MIME media types and examples of FDI-custom MIME media types that may be used in FDI packages. Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4 , Ed. 1.2.0, 21 Jun 2019 Page 41 of 79 Table D.1 – Examples of standard MIME media types that can be used in FDI packages Type of content Standard MIME media type XML file application/xml PNG image image/png PDF document application/pdf OPC relationships application/vnd.openxmlformats-package.relationships+xml Table D.2 – Examples of FDI-custom MIME media types that can be used in FDI Packages Type of content FDI-custom MIME media type Package catalog application/vnd.fdi.package.catalog+xml EDD application/vnd.fdi.package.edd UIP application/vnd.fdi.package.uip The following clause in the /[Content_Types].xml file defines the default MIME media type for any XML files in the package. <Default Extension="xml" ContentType="application/xml"/> The following clause in the same file will override the definition above for the package catalog part only: <Override PartName="/fdipackage/catalog.xml" ContentType="application/vnd.fdi.package.catalog+xml"/> D.2.4.3 Package Relationships The root level /_rels folder stores the relationships for the package as a whole. The /_rels folder normally contains a file named .rels, an XML file where the starting package-level relationships are stored. D.2.4.4 Part Relationships Each part may have its own relationships. If the part has relationships, they will be stored in an XML file within the _rels folder that is a sibling of that part. That file takes the part name with a .rels appended to it. Because the Package Catalog part has relationships to other package parts, there is a file named catalog.xml.rels inside the /_rels folder that defines those relationships. D.2.5 OPC Additional features D.2.5.1 Core Properties Core properties consist of package metadata. They enable users to get and set well-known and common sets of property metadata within packages, such as categorization of the content, status of package (e.g., draft, reviewed, final), date of creation, identification of the creator, keywords, and language. The core properties are not used in FDI Packages (see 5.2). D.2.5.2 Thumbnails Thumbnails are images that are used as graphical representation of parts of a package or a package as a whole. The use of thumbnails in an FDI Package is optional (see 5.2). Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4, Ed. 1.2.0, 21 Jun 2019 Page 42 of 79 D.2.5.3 Digital Signatures Digital signatures can be used to enable consumers to validate the integrity of the contents. The use of digital signatures is mandatory in FDI Packages (see 5.2). D.3 Creation and Handling of FDI Packages As long as the conventions are followed, OPC files can be created, opened and modified just as any ordinary ZIP file by using standard ZIP file tools. However, there exists higher level support to handle them so that developers do not have to cope with all the peculiarities of OPC. OPC is natively supported in Microsoft .NET Framework 3.0. Open source libraries also exist for other languages. Ultimately, FDI specific tools are expected to provide automated support for the creation and handling of FDI packages. Given the catalog information, the EDD, the UIPs and attachments for a specific device type, a hypothetical FDI packaging tool is capable of creating the FDI package for that device type, as depicted in Figure D.2. Package UIP Attachment Catalog Information FDI Packaging Tool UIP UIP Attachment Attachment EDD EDDUIP UIP UIP Att Att Att Cat. Figure D.2 – Creating an FDI Package with the content files D.4 FDI Device Package Example D.4.1 Overview Figure D.3 represents an example FDI Device Package. The root directory of the FDI Device Package contains three directories and one file. The directory names fdipackage and uip are examples and are not defined by this standard. The _rels directory is used to store the package relationships and is defined by ISO/IEC 29500-2. Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4 , Ed. 1.2.0, 21 Jun 2019 Page 43 of 79 fdipackage attachments 010101.cff companylogo.png datasheet.pdf deviceimage.png manual.pdf edd device.edd _rels catalog.xml.rels catalog.xml uip fancytrend.uip _rels .rels [content_types].xml Figure D.3 – FDI Device Package Example The file [Content_Types].xml is defined by ISO/IEC 29500-2 and defines the content type of the parts in the package. It is required for all packages. All parts in the package shall have a content type identified by this file. An example for /[Content_Types].xml is listed below. <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"> <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/> <Default Extension="xml" ContentType="application/xml"/> <Default Extension="uip" ContentType="application/vnd.fdi.package.uip"/> <Default Extension="png" ContentType="image/png"/> <Default Extension="pdf" ContentType="application/pdf"/> <Default Extension="edd" ContentType="application/vnd.fdi.package.edd"/> <Default Extension="cff" ContentType="application/vnd.ff.cff"/> <Override PartName="/fdipackage/catalog.xml" ContentType="application/vnd.fdi.package.catalog+xml"/> </Types> In this example, the Package Catalog is identified by the part /fdipackage/catalog.xml with content type application/vnd.fdi.package.catalog+xml in the /[Content_Types].xml. The device has a protocol specific CFF file. It is the responsibility of the protocol organization to define the content type associated with that file type. The content type for the CFF is an example and is not currently specified by the Fieldbus Foundation. The /rels/.rels part defines the package relationships per ISO/IEC 29500-2. Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4, Ed. 1.2.0, 21 Jun 2019 Page 44 of 79 An example for /rels/.rels is listed below. <?xml version="1.0" encoding="UTF-8" ?> <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"> <Relationship Id="rId1" Type="http://fdi-cooperation.com/2010/relationships/package-catalog" Target="fdipackage/catalog.xml"/> <Relationship Id="rIdUip1" Type="http://fdi-cooperation.com/2010/relationships/uip" Target="uip/fancytrend.uip"/> </Relationships> According to this standard, the Package Catalog shall be identified by a single package relationship. The FDI Server identifies the Package Catalog part by retrieving the part associated with this standard relationship type. In this example, the catalog relationship is represented by <Relationship Id="rId1" Type="http://fdi-cooperation.com/2010/relationships/package-catalog" Target="fdipackage/catalog.xml"/> The value for relationship id is not specified by this standard. ISO/IEC 29500-2 requires that each relationship have a unique relationship id. An FDI Device Package may also provide one or more UIPs. According to this standard, a UIP shall be identified by a package relationship. The FDI Server identifies a UIP in a package by searching for all parts with the associated relationship type. In this example, a single UIP is identified by <Relationship Id="rIdUip1" Type="http://fdi-cooperation.com/2010/relationships/uip" Target="uip/fancytrend.uip"/> An example for /fdicatalog/catalog.xml is listed below. <?xml version="1.0" encoding="UTF-8"?> <fdi:Catalog xmlns:fdi="http://fdi-cooperation.com/2010/package" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://fdi-cooperation.com/2010/package catalog.xsd"> <PackageId>ef377fd0-5de5-11df-a08a-0800200c9a66</PackageId> <PackageType>Device</PackageType> <Version>01.00.00</Version> <FdiVersionSupported>01.00.00</FdiVersionSupported> <ManufacturerName>ACME Transmitters</ManufacturerName> <ManufacturerContact>42 Wallaby Way, Sydney, Australia</ManufacturerContact> <ManufacturerUrl>http://acme.local</ManufacturerUrl> <ManufacturerImage>rIdMfrLogo</ManufacturerImage> <ListOfDeviceTypes> <DeviceType> <Name> <value>Temperature Transmitter</value> <value xml:lang="fr">Transmetteur de température</value> <value xml:lang="de">Temperatur-Transmitter</value> </Name> <ClassificationId>SENSOR_TEMPERATURE</ClassificationId> <ListOfInterfaces> <Interface> <ListOfCommunicationProfiles> <CommunicationProfile>foundation_h1</CommunicationProfile> </ListOfCommunicationProfiles> <Version>05.00.00</Version> Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4 , Ed. 1.2.0, 21 Jun 2019 Page 45 of 79 <Manufacturer>0xff00</Manufacturer> <DeviceModel>0x1234</DeviceModel> <CommunicationRole>CLIENT</CommunicationRole> <ListOfCommunicationProfileSupportFiles> <CommunicationProfileSupportFile>rIdCFF</CommunicationProfileSupportFile> </ListOfCommunicationProfileSupportFiles> </Interface> </ListOfInterfaces> <Edd>rIDEDD</Edd> <ListOfSupportedDeviceRevisions> <DeviceRevision>01.00.00</DeviceRevision> </ListOfSupportedDeviceRevisions> <ListOfImages> <Image>rIdPicture1</Image> </ListOfImages> <ListOfDocuments> <Document>rIdDocument1</Document> <Document>rIdDocument2</Document> </ListOfDocuments> <ListOfSupportedUips> <SupportedUip> <UipId>f67e4ad0-5de5-11df-a08a-0800200c9a66</UipId> <Name>Fancy Trend</Name> <Version>01.01.*</Version> <Optional>true</Optional> </SupportedUip> </ListOfSupportedUips> </DeviceType> </ListOfDeviceTypes> </fdi:Catalog> The Package Catalog part will reference other package parts through relationship ids. Those relationship ids will be defined in a relationship file name by the part and appended with the .rels suffix. In this example, this part is named fdipackage/_rels/catalog.xml.rels. An example for /fdipackage/_rels/catalog.xml.rels is listed below. The relationship ids are not defined by this standard. According to ISO/IEC 29500-2, these relationship ids shall be unique. The id names in this example were selected to better illustrate referencing. <?xml version="1.0" encoding="UTF-8"?> <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"> <Relationship Type="http://fdi-cooperation.com/2010/relationships/edd" Target="edd/device.edd" Id="rIdEDD"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-image" Target="attachments/deviceimage.png" Id="rIdPicture1"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-documentation" Target="attachments/datasheet.pdf" Id="rIdDocument1"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-documentation" Target="attachments/manual.pdf" Id="rIdDocument2"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-protocol" Target="attachments/010101.cff" Id="rIdCFF"/> </Relationships> In this example, the product documentation is identified by the following. Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4, Ed. 1.2.0, 21 Jun 2019 Page 46 of 79 <ListOfDocuments> <Document>rIdDocument1</Document> <Document>rIdDocument2</Document> </ListOfDocuments> The catalog identifies the files by the relationship ids that are found in the corresponding /fdipackage/_rels/catalog.xml.rels. <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-documentation" Target="attachments/datasheet.pdf" Id="rIdDocument1"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/attachment-documentation" Target="attachments/manual.pdf" Id="rIdDocument2"/> The example FDI Device Package identifies one supported UIP. <SupportedUip> <UipId>f67e4ad0-5de5-11df-a08a-0800200c9a66</UipId> <Name>Fancy Trend</Name> <Version>1.1.*</Version> </SupportedUip> This standard permits UIPs to be delivered in the FDI Device Package, or the UIPs may be delivered in a separate FDI UIP Package. In this example, the UIP is delivered in the FDI Device Package. UIPs are also encoded using ISO/IEC 29500-2, but they are not considered a valid FDI Package type. An FDI server will not directly consume a UIP. A UIP shall be encoded in a valid FDI Package as shown in this example. D.4.2 User Interface Plug-in The following example is for the UIP referenced from the example FDI Package in Clause D.4. This UIP has two variants, one targeted for the workstation and the other for a mobile environment. The UIP part is encoded according to ISO/IEC 29500-2. Figure D.4 shows the structure of the example UIP. In this example, the filename for the UIP is fancytrend.uip, and is explicitly referenced in the package relationship id in Clause D.4. uip _rels uipcatalog.xml variant1.zip variant2.zip _rels .rels [content_types].xml Figure D.4 – User Interface Plug-in Example (fancytrend.uip) Similar to the example in Clause D.4, a package conforming to ISO/IEC 29500-2 shall have a /[content_types].xml and _rels/.rels part. In this example, the directory name uip is only an example and not specified by this standard. An example for [Content_Types].xml is listed below. Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4 , Ed. 1.2.0, 21 Jun 2019 Page 47 of 79 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"> <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/> <Default Extension="xml" ContentType="application/xml"/> <Default Extension="zip" ContentType="application/zip"/> <Override PartName="/uip/uipcatalog.xml" ContentType="application/vnd.fdi.package.uip.catalog+xml"/> </Types> An example for _rels/.rels part is listed below. <?xml version="1.0" encoding="UTF-8"?> <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"> <Relationship Id="rId1" Type="http://fdi-cooperation.com/2010/relationships/uip-catalog" Target="uip/uipcatalog.xml"/> </Relationships> According to this standard, the UIP Catalog part shall be identified by a package relationship. This is represented by the following code of the _rels/.rels part. <Relationship Id="rId1" Type="http://fdi-cooperation.com/2010/relationships/uip-catalog" Target="uip/uipcatalog.xml"/> The relationship id is only an example. The relationship type allows an FDI Server to identify the part corresponding to the UIP Catalog. In this example, the catalog is the /uip/uipcatalog.xml part. An example for /uip/uipcatalog.xml list listed below. <?xml version="1.0" encoding="UTF-8"?> <fdi:UipCatalog xmlns:cat="http://fdi-cooperation.com/2010/package" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <UipId>f67e4ad0-5de5-11df-a08a-0800200c9a66</UipId> <Name>Fancy Trend</Name> <Version>1.0.0</Version> <FdiVersionSupported>1.0.0</FdiVersionSupported> <Additional>Best trend ever</Additional> <ListOfUIPVariants> <UIPVariant> <Variant>rIDVariant1</Variant> <Version>01.00.00</Version> <PlatformId>Workstation</PlatformId> <RuntimeId>String</RuntimeId> <StartElementName>Variant1.assembly</StartElementName> </UIPVariant> <UIPVariant> <Variant>rIDVariant2</Variant> <Version>01.00.00</Version> <PlatformId>Mobile</PlatformId> <RuntimeId>String</RuntimeId> <StartElementName>Variant2.assembly</StartElementName> </UIPVariant> </ListOfUIPVariants> </fdi:UipCatalog> The UIP Catalog will have a corresponding relationship part. In this example, the part is /uip/_rels/uipcatalog.xml.rels. An example for /uip/_rels/uipcatalog.xml.rels is listed below. <?xml version="1.0" encoding="UTF-8"?> Field Device Integration (FDI) – Part 4: FDI Packages RELEASED FCG TS62769-4, Ed. 1.2.0, 21 Jun 2019 Page 48 of 79 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"> <Relationship Type="http://fdi-cooperation.com/2010/relationships/uip-variant" Target="variant1.zip" Id="rIdVariant1"/> <Relationship Type="http://fdi-cooperation.com/2010/relationships/uip-variant" Target="variant2.zip" Id="rIdVariant2"/> </Relationships> In this example, the UIP Variants are stored in the /uip directory. It is possible that these could be stored in a different location. The target of the relationship would be updated to properly identify the UIP Variant. D.4.3 EDD reference to UIP The following EDD fragment can be used to identify the UIP in this example. The following code includes only the necessary attributes to establish the relationship. Other mandatory attributes have been removed for clarity. MENU mymenu { ITEMS { pFrancyTrend } } PLUGIN pFrancyTrend { UUID f67e4ad0-5de5-11df-a08a-0800200c9a66; } D.4.4 FDI Registration Certificate The example shows an FDI Device Package that describes device model 1234. The first registration was issued by FDI Registration Corp., Singapore in December 2010. A second registration was issued by FDI Registration Corp., Köln in March 2011. <?xml version="1.0" encoding="UTF-8"?> <fdi:FdiRegistrationCert xmlns:fdi=http://fdi-cooperation.com/2010/package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://fdi-cooperation.com/2010/package catalog.xsd"> <PackageId>ef377fd0-5de5-11df-a08a-0800200c9a66</PackageId> <Version>1.3.4</Version> <ListOfRegDeviceTypes> <RegDeviceType> <Manufacturer>00ff00</Manufacturer> <DeviceModel>1234</DeviceModel> <ListOfRegistrations> <Registration> <RegistrationDate>2010-12-31</RegistrationDate> <RegAuthorityIdent>FDI Registration Corp., Singapore</RegAuthorityIdent> <RegistrationData> <value>Test Tool Version 2.1, Conformance Test<value> <value xml:lang="de">Test Tool Version 2.1, Conformance Test</value> </RegistrationData> </Registration> <Registration> <RegistrationDate>2011-03-07</RegistrationDate> Next >