====== BACnet Server ======

A BACnet server provides data over BACnet / UDP to clients, such as supervisory workstations (SCADA). Mervis Runtime variables are mapped to standard BACnet objects either in Mervis variables properties, or by populating the BACnet object table in a BACnet device. These objects are available in a BACnet server which is running in a PLC. BACnet clients can read these objects and their properties, and write to writable objects.

===== Platforms and object types =====

Supported hardware platforms are as follows:\\
mark220\\
mark320\\
markMX\\
IMIO105\\
IMIO110\\
ICIO205\\
mark125\\
Windows RT\\
wall - all types

Other hardware platforms do not support BACnet because of performance reasons.

Following BACnet object types are supported:

  * Analog Input - reading
  * Analog Value - reading, writing
  * Analog Output - reading, writing
  * Multistate Input - reading
  * Multistate Value - reading, writing
  * Multistate Output - reading, writing
  * Binary Input - reading
  * Binary Value - reading, writing
  * Binary Output - reading, writing
  * Schedule (bool, multistate, real) - reading, writing

See details including supported object properties in the [[en:mervis-ide:35-help:015-plc:115-bacnet_pics|PICS]].

===== Creating a channel =====

If a PLC shall work as a BACnet server, a server communication channel must be defined. Right click the PLC and select Add server channel. (This is where the Device object is inserted.)

In Channel properties select Protocol: BACnet Server. Link protocol is UDP. (Communication BACnet / MS/TP - over serial line RS485 - is not supported in this version, use a BACnet router if necessary.)

