BACnet Fire 3rd Party EDE File Formats

To integrate BACnet Fire 3^rd party devices into Desigo CC using the offline import you must edit and import the EDE (Engineering Data Exchange) file that defines the structure of the BACnet project data of a device.

Project Data

EDE data is designed as follows to exchange project data:

General project information
Required information for an individual object (column: Mandatory)
Optional information for an individual object (column: Optional)

All available optional information is replaced by an object instance in the project database. If no optional information exists in the EDE file, the missing information is taken from the Desigo CC function or object model.

EDE File Formats

The following table describes the formats of the file to edit and import object data supported by Desigo CC. An error message is displayed if the data format does not meet the requirements.

File Format

Data Format

CSV

EDE data can be presented in one of the following ways:

Separate for CSV files for each of the following:

Object description
Object type
Unit
State text

Single CSV file that includes object description, object type, unit, and state text), each in the corresponding column.

XLSX

EDE data is available in a single XLSX file that includes object description, object type, unit, and state text, each in its own tab. See Examples of EDE Files.

NOTE:
By default, the object type is taken over from the associated object model for the Fire_Device_BACnet_HQ_1 library (Family = BACNET). A different library may be referenced by using the Family attribute. The information from the EDE standard file is ignored during import.

Naming Conventions

The following naming conventions apply if object description, object type (not evaluated), unit, and state text are saved in separate CSV files.

Naming Conventions for the CSV Files
Variant 1	Variant 2	Variant 3
Example_EDE.csv	Example_EDE.csv	Example_EDE.csv
Example_ObjectTypes.csv	Example_Object-Types.csv	Example-object.csv
Example_StateTexts.csv	Example_State-Texts.csv	Example-states.csv
Example_Units.csv	Example_Unit-Texts.csv	Example-unit.csv

When you specify the name for the separate CSV files, you can follow one of the above variants for all the files or use different variants for the separate CSV files.
It is only recommended to construct the name as follows: [file name]_[variant file type].csv.

An error message is displayed if the file names for object type, unit, or state text cannot be determined.

Column Titles

Column titles may vary depending on the manufacturer. At a minimum, the keyword must be included in the column title for the import to be executed correctly (case-sensitive).

Keyword	Specified by EDE Template	System Mapping
keyname	keyname	Needed to map the hierarchy.
device	device-object-instance	Unique device ID in the BACnet network.
object-name	object-name	Unique name within the device.
object-type	object-type	Defines the object type to determine the corresponding object model.
object-instance	object-instance	Instance number for the same object type.
description	description	Description of the data point text in the views for import: Management View Logical view User view
default	present-value-default	Not evaluated by the system.
min	min-present-value	Provided that changes of values that are less than the defined value are not executed.
max	max-present-value	Provided that changes of values that are greater than the defined value are not executed.
hi	hi-limit	Not evaluated by the system.
low	low-limit	Not evaluated by the system.
state	state text reference	Display state value for binary or multistate data points.
unit-code	unit-code	Reference number for the unit text column.
unit-text	Siemens-specific	Unit applied to analog values.
vendor	vendor-specific-address	Vendor's ID.
function	Siemens-specific	Reference to the applied function. A corresponding function and a Function key must be defined. See (Optional) Define Function Keys in the Import Rules.
resolution	Siemens-specific	Resolution value for a data point.
EoType	-	The EoType mapping is mandatory and must be used in combination with the family attribute. Each row must have an EoType assigned.

A keyword used in multiple columns may result in an incorrect data import. Use the column titles according to the EDE specification where possible.

Format of the Configuration Files

Term			Description
File delimiters			Defines where a new entry (column information) starts in the main file (CSV). In the main file, defines the inline state texts (off, on), and in the supplemental files, where a new entry (column information) starts.
Definition delimiter			Defines the delimiter used to separate individual entries in the configuration file.
Hierarchy delimiter			Used during object import to define the applicable hierarchy level.
Delimiters in the Files

	Use	Description
