3rd Party BACnet Reference

Engineering

Third party BACnet devices can be integrated in the management platform Online or Offline depending on the application or availability of project data. The selected import to the management platform also impacts how project data is depicted in System Browser.

Online Import

For online engineering, you must connect to the third party BACnet device online in order to import project data in the management platform.

Advantage

• You import the latest project data from the third-party BACnet device.
• Extensive coordination with the third-party BACnet device project engineer is not required.
  NOTE: The following information must, however, be clarified in advance: PICS, device ID, device name, UDP port.

Disadvantage

• Scanning the network can take quite a long time.
• The hierarchy structure for viewing in System Browser cannot be influenced if the texts are unstructured.

Offline Import

You need an Engineering Data Exchange (EDE) file for the offline import of third-party BACnet devices in the management platform. An online connection with the BACnet device is not required.

Advantage

• Engineering can take place in the office.
• Multilanguage is supported.
• The following views are supported in System Browser:
• Management View (generated automatically by the system cannot be influenced).
• Logical View (controlled via the Configuration file)
• User View (only if already created in the engineering tool and it is then controllable via the Configuration file)
• Graphic engineering can be completed in advance at the office.

Disadvantage

• Project data from the third-party BACnet device may not be up-to-date.
• Requires more coordination to receive the EDE data from the third-party BACnet device project engineer.

Views in the System

The data points are displayed in various views, depending on the import type. The Management View is generated on all import types.

Online

The list of imported data points can be displayed alphabetically after an online import.

Offline

In addition to Management View, that is identical offline to the Online variant, the Logical View and the User View can also be generated offline using Configuration files.

PICS

The Protocol Implementation Conformance Statement (PICS) document lists all devices of the manufacturer and describes the supported BIBBs, object types, characters sets, and options of communication. PICS of the respective manufacturers are listed under:

• http://www.bacnetinternational.net/btl/
• http://www.bacnet.org
• http://www.big-eu.org

The following PICS are available for vendors’s devices:

• BACnet Advanced Operator Workstation (B-AWS)
• BACnet Building Controller (B-BC)
• BACnet Advanced Application Controller (B-AAC)
• BACnet Application Specific Controller (B-ASC)
• Other BACnet Devices (B-Oth)

Supported Object Types

Functions AutoDiscovery or EDE Import support only standard BACnet objects, i.e. BACnet extensions made by the manufacturer are not supported by these Desigo CC functions. The current version supports the defined BACnet objects in the following library: Project > System settings > Libraries > BA (HQ) > Devices > BACnet > Object models.

Workflow Importing Data

A BACnet driver and a network must be created or exist in advance for online or offline import.

NOTE:
Select the same type of import for each manufacturer and network to avoid potential data loss.

Concept EDE File

BACnet ensures interoperability among devices from various manufacturers. The EDE file documents BACnet project data of a device and integrates it in Desigo CC.

Project data

EDE data is designed as follows to exchange project data:

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

Available optional information is taken over as an object instance in the project database. In the event that no optional information exists in the EDE file, the missing information is derived from the Function or the Object Model.

Object information

Two data formats (CSV and XLSX) are available for data import to prepare object information. In addition, the file format may differ for CSV.

CSV file format

• Information is located in various CSV files:
• Object description
• Object type
• Unit
• State text
• All information is available in a CSV file (object description, object type, unit, state text). The individual information is defined in the corresponding column.

XLSX file format

• All information is available in a XLSX file (object description, object type, unit, state text). The individual information is defined under its own tab.

The Desigo CC import function supports these three data forms. An error message is displayed if the data format does not meet the requirements.

NOTE:
By default, the object type is taken over from the associated Object Model for the BA_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.

Hierarchy Mapping in System Browser

Multiple views of an object are possible in System Browser depending on the integrated field networks:

• Project data is only displayed in Management View without additional configuration. The information from the Object Name column is taken to create the objects in the Management View.
• The Logical and User Views can be controlled using a configuration file (Hierarchy-Logical.txt or Hierarchy-User.txt). The company executing the project must comply with project specifications to properly map the hierarchy in Desigo CC. This is the only way to hierarchically import the object information using separators and to display it in System Browser.

Field Network-Specific Special Cases

Behavior (creating objects or views) during import may differ from the standard EDE file depending on the field network used. The requirement for integration is that the extension module Desigo_System and the corresponding field network extensions are available in the project.

Integration of Simatic S7 Solutions

Adding Object for Hierarchy Mapping

For field networks that do not know objects for mapping hierarchies, all objects with the same descriptive text, for example Meters, are displayed one below the other which makes it difficult to select a particular object.

