3rd Party BACnet Reference

This section provides background information on integrating BACnet project data into Desigo CC . Integration permits the user to access objects from corresponding third party BACnet devices and monitor or edit them in the management platform. For related procedures, see the step-by-step section.

 

NOTICE
Safety functions

Observe all applicable standards for the country as well as regional or local regulations when integrating safety functions.

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.

Management View after 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.

Hierarchy View in System Browser

Logical View

Configuration of the Logical View

Hierarchy View in System Browser

User View

Configuration of the User View

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:

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.

Object Types in the Library BA_Device_BACnet_HQ_1

Short Name

English

German

ACC

Accumulator

Counter input

AE

Alert Enrollment

Alert Enrollment

AI

Analog Input

Analogeingabe

AO

Analog Output

Analogausgabe

AV

Analog Value

Analogwert

AVG

Average

Mittelwert

BI

Binary Input

Binäreingabe

BO

Binary Output

Binärausgabe

BSV

BitString Value

Bitfolge

BV

Binary Value

Binärwert

CAL

Calendar

Kalender

CMD

Command

Befehl

CSV

Characterstring Value

Zeichenfolge

DEV

Device

Gerät

DPV

Date Pattern Value

Datumsschema

DTPV

Date Time Pattern Value

Datum/Zeit-Schema

DTV

Date Time Value

Datum/Uhrzeit

DV

Date Value

Datum

EE

Event Enrollment

Ereignisregistrierung

ELOG

Event Log

Alarmaufzeichnung

FIL

File

Datei

GGRP

Global Group

Globale Gruppeneingabe

GRP

Group

Gruppe

IV

Integer Value

Ganzzahlwert

LAV

Large Analog Value

Analogwert mit doppelter Genauigkeit

LSP

Life Safety Point

Gefahrenmelder

LSZ

Life Safety Zone

Sicherheitsbereich

LC

Load Control

Laststeuerung

LP

Loop

Regler

MI

Multistate Input

Mehrstufige Eingabe

MO

Multistate Output

Mehrstufige Ausgabe

MV

Multistate Value

Mehrstufiger Wert

NC

Notification Class

Meldungsklasse

NF

Notification Forwarder

Notification Forwarder

NS

Network Security

Netzwerksicherheit

OSV

OctetString Value

8-Bit-Zeichenfolge

PR

Program

Programm

PC

Pulse Converter

Pulszähler

PIV

Positive Integer Value

Positiver Ganzzahlwert

SCHED

Schedule

Zeitplan

SV

Structured View

Strukturierte Ansicht

TLOG

Trend Log

Trendlog

TLOGM

Trend Log Multiple

Mehrfaches Trendlog

TPV

Time Pattern Value

Zeitschema

TV

Time Value

Uhrzeit

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.

Workflow Importing Data
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.

Subsystem or Interfaces Used

Name

Import with

Comments

SX Open

Standard EDE

Edit the EDE file

Integration of Simatic S7 Solutions

Topology Simatic S7

Simatic S7 Integrations

Integration of

Required EMs

Import with

File format

Comments

Siclimat X

Siclimat

Siclimat Importer

XML

See Siclimat X information

Simatic S7 Scada

Simatic_S7

S7 Importer

CSV

See Simatic S7 information

Simatic HVAC Building Solution

Siclimat

Simatic_S7

Desigo_PX

Siclimat Importer

XML

Use the Desigo PX documentation

Desigo S7 Integration Solution

BACnet_EDE

Standard EDE Workflow

EDE

Edit the EDE file

Desigo S7 Building Solution

BACnet_EDE

Desigo_System

Desigo_PX

Standard EDE Workflow

EDE

Check the EDE file

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.

View in System Browser

Without editing of the EDE file

With editing of the EDE file

  • The following description refers to the table view in the System Browser.
  • The Hierarchy-User.txt (optional) and Hierarchy-Logical.txt (required) files cannot be selected. The files are unavailable, so that no or only the defined view is created.
  1. Open the EDE file using an editor.
  1. Add an empty line before each Meters.
  1. In the keyname column, enter a name and shorten this text by one level.
    − Original text (blue arrow): PiiGAB'CTS02'Meters'A17EL01'DR2Value
    − Added text (red arrow): PiiGAB'CTS02'Meters'A17EL01
  1. In the Object name column, enter a name and shorten this text by one level.
    − Original text (blue arrow): PiiGAB'CTS02'Meters'A17EL01'DR2Value
    − Added text (red arrow): PiiGAB'CTS02'Meters'A17EL01
  1. In the description column, enter a description, for example: A17EL01.
  1. Entries cannot be made on added lines in the following columns:
    device-object-instance
    object-type
    object-instance
  1. Save the EDE file.
  1. Import the file and check the changes.
