Promotic

PmBACnet - Driver for communication by the BACnet protocol

This driver serves for communication with devices using the BACnet protocol. See Communication by the BACnet protocol.

Before using this driver in the PROMOTIC application it is highly recommended to watch "PROMOTIC video tutorial 4 - Communication drivers".

Basic properties of the driver:
- Usage of this driver requires purchase of the PmBACnet licence. When developing the application in the freeware mode PmFree, or with development environment and while testing it in runtime, this component is always functional.
- The communication is done for Ethernet (PROMOTIC application is client). The driver supports exclusively the BACnet/IP application layer with UDP transport layer.
- The driver is incorporated into the PROMOTIC system by means of the PmaComm object.
The driver supports usage of the PmaCommGroup object (for read and write of variables). The PmaCommMsg object is used only for special auxiliary message that detects the variables that can be read from the device (see further).
For easy integration of this driver into the application it is handy to use: Preconfigurations in group "BACnet"
- There is a slight deviation from standard, namely the fact that from the communicaton point of view the PROMOTIC application is always the client. The functions for searching devices and objects (Who-Is/I-Am) are not supported. The primary identification of target device is its IP address, not the device number (the driver does not use the device number for any purpose).
Note: Who-Is is used for sending a broadcast type request (request for all). The response that follow I-Am provide the information about the presence of the device together with device number, IP address, etc.
- The driver does not support segmentation and COV (Changing of Value).


The protocol is using objects:
The BACnet protocol belongs to the object oriented protocols group. The BACnet device object is defined by its type, its number and a set of properties.
Object type: for example analog input, binary output, etc. - see further.
Object number: is used for object identification (there can be multiple object of the same type or none). The numbers must be unique within the type, in the range of 0 to 4 194 302 and may not constitute a continuous series.
The "Device" type object represents special case that is always unique within the individual device. Its number is 4 194 303 (3FFFFF hexa). This number is therefore not entered in the driver.
Property: specifies additional information regarding the object, for example current value, unit, limits, etc. Some properties may be of the Array type.


Example 1: Some measured temperature is represented by object of the Analog Input type, and the number is for example 13 and the property set is for example:
"present-value"
"units"
"reliability"
"high-limit" etc.
Example 2: Each BACnet device is described by a single "Device" object, with properties for example:
"vendor-name" (name of the manufacturer)
"local-time" (time in the device)
"time-of-device-restart" (time last device restart) etc.


Object types:
Followed by the list of object types supported by the driver:
- Device: An object containing global device information. For example name and identifier of the manufacturer, etc.
- Analog Input: Analog value on the device input.
- Analog Output: Analog value on the device output.
- Analog Value: Analog value inside the device.
- Binary Input: Logical value on the device input.
- Binary Output: Logical value on the device output.
- Binary Value: Logical value inside the device.
- Multi-state Input: Multistate value on the device input.
- Multi-state Output: Multistate value on the device output.
- Multi-state Value: Multistate value inside the device.
- Averaging: Averaging.
- Accumulator: Container.
- PulseConverter: Pulse converter
- CharacterString Value: Text string.
- Schedule: Scheduler.
The "weekly-schedule" property is also supported in this object. This property can be read and written in the PROMOTIC system and is of the String data type. It is a text in the CSV format containing day (1=Monday - 7=Sunday), time and value. Note: For reading and writing into the file the methods Pm.FileCsvRead and Pm.FileCsvWrite can be used.
Property "exception-schedule" is not supperted by the driver so far.