To render selection more user friendly, the EDE file must be extended by an additional entry for each object. It is this object that carries the corresponding description.

NOTICE

Prevent Data Loss

Any changes made to previous versions are overwritten once a newly generated EDE file is imported.

Back up the edited EDE file and compare the changes to the new EDE file. Edit one or both of the EDE files and import the revised EDE file.

Alternatively, use the SX Open tool to make the relevant changes to the EDE file.

Creating Desigo PX Objects

An EDE file can be extended to include additional column information. This creates a Desigo PX BACnet object, if extensions are available, rather than a standard BACnet object. It is thus 100% compatible with Desigo PX.

NOTICE

The display in System Browser is incorrect
The columns Function name and Short name are required for the program to be able to switch to the S7 mode The information in the columns depends on the function but the columns can also be empty.

− A Logical View, but no User View, is created if there are no Hierarchy-User.txt and Hierarchy-Logical.txt files. The Logical View is then derived from the object name (Delimiter = ' ; min = 1; max = 50) and hard-coded.

Naming Conventions

File Names

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

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).

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

Mapping in System

Indicates where the information is displayed in the system.

Format of Configuration Files

Terms

• 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
  Defines the applicable hierarchy level when importing the object.

Delimiters in the files

General

A text editor can be used to create the Hierarchy-User.txt and Hierarchy-Logical.txt files. The file format for the Hierarchy-User.txt and Hierarchy-Logical.txt files is divided into two parts:

• Design of EDE file
• Design of Hierarchy mapping

File format

!encoding!utf-8

#separators-1#;

#separators-2#,;

#separators-3#|

:column-name:keyname

,_,1,15,Location|Location|Standort

,:,1,15,Building|Bâtiment|Gebäude

,_,1,15,Floor|Plancher|Stockwerk

,_,1,20,Plant|Installation|Anlage

,_,1,20,Object|Objet|Objekt

,_,1,25,Data point|Point|Datenpunkt

NOTE:
Any character may be used as the definition separator but it must not occur in the corresponding line.

Partial Definition for EDE File

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

• Encoding (Optional): Must be used, if imported characters are no displayed correctly
• Separators-1 (Optional): Default = ";")
• Separators- 2 (Optional): Default = ";,")
• Separators- 3 (Optional): Default = "|") Use only in the event of multiple languages
• Column-name (Optional): Default (logical) = „object-name“, Default (user) = "keyname"
• Family (Optional): Default = "BACNET”

Syntax for the EDE Component

!encoding!utf-8

#separators-1#;

#separators-2#,;

#separators-3#|

:column-name:keyname

Use the Family Attribute

The Family attribute may be used to choose other Object Models than the ones from the standard BACnet library (Family = BACNET). Mapping of the BACnet types to EO-Type is hard coded by default. This means that the Family attribute can only be used for libraries which are 100% BACnet compliant, (for example Object-Type ‘0’ EO_BA_AI_1, ‘1’ EO_BA_AO_1, …).