EDE File after Processing
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.

Additional Columns for Desigo PX objects

Column name

Information

Example PID Controller

Object-profile-number

Required

12

Object-profile-name

Optional

PID Controller

User Designation

Optional

 

Function-name

Required

PIDCtr

Function-name-reference

Optional

TxG25059Tx1

Short-name

Required

PCtr

Short-name-reference

Optional

TxG26005Tx7

Element-type

Optional

4

Main-parameter

Optional

 

Resolution

Optional

 

Device-name

Optional

AS01

 

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.

Naming Conventions for EDE 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

 

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

Naming Conventions for EDE Columns

Keyword

Specified by EDE Template

keyname

keyname

Device

device-object-instance

object-name

object-name

object-type

object-type

object-instance

object-instance

description

description

Default

present-value-default

Min.

min-present-value

max

max-present-value

hi

hi-limit

low

low-limit

state

state text reference

unit-code

unit-code

unit-text

Siemens-specific

Vendor

vendor-specific address

Function

Siemens-specific

Resolution

Siemens-specific

EoType

(Optional) Eo type mapping (Used only together with the family attribute.) Each line must be assigned an Eo type.

 

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.

Mapping in System

Column

Use

keyname

Is needed to map the hierarchy.

device-object-instance

Unique device ID in the BACnet network.

object-name

Unique name within the device.

object-type

Defines the object type to determine the corresponding object model.

object-instance

Instance number for the same object type.

description

Description of the data point text in the views for import:

  • Management View
  • Logical View
  • User-Defined View

present-value-default

Is not evaluated by the system.

min-present-value

Under the condition that changes of values that are less than the defined value are not executed.

max-present-value

Under the condition that changes of values that are greater than the defined value are not executed.

hi-limit

Is not evaluated by the system.

low-limit

Is not evaluated by the system.

state text reference

Display state value for binary or multistate data points.

unit-code

Reference number for the unit text column.

unit-text

Unit applied to analog values.

vendor-specific address

Vendor's ID.

Function

Reference to the applied Function. A corresponding Function and a Function key must be defined.

Resolution

Resolution value for a data point.

 

Mapping in 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

Overview EDE Files

Functionality of Delimiters

 

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

The file separator is dependent on the regional settings in Windows when using Excel: Control Panel > Clock, Language, 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).

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 delimiter for the corresponding line.

4

Hierarchy

The hierarchy delimiter can differ for each hierarchy or is always the same. The hierarchy delimiter 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

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 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:

Files Hierarchy-Logical-Map.csv and Hierarchy-User-Map.csv

Without translation

With translation

 

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.

Reference Column for Hierarchy Mapping

View in System Browser

File Name

Default
Column name

Alternative
Column name

User-Defined View

Hierarchy-User.txt

keyname

Vendor-specific-address

object-name

Logical View

Hierarchy-Logical.txt

object-name

keyname

 

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.

Example User Designation 5600:G01'F07W_VP10_TSA09

Definition

Partial designation

Description

,:,4,4,Location

5600

Locality (as zip code)

,',1,5,Building

G01

Building 1

,_,1,5,Floor

F07W

Floor 7 / West wing

,_,1,10,Plant

VP10

Ventilation plant 10

,_,1,20,Object

TSA09

Supply air temperature

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.

Example User Designation 5600G01S07WLA10TZU09

Definition

Partial designation

Description

,,4,4,Location

5600

Locality (as zip code)

,,3,3,Building

G01

Building 1

,,4,4,Floor

F07W

Floor 7 / West wing

,,4,4,Plant

VP10

Ventilation plant 10

,,5,5,Object

TSA09

Supply air temperature

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.

XLSX EDE file

Definition of Tab Names

Tab Names

Contents

EDE

Data point information

State texts

State texts

Unit texts

Units

Object types

Is not evaluated

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 with Reference Files

CSV without Reference Files

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

CSV without Reference File

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

Mapping the Text Group

 

Prefix

Name

Suffix

System Browser

File Name

 

Cosmos Open

 

 

Text group 1

EdeStateTexts

_Cosmos_Open

_0

EdeStateTexts_Cosmos_Open_0

Text group 2

EdeStateTexts

_Cosmos_Open

_1

EdeStateTexts_Cosmos_Open_1

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.