Data types:
BACnet uses the following data types:
- boolean - In the PROMOTIC application represented by the Boolean data type.
- unsigned integer - In the PROMOTIC application represented by the Long data type.
- signed integer - In the PROMOTIC application represented by the Integer data type.
- real - In the PROMOTIC application represented by the Single data type.
- double - In the PROMOTIC application represented by the Double data type.
- character string - In the PROMOTIC application represented by the String data type.
- bit string - In the PROMOTIC application represented by the Long data type. So far it is limited to 32 bits with no way to find out which bits are valid. So far "read only" is supported (cannot write).
In some cases the bit strings are used as so-called BACnet Status Flags. In this case only the first 4 bits are used for following purpose:
- bit 0: in-alarm
- bit 1: fault
- bit 2: overriden (switched to manual control)
- bit 3: out-of-service
- enumerated - For the "units" property, it is transformed to String value carrying information regarding the physical units assigned by standard (this value can only by read, cannot write). Other values are transformed to Byte with the number of the value (these values can beread and written).
- date - In the PROMOTIC application represented by the Date data type.
- time - In the PROMOTIC application represented by the Date data type.


Saving into present-value property:
The present-value property forms the priority array priority-array with 16 priority values. While writing, it is possible to define the priority, i.e. the array index of the written value. If the written value is defined as Variant data type containing: null for JavaScript or Empty for VBScript, then the BACnet value NULL will be sent which means that the selected index value will be deleted.

Recommended values of the PmaComm object parameters:

Recommended values for the Ethernet-client parameters:
Network addressDevice IP address. Because the driver does not support device search so far, the IP address is used as a main device identifier instead of the device number.
TCP/UDP remote port number47808 (defined in the BACnet standard, the hexadecimal value is BAC0)
 
See: Wikipedia: A list of TCP and UDP port numbers used by protocols to run network applications.
TCP/UDP local port numberUsually you can set "Automatic".
For some devices (e.g. devices from Loxone) you must set this port to the same value as "TCP/UDP remote port number".
Ethernet transfer typeUDP
Description and recommended values for the Protocol parameters:
Maximum APDU length acceptedDespite the fact that for BACnet/IP the recommended length of data packet of the application layer is 1476 byte, some devices may require shorter packets.
The packet length information can be found, for example, by the message of the Read list of all available information from the device type - see further.
The standard tolerates following alternative lengths (octets = number of bytes):
50 octets
128 octets
206 octets (fits LanTalk frame)
480 octets (fits ARCNET frame)
1024 octets
1476 octets (fits ISO 8802-3 frame) (default)

The communication description by means of the PmaCommGroup object

The variables in the PmaCommGroup object (or even better the variables in the PmaData object with ExtComm data extension) are read by this driver all together in one message. The driver itself does not limit number of variables, but if the designer sets too many variables in a single PmaCommGroup object then the maximum message size can be exceeded (see the "Maximum APDU length accepted" configurator) and the transmission fails. Therefore it is recommended to separate variables into more PmaCommGroup objects.
Note: The PmBACnet driver does not yet support splitting the message into multiple UDP packets (so-called segmentation). Other PROMOTIC communication drivers automatically separate the variables from a single PmaCommGroup object into multiple messages. But it is not possible for this protocol - if implemented then it would significantly limit number of variables in one message. Therefore the decision to define the number of variables depends on the application designer that can optimize the variable count in PmaCommGroup object to maximum number possible.

All variables are read (if the "Data refresh enabled" configurator is checked). When writing into the variable, only the single variable is sent into the device (if the "Auto send when writing to item" configurator is checked).

Description of the "ItemId" configurator:
ItemId is the text identifier of the item that is used for addressing the item in the device. The "ItemId" configurator tells the driver how to receive or send the item value.
The text can be written manually, or it can be assembled in the window opened by the button to the right of the configurator.
Macro expression can be used for input (it is evaluated after the application is launched).

The text string for ItemId has in general the following syntax:
ObjectType.ObjectNumber.PropertyIdentifier[PropertyIndex].priN
- ObjectType: See Object types.
- ObjectNumber: It is not entered for the "Device" object type.
- PropertyIdentifier: The identifier can be entered by name or as a number. Entering the identifier as a number is relevant e.g. for non-standard properties specific for the PLC automaton.
- PropertyIndex: (optional) The object property can also be represented by an array - in such case, the array index in brackets can be used.
- priN: (optional) Entered only for the "present-value" property. N is the writing priority. See Saving into present-value property.
 