A Device is a basic (mandatory) object, which contains definition of all other objects for a BACnet network. A Device keeps its list (after successfull configuration and project execution visible e.g. in Yabe - Yet Another BACnet Explorer, available at https://sourceforge.net/projects/yetanotherbacnetexplorer/):

{{:en:mervis-ide:35-help:bacnet_yabeobjectlist.png|BACnet object list v Yabe}}

As a "container" for BACnet objects there must be a Device Object defined, let us then define this object first:

In the channel context menu, select Add server device. 

The PLC name (here "PLCbtest") is copied into BACnet properties of the Device object: Object Name and Description.

{{:en:mervis-ide:35-help:bacnet_device.png|BACnet device}}

  * **Name** - just for information, not used anywhere else.
  * **Enable** - to have the communication working, a device must be enabled.
  * **Device Instance** - must be unique in a BACnet network for the Device object identifier to be unique.
  * **Management password** - a BACnet device can be managed remotely, e.g. restarted. Access for device management should be protected by a password, which is entered here.
  * **Network Address Type** - in this version, only BACnet / UDP is supported, enter None here.
  * **Device IP Address** - enter 127.0.0.1, not used here.
  * **Device Port** - the standard UDP port number for BACnet is 47808 (which is BAC0 in hex notation, and easier to remember), it is advised to keep this number for compatibility with some 3rd party devices that require this port number.
  * **Local Port** - enter 47808, not used here.

Now the BACnet objects with values mapped to Mervis variables can be defined.

===== Defining objects with values =====

Double click a Device to open a table with mapping of Mervis variables to BACnet objects. 

The table can be populated in two ways:

==== 1. Directly in the Variable browser ====

BACnet properties are defined at the same time the application is engineered. They are part of variable metadata. The BACnet object table in the Device is generated automatically at the compilation time, and needs not to be defined manually later.

  * Focus the variable to be available over BACnet
  * Set the BACnet Visible parameter at the respective PLC to True and confirm
  * BACnet device is selected automatically
  * The BACnet object type is suggested automatically (here Analog Value). If the type should be changed, select of the available types in the drop-down box. For example, a AI... is a typical Analog Input, because it is read-only (an Analog Value may be written over BACnet, which makes no sense at an I/O module input).
  * If a physical unit is entered (Variable metadata - Unit), such as "°C", it will be translated into the BACnet property Units with the corresponding code.

{{:en:mervis-ide:35-help:bacnet_variable.png|BACnet variables}}

  * **Data Point Name** - this text appears in the BACnet properties Object Name and Description
  * **Data Point Type** - automatically suggested value, can be changed by selecting from predefined (relevant) object types
  * **Alarm Point** - see below
  * **[PLC_name]:BACnet visible** - proměnná se mapuje na objekt BACnet do vybraného Device
  * **[PLC_name]:BACnet device** - BACnet Device in which this variable is mapped (usually there in only a single BACnet device per PLC, then the variable is mapped to this Device automatically)
  * (Variable Metadata)
    * **Unit** - text string with physical unit name (e.g. °C) which Mervis IDE attempts to translate into standard BACnet physical unit code (e.g. 62 DEGREES-CELSIUS) and uses this in the BACnet object table.
    * 
The items above can also be edited for more variables together, just select more variables (Ctrl+ left click or Shift + down arrow) and edit the item concerned.

At the next compilation, BACnet object identifiers are generated (BACnet Object IDs) and the table in a Device is completed.

==== 2. Manual editing of the object table in a BACnet Device ====

  * Click a BACnet device
  * Right click the table, select Add Variable
  * Select a variable to be mapped on a new BACnet object. Multiple variables may be selected (Ctrl+ left click or Shift + down arrow).
  * If necessary, change the Object Type in the Properties.
  * At Binary objects, Polarity can be changed (when Reverse, the Active text is in False)

The added objects will appear in the table, with Object Instance and Object ID blank. (The Object ID is a bit composition of Object Instance and standard object type code.)

{{:en:mervis-ide:35-help:bacnet_manually.png|BACnet variables added manually}}

The objects are automatically numbered at the next compilation. This numbering cannot be edited. 

A variable can only be mapped to one BACnet object in the table. It is not possible to define more BACnet objects linked to a single variable. If the table already contains an object linked to a particular variable, this variable is not in the selection of available objects in the mapping dialogue for a new object.

===== BACnet properties and their relations to variable metadata  =====

Each BACnet object type contains a set of required and optional propertiers, according to the BACnet standard. Some of them are to be entered manually, others are copied from the Mervis variables metadata. 

As an example, an Analog Value object has following properties (ASHRAE BACnet Standard, 1995):

{{:en:mervis-ide:35-help:bacnet_avproperties.png|AV properties}}

Required properties are marked as R(equired) in the third column. W stands for Writable. O means Optional, a property which may be present or not, depending on the server implementation.

  * **Object Identifier**: generated automatically as a combination of object type (here Analog Value) and object instance (number 0 to 4194302). See also BACnet standard.
  * **Object Name**: taken from Mervis Object name (editable).
  * **Object Type**: Defined by automatic assignment or manual object type selection in the Mervis property Data point type.
  * **Present Value**: Value of the variable, the main property which is of interest.
  * **Status Flags**: from the flags In Alarm, Fault, Overridden, Out of service only two flags are supported: InAlarm, which is active if an alarm point is linked to the object and the alarm point is in a state different from Normal, and Overridden, which is active if the mapped variable in in manual mode.
  * **Event State**: If an alarm point is linked to the object, then as soon as the alarm point is in a state different from Normal, this property goes to Offnormal. Otherwise it goes to Normal.
  * **Out Of Service**: In this version this property is permanently False.
  * **Units**: If a Mervis variable has a physical unit entered in its metadata, e.g. °C, Mervis IDE attempts to translate this string to a standard BACnet unit code, such as 62 DEGREES-CELSIUS.
  * **High Limit**: at settable values this is the recommended high limit, it is advised to limit a setter to this upper value.
  * **Low Limit**: at settable values this is the recommended low limit, it is advised to limit a setter to this lower value.

===== Notification classes =====

Notification classes are objects which define rules how to send event notifications. If any of the objects shows a change of value or event which has to be communicated to the other network participants, a notification is sent. Each message has a defined priority which specifies how the information has to be processed. The priorities are numbered from 0 (highest, for critical events) to 255 (lowest, for the most unimportant events).

A notification class may be assigned to an object (such as to Analog Input) not before the object has an alarm point connected. As soon as the alarm point changes its state from Normal or goes to another state later, a notification is sent to the BACnet network. The notification priority is defined in the notification class. This means that every object with an alarm point attached must have a notification class assigned, otherwise the Mervis project can not be compiled. On inserting a BACnet server, a notification class named "Class_1" is created automatically, and all objects with attached alarm points are assigned this default notification class automatically.

==== Inserting a notification class ====

  * Right click the notification class table and select Add Notification Class.
  * Confirm by clicking OK.
  * In the Notification Class Properties, enter the notification class name (Object name) and priorities for different event types.
  * The defined notification class can be used in the BACnet object table.

{{:en:mervis-ide:35-help:bacnet_notificationclass.png|Notification classes}}

If you are not sure or do not want to use priorities, use the predefined notification class only.

===== Export to EDE files =====

The EDE (Engineering Data Exchange) files are text files in CSV format. They describe the BACnet objects and their properties in a BACnet device. They enable a standardized offline data transfer between different systems, especially for importing of objects in a BACnet client (SCADA). If a BACnet server supplier provides these files, the engineer who configures the BACnet client does not have to enter the objects and their properties manually. They can be imported from the EDE files.

The EDE files should be exported not before the BACnet objects table in a device has been completed. The object IDs may be renumbered on adding and deleting of BACnet objects. 

  * Right click the BACnet channel

{{:en:mervis-ide:35-help:bacnet_edeexport.png|EDE export}}

  * Select Export EDE file\\
  * In the Results field, a message about successful export is displayed. The files are exported to the project folder, into a newly created folder named BACnet-export.

{{:en:mervis-ide:35-help:bacnet_edeexportfiles.png|EDE export soubory}}

The product of the export are four files. The file names consist of project name, project GUID, and standard part of the file name.\\

<code>
...EDE: the main file with list of objects and their properties, e.g.

#Engineering-Data-Exchange;;;;;;;;;
PROJECT_NAME;"<undefined>";;;;;;;;
VERSION_OF_REFERENCEFILE;1;;;;;;;;
TIMESTAMP_OF_LAST_CHANGE;13.08.19;;;;;;;;
AUTHOR_OF_LAST_CHANGE;HONZA-PC - Jan;;;;;;;;
VERSION_OF_LAYOUT;2;;;;;;;;
#mandatory;mandatory;mandatory;mandatory;mandatory;mandatory;optional;optional;optional;
# keyname;device obj.-instance;object-name;object-type;object-instance;unit-code;hi-limit;low-limit;state-text-reference;
"prom1";1;"prom1";0;1;62;200;0;;
"prom2";1;"prom2";1;1;47;100;0;;
"prom3";1;"prom3";2;1;16;362;80;;
"prom5";1;"prom5";4;1;95;;;;
"prom6";1;"prom6";3;1;95;;;;
"main.T17_Boolean_Scheduler";1;"T17_Boolean_Scheduler";17;4;95;;;;
"main.T18_Real_Scheduler";1;"T18_Real_Scheduler";17;2;95;;;;
"main.T19_Int_Scheduler";1;"T19_Int_Scheduler";17;3;95;;;;
"prom4";1;"prom4";5;1;95;;;;
"prom6_out";1;"prom";5;4;95;;;;
"prom01";1;"prom01";14;1;95;;;1;
"prom02";1;"prom02";19;1;95;;;1;
"prom";1;"prom";13;1;95;;;1;
"prom1_out";1;"prom1_out";2;3;95;100;0;;
"hw.IMIO10x_DO2";1;"IMIO10x_DO2";3;2;95;;;;
"hw.IMIO10x_AI1";1;"IMIO10x_AI1";2;5;95;100;0;;

...ObjTypes:used object types with numeric coding according to the BACnet standard, e.g.

#Encoding of BACnet Object Types;;;
#Code;Object Type;;
"0";"AnalogInput";;
"1";"AnalogOutput";;
"2";"AnalogValue";;
"3";"BinaryInput";;
"4";"BinaryOutput";;
"5";"BinaryValue";;
"13";"MultistateInput";;
"14";"MultistateOutput";;
"17";"Schedule";;
"19";"MultistateValue";;

...StateTexts: list of states for Multistate objects, such as:

#State Text Reference;;;;;;
#Reference Number;0;1;2;3;4;
1;Normal;Active;ActiveAcked;AckedMemory;Memory;

...Units: used physical units with numeric coding according to the BACnet standard, e.g..

# Unit Texts Reference;
"16";"JOULES"
"47";"WATTS"
"62";"DEGREES-CELSIUS"
"95";"NO-UNITS"
</code>

Some software packages may require a slightly different file format (different positions of spaces, "#" characters, etc.). In case of incompatibilities please contact the Domat Control System technical support. The EDE files export in Mervis IDE was tested with major SCADA packages and keeps all known standards.

===== Testing knowledge =====

To set exceptions in program in Desigo Insight only the time program can be used T19 Int. The T17 Bool and T18 Real time programs do not allow writing exceptions.