1	Main file	The file separator semi-colon (;) is used as the default character in the main file. If another separator is required, you can change it in the configuration files (separators-1). See Create the Configuration Files. The file separator is dependent on the Windows regional settings when using Excel: Control Panel > Clock, Language and Region > Change the date, time, or number format > Additional settings > List separator.
2	Secondary file Inline texts in the main file	The file separators comma (,) or semi-colon (;) are used as default characters in the main file as inline text and in the secondary files. If another separator is required, you can change it in the configuration files (separators-2). See Create the Configuration Files.
3	Definition	In the configuration file, always the first character of each line (for example, #, space, letter). The definition separator must differ from the hierarchy separator for the corresponding line.
4	Hierarchy	The hierarchy separator can differ for each hierarchy or it can always be the same. The hierarchy separator used depends on the user structure.

Example: Hierarchy Separator in a Data Point
Delimiter	Data point
Different	AAAA_BBB:CC'DDD.EEE
Equal	AAAA_BBB_CC_DDD_EEE

Partial Definition of the EDE File

The following properties can be used to import an EDE file to Desigo CC:

Property	Description	Use
`encoding`	Encoding permits clear assignment of characters (alphanumeric) and symbols within a character set. This property must be used, if the imported characters are not displayed correctly. If encoding is false, the characters are partially displayed incorrectly in the system. Basically, this issue occurs if an EDE file is created on a computer in Western Europe and then imported to a computer used in Eastern Europe. Usually, this is not a problem if encoding UTF-8 (with BOM) is used when saving the EDE file. To troubleshoot this issue, do one of the following: On the first row, define the code-page information that was created with the EDE file. If the code-page information is unknown, try entering encoding=UTF-8. An explicit entry of the correct encoding generally provides the correct results. The benefits of this variant are: ‒ No additional settings are required if the supplier furnishes a new EDE file. ‒ If multiple EDE files are imported, the encoding only needs to be defined once in the configuration file. NOTE: Encoding can be indicated as both a text as well as a numerical value. For example, 1252 or Windows-1252. Open the EDE file with a text editor (the editor must correctly display all characters) and save the file with the setting Encoding = UTF-8. The disadvantages of this variant are: ‒ Any new EDE file furnished by the supplier must be resaved with UTF-8. ‒ Each EDE file must be saved in this way. General information on implementing the EDE function: Both hierarchy files are read with Encoding.Default. The other EDE text files are read using the indicated encoding. The default for the encoding property is Encoding.Default. Encoding.Default uses the code-page Information as set in the operating system unless a Byte Order Mark (BOM) exists. In this case, encoding is derived from BOM. When there is a BOM in a file the correct encoding is always used.	Optional
`separators-1`	Separators-1 is required to classify the columns of the EDE file. The property is optional and not required. The default value semi-colon (;) is used if no separator is defined.	Optional. Default = ";"
`separators-2`	The file separator (separators-2) is used: In the EDE main file, to determine the inline texts in a column. For example, Off, On, Stage 1, Stage 2. To classify the columns into state text and unit text files. The default separators are comma (,) and semi-colon (;).	Optional. Default = ";,"
`column-name`	Column name is used to provide the reference column to create the object hierarchy.	Optional. Default (Logical) = `"object-name",` Default (User) = `"keyname"`
`Family`¹⁾	Family name.	Optional.

¹⁾	For this integration the default is `“BACNET”`.

Reference Column for Hierarchy Mapping
View in System Browser	File Name	Default Column Name	Alternative Column Name
User View	Hierarchy-User.txt	keyname	Vendor-specific-address object-name
Logical View	Hierarchy-Logical.txt	object-name	keyname

Syntax for the EDE Component

!encoding!utf-8

#separators-1#;

#separators-2#,;

:column-name:keyname

Using the Family Property Extension

The Family property can be used to choose object models other than the ones from the standard BACnet library (Family = BACNET_Fire).

Example of using Family property:

!encoding!utf-8

#separators-1#;

#separators-2#,;

:column-name:keyname

;Family;System_name

The BACnet type to EO-Type mapping is hardcoded by default. Basically, this means that the Family attribute can only be used for libraries which are a 100% BACnet compliant.

Example:

Object-Type ‘0’ EO_FI_AI_1, ‘1’ EO_FI_AO_1, and so on.

If this is not the case, the EDE-file must be extended with a new column (with the name EoType) which specifies the EO-Type for each object individually.

When the flexible import rule Family is applied, the hierarchical object models aggregators and folders of the subsystem must be defined. If required, the aggregator and the folder are added to hierarchy structure during the import of the EDE file.

Partial Definition of the Hierarchy Mapping

The following properties must be defined for the hierarchy mapping in System Browser:

Property	Description
Definition Separator	This separator is the first character of each individual line and it can be a special character, letter, or number. NOTE: The definition separator must differ from the defined hierarchy separator for the corresponding line.
Hierarchy Separator	This separator defines the location in the text where a new hierarchy level is created (AAA_BBB:CCC'DDD-EEE_FFF+GGG). NOTE: A definition separator that is also used in the object text as a character can result in an incorrect hierarchy level.
Minimum user designation length	This value defines the minimum text length (1-255) of the corresponding hierarchy level. A warning message is displayed if the designation is shorter than defined.
Maximum user designation length	This value defines the maximum text length (1-255) of the corresponding hierarchy level. A warning message is displayed if the designation is longer than defined.
Description of hierarchy levels	This descriptive text corresponds with the description displayed for the corresponding hierarchy level in System Browser. This property is optional.

Special case: Fixed field length

For a user designation with a fixed field length, no hierarchy separators are available. In this case:
- The minimum and maximum field length must be defined as the same.
- No hierarchy separators can be defined.

Syntax of the Hierarchy Elements

,_,1,15,Location

,:,1,15,Building

,',1,15,Floor

,-,1,20,Plant

,_,1,20,Object

,+,1,25,Data point

Examples of EDE Files

The following are examples of the supported file formats.

XLSX File

All the information is saved in an XLSX file. Data is collected in the following Excel sheets:

Excel Sheet	Content
EDE	Data point information
State texts	State texts
Unit texts	Units
Object types	Is not populated

If all the information displays in one column in the XLSX EDE file, you must change the file separators as follows:
1. Select Start > Control Panel > Clock, Language, Region > Change the date, time, or number format.
2. Select Format > Additional settings > List separators.
3. Enter the corresponding file separators.

CSV with Reference Files

In the CSV file with reference files, the different types of information are saved in specific individual files.

CSV without Reference Files

All the information is saved in one CSV file without reference files.