Examples of the identifier syntax:
Device.model-name = Device type name
AnalogValue.2.present-value.pri8 = Current analog value of number 2. When writing into this item, the value will have the priority 8 (see Saving into present-value property).
BinaryValue.14.present-value[4] = Current value on the index 4 in binary array numbered 14
AnalogOutput.15.priority-array[8] = Analog output value 15, which is assigned to priority 8.
AnalogOutput.15.priority-array = An array of outputs and priorities of analog output 15.
This field is stored in a variable of the String type in the KeyVal format. This String contains only set priorities with values (e.g. "p1:12.8;p8:3.14;" - priority 1 with the value 12.8 and priority 8 with the value 3.14).
AnalogInput.20.event-state = Value of the event-state property of analog input 20.
Instead of this property, other properties can be used, for example: object-identifier, object-name, object-type, status-flags, out-of-servis, units, description, device-type, reliability, update-interval, min-pres-value, max-pres-value, resolution, COV-increment, time-delay, notification-class, high-limit, low-limit, deadband, limit-enable, event-enable, acked-transitions, notify-type, event-type-stamps, event-message-texts, profile-name.
AnalogInput.20.2048 = Here is the property specified by 2048.
 
In order to define the ItemId correctly, it is recommended to:
- Use the message of the Read list of all available information from the device type to find out the contents of of the device (see further).
- For entering the value in the "ItemId" configurator use the selection window that can be opened by the button to the right from the inputbox.


Caution when writing values into the device:
Setting the ItemId defines the required BACnet object and property. But BACnet data type is not defined. When the value is received, the driver recognizes the value data type and remembers it for the specific variable. When sending the value into the device after that, the driver already knows the type to be used for sending the value.
But if at least one receive does not occur before, then the driver may not know the correct BACnet type for defined variable is used by the device. The driver then sets some suitable type based on the BACnet property name. This may result in setting incorrect type. Therefore it is recommended to execute at least one receive before sending a value.

Description of the "PmaCommGroup > Parameters > Special Parameters" configurator:
This configurator is not used for given driver.

The communication description by means of the PmaCommMsg object

The PmaCommMsg object can be used for special communications, that cannot be executed by the PmaCommGroup object. For this driver, there is only a singe special message implemented:

- Read list of all available information from the device:
In order to set the "ItemId" configurator correctly in variables of the PmaCommGroup object it is necessary to have the information about available objects in the device. This information can be read from the device and this is exactly the sole purpose of this message:
The message reads the information and saves it into a text string on the "Data-received" tab.
The information gathered by this message provide an overview of objects present in current device (object list with types and object numbers). This information can be used for compiling the ItemId in the PmaCommGroup object.
The PmBACnet driver does not yet support splitting the message into multiple UDP packets (so-called segmentation). That's why this message doesn't work (it reports abort-segmentation-not-supported error) if the device contains many objects and their list does not fit in one packet.

In order to create and configure the PmaCommMsg object correctly it is handy to use the preconfiguration: If you (in this preconfiguration) check the configurators: then the correctly configured PmaCommMsg object is created together with a panel that can run the message and read the desired information from the PLC device.

History:
Pm9.00.25: The property identifier in ItemId can now also be entered as a number.
Pm9.00.22: Fixed bug: Receiving and writing to the priority-array[x] property is now available.
Also the driver functionality is extended to receive a separate property priority-array (i.e. without specifying an index) - see the example AnalogOutput.15.priority-array.
Pm9.00.03: Fixed bug: The response to a specific request was not tested. An error occured if the response was received late, after timeout.
Pm8.03.11: Now supports the "PulseConverter" type object.
Pm8.03.04: Receive and write of the weekly-schedule property in the Schedule object is now working.
Pm8.02.16: Generalization of writing into the device:
- U present-value can now be entered with priority for writing.
- When writing value null for JavaScript or Empty for VBScript, the BACnet value NULL is sent - causing the device to delete the data.
Pm8.02.03: Created
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.