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 can 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.
:
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.
-
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 data type with the number of the value (these values can be read and written).
-
date - In the PROMOTIC application represented by the
Date data type.
-
time - In the PROMOTIC application represented by the
Date data type.
:
The
present-value property forms the priority array
priority-array with 16 priority values. On 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:
Description and recommended values for the Protocol parameters:
| Maximum APDU length accepted | Despite 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). On writing into the variable, only the single variable is sent into the device (if the "
Auto send on 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 either 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
- 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 device.
- PropertyIndex: (optional) The object property can also be represented by an array - in such case, the array index inside the square brackets can be used.
Examples of the identifier syntax:
Device.model-name = Device type name
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 priorities and values of analog output
15.
This array 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 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:
- 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.
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.
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 is 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.