BACnet Fire 3rd Party EDE File Formats

To integrate BACnet Fire 3rd 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 step 5 – (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 step 1 – 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 step 1 – 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"

Family1)

Family name.

Optional.

1)

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.

 

NOTICE
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

 

NOTICE

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.