If this is not the case, the EDE files must be expanded by a new column (with the name EoType to indicate the Eo-Type for each object

Example of use of EO type:

Example of use of Family attribute:

!encoding!utf-8

#separators-1#;

#separators-2#,;

#separators-3#|

:column-name:keyname

;Family;System_name

+EOType-Aggregator+EO_System_name_AGG_1

?EOType-Folder?EO_System_name_FDR_1

The hierarchical object model aggregators and subsystem folders must be defined to use the flexible import rule Family. The aggregator and folder are added to the hierarchy structure as needed during the import of the EDE file.

Multilingual support

The following must be fulfilled for multilingual support.

• A unique separator must be defined for #separators-3#| in files Hierarchy-User.txt and Hierarchy-Logical.txt.
• The sequence of the language entries in the EDE files is defined as per the sequence on the System Management Console.
• The texts are available in the description column of the EDE file and separated by separator 3.
  
• When using a state text file, the texts are available in the desired languages and separated by separator 3.
  
• The desired languages are available and separated by separator 3 in files Hierarchy-Logical-Map.csv and Hierarchy-User-Map.csv. A second data import is required to write the texts to the project data base.
  

Type and source of hazard

Is only the national language (for example, de-DE) use on a project, the first language must be defined as en-US and separated by separator-3.
Example en-US and de-DE:

Example for en-US only:

Encoding

Encoding permits clear assignment of characters (alphanumeric) and symbols within a character set. The characters are partially displayed incorrectly in the system if encoding is false. This generally 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.

Troubleshooting version 1

On the first row, define the code-page information that was created with the EDE file. If the code page information is unknown, try entry encoding=UTF-8.

The explicit entry for the correct encoding normally supplies the correct results. The advantages of this variant:

‒ No further settings are required if a supplier provides a new EDE file.

‒ The encoding only needs to be defined one time in the configuration file when importing multiple EDE files.

Encoding can be indicated both as text as well as numerically: For example 1252 or Windows-1252.

Troubleshooting version 2

Open the EDE file using a normal editor (the editor must correctly display all characters) and save the file with the setting Encoding = UTF-8. The disadvantages of this variant:

‒ Any new EDE file supplied by the supplier must be re-saved with UTF-8.

‒ Each EDE file must be saved in this manner.

• 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.

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.

Separators-2

The file separator (separators-2) is needed for:

• In the EDE main file, to recognize 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 (;).

Separators-3

The file separator (separators-3) is needed for:

• To support multiple languages.

Column Name

Column name is used to establish the reference column to create the object hierarchy.

Partial Definition for Hierarchy Mapping

Five properties must be defined for hierarchy mapping in System Browser:

• Definition delimiter
• Hierarchy delimiter
• Minimum user designation length
• Maximum user designation length
• Description of hierarchy levels

Syntax for Hierarchy Elements

,_,1,15,Location

,:,1,15,Building

,',1,15,Floor

,-,1,20,Plant

,_,1,20,Object

,+,1,25,Data point

Definition delimiter

The first character of each individual line is the definition separator. It may be a special character, letter, or number. The definition separator must, however, differ from the defined hierarchy delimiter for the corresponding line.

Hierarchy delimiter

The hierarchy delimiter defines the location in the text where a new hierarchy level is created (AAA_BBB:CCC'DDD-EEE_FFF+GGG).

A defined delimiter that is also used in the object text as a character can result in an incorrect hierarchy level.

Minimum User Designation Length

Defines the minimum text length (1-255) of the corresponding hierarchy level. A warning is displayed if the designation is shorter than defined.

Maximum User Designation Length

Defines the maximum text length (1-255) of the corresponding hierarchy level. A warning is displayed if the designation is longer than defined.

Description (Optional)

In System Browser, the descriptive text is displayed on the corresponding hierarchy level.

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 the same
• No hierarchy separators may be defined.

Overview EDE Files

The following examples display the supported file formats.

XLSX File

All information is saved in the XLSX file under the various tabs.

NOTE:
The file separators must be changed if the information in the XLSX EDE file displays everything in one column.

1. Select Start > Control Panel > Clock, Language, Region > Change the date, time, or number format.
2. Select Formats > Additional settings > List separators.
3. Enter the corresponding file separator.

CSV with Reference Files

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

CSV without Reference Files

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

Text Groups

State Text

One text group is created for each state text during an EDE file import. The text groups are saved in the Management View in System Browser under Project > System settings > Libraries > L4 project > Common > Common > Texts. The descriptive name of the text group is formed from EdeStateTexts+File name+Number. A file name with a space is supplemented with _ (underscore).

Use existing text groups for the state text

To avoid many new text groups, use the state-text-reference column to add the required text group. The functionality works for:

• _StateTexts.csv
• Tab StateTexts
• _StateTexts.csv as inline text defined

Syntax for a 3-stage fan:

• Add the comment *TxG*,TxG_BA_3147 if no limit is required or defined in the max-present-value column.
• Define the maximum stage of the fan *TxG*,TxG_BA_3147,4 for a 2-stage fan. This value is used if no value is defined in the max-present-value column.

Simple scenario:

• Debug mode

Scenario with max-present-value:

• Debug mode

Scenario without min-present-value and max-present-value, but with stage text:

• Debug mode

Additional information to the state text behavior:

• Default behavior (no min-present-value & no max-present-value & 2 texts (*TxG*,TxG_BA_1024)): Min and Max are set to «0» and «1» for binary, to «1» and «2» for multistate.
• min-present-value & max-present-value available: minimum and maximum values are available.
• No min-present-value & max-present-value available, but 3rd texts (*TxG*,TxG_BA_1024,4): Min is set to «1» and Max to the 3rd text (here 4) for multi-state (for binary, it remains at «0» and «1»).
• min-present-value set, for example, to value «3», but no max-present-value available for 3 texts (*TxG*,TxG_BA_1024,8): Min set to «3», Max to «8».

Units Text

An EdeUnitsTexts+File name text group is created to map units used.

Drop

The text groups are only deleted if referenced on a device. Multiple, referenced text groups must be manually deleted using the Text Group Editor.