PLC library: TcBACnetRev12.Lib
The functionality of the PLC library "TcBACnetRev12.lib" is described below. The library offers convenient access to objects of a BACnet configuration from a PLC program.
Overview
The PLC library "TcBACnetRev12.lib" is a collection of function blocks for programming a BACnet controller. For each BACnet object function blocks are available that are read and written via the selected Properties. In general a distinction is made between function blocks for server and client objects. Function blocks for client objects have the prefix "Remote", since they enable access to remote BACnet objects on other devices. The BACnet object function blocks ascertain whether process data are valid and the BACnet controller is ready for operation (bReady).
The function block FB_BACnet_Adapter represents a BACnet device and therefore the access point to the BACnet network via a network card. This block enables the existence of a link to be verified, for example. To make the PLC program more transparent, the BACnet adapter is created as a global variable within the "TcBACnetRev12.lib", since in the majority of the projects a single BACnet adapter is used.
Depending on the client and server functionality, the function blocks FB_BACnet_Device or FB_BACnet_RemoteDevice can be used to link state and control information for the BACnet client and server. The operational readiness of the BACnet objects is determined via the client and server status and the property System_Status for the respective device or remote device object. Each BACnet object function block must therefore transfer a reference to the instance of the corresponding FB_BACnet_Device or FB_BACnet_RemoteDevice, in order to enable the status evaluation (bReady).
The following figure shows an overview of the function blocks of "TcBACnetRev12.lib" and the corresponding links with the BACnet modules. The linking between a PLC program based on "TcBACnetRev12.lib" and the BACnet modules of a configuration can be automated via the function PLC automapping.
Compatibility and new features
From TwinCAT 2.11 Build 2042, the PLC library "TcBACnetRev12.lib" is included in the basic TwinCAT installation. The library is largely compatible with the previous version "TcBACnet.lib". A brief overview of new features is provided below:
- BACnet function block names are compatible (except Accumulator)
- Improved alignment of process data
- FBs for new (Revision 12) objects, consistently _Ex for all objects
- FB_BACnet_Device
- Data type, name nAmsPort changed (no function with Rev. 12)
- Automatic reading of ADS information
- Triggering of persistent data writing
- Loop_Drv: Internal control active automatically (via BACnet stack)
- Loop_Ex: Auto-tuning (PID determination), ramp limitation (AccLimit) outputs
- New ADS functions:
- String decoding according to Win1252 (Description, ObjectName,EventMessageTexts)
- ExceptionSchedule (bool), WeeklySchedule (bool), LogBuffer (Real), RecipientList (Read,Write), ObjectList, RecpientList (Notification Class)
- Access to NotificationSink functions (Acknowledge, Read message list, Delete)
- Support for time synchronization
- Remote_blocks
- ERR_OPERATIONAL error if client not present
- bTriggerWOC
- For write access, _EX or _WR versions must be used.
Older projects that were created based on the "TcBACnet.Lib" PLC library can be converted for use with the new library based to the following scheme:
- Delete "TcBACnet.Lib" from the PLC project
- Add "TcBACnetRev12.Lib"
- Recompile
- In the System Manager:
- Re-load the PLC project
- undo the old mapping, if necessary
- create a BACnet device in the new Revision, if necessary.
- Run PLC automapping
Persistent data cannot be preserved during the changeover to the new "TcBACnetRev12.lib".
As a rule, PLC projects based on the old "TcBACnet.Lib" should also work under "BACnet Revision 12", without the need for conversion.
Overview
An overview of the PLC library components is provided below. Detailed information can be called up via corresponding links.
BACnet adapter and Notification Sink
Blocks | Description |
---|---|
Function block for linking the PLC program with a local BACnet adapter (network card). | |
Function block for realizing an ADS connection with a BACnet NotificationSink. |
Local BACnet objects (server)
Standard objects
The following function blocks establish the connection between the BACnet object in the TwinCAT System Manager and its use in the PLC program. The blocks contain all comments that are required for the PLC automapping.
The standard function blocks are available in two versions:
- Minimum process data - only the essential properties are linked, including Present_Value and Status_Flags.
- Extended process data - Object_Identifier, Event_Flags and Reliability are also linked. Function blocks with extended process data are identified with the extension _EX.
The documentation refers to the version with extended process data. Advanced process data are identified as such in the description.
Blocks | Symbol | BACnet object | Description |
---|---|---|---|
| Accumulator | A BACnet Accumulator object represents a measured value determined through pulse count. | |
| Analog Input | A BACnet Analog Input object represents an analog input value. | |
| Analog Output | A BACnet Analog Output object represents an analog output value. | |
| Analog Value | Represents an analog state value within a program. | |
| Averaging | Enables calculation of statistical data within a control system. | |
| Binary Input | A Binary Input object represents a binary input value. | |
| Binary Output | A Binary Output object represents a binary output value. | |
| Binary Value | Represents a binary state value within a program. | |
| Calendar | Enables separate definition of exception days for schedules (schedule objects). | |
| Command | Enables control of complex sequences over chronologically staggered write commands for BACnet object properties. | |
| Device | Forms the logical entry point of a BACnet device. Includes the list of all BACnet objects for this device. | |
| Event Enrollment | Enables configuration of rule-based event messages. The notification system integrated in many objects enables definition of comprehensive rules for triggering event messages. Example: additional or multiple limit value pairs for a PresentValue. | |
| File | Represents properties of a file object. | |
| Group | Group objects enable consolidation of multiple Properties in a single data point. | |
| Loop | Represents the properties of a PID controller. | |
| Multi State Input | Represents an integer/multi-stage input value. | |
| Multi State Output | Represents an integer/multi-stage output value. | |
| Multi State Value | Represents an integer/multi-stage state value. | |
| Notification Class | The Notification Class object is used to configure the distribution of event messages (EventNotifications). | |
| Program | A BACnet Program object enables changing the states of a PLC program. | |
| Pulse Converter | A Pulse Converter object represents a measured value determined through pulse count. | |
| Schedule | Represents a schedule which is used to write values of other BACnet objects on the basis of time-based switching entries. | |
| Trend Log | Represents recorded historical data, which are recorded cyclically at fixed intervals or event-based. |
Local BACnet objects (ADS)
Write access to the property PresentValue occurs priority-based via ADS. This function block can be used in cases where no priorities for write access have been specified in advance of the program runtime, or to manipulate several priority levels in the program at the same time.
Function blocks | Description |
---|---|
A BACnet Analog Output object represents an analog output value. | |
Represents an analog state value within a program. | |
A Binary Output object represents a binary output value. | |
Represents a binary state value within a program. | |
Represents an integer output value. | |
Represents an integer output value. |
Function blocks | Description |
---|---|
This block is linked to a TwinCAT BACnet Loop object with enabled internal control. The control algorithm is implemented directly in the BACnet stack, not in the PLC. All other loop-FBs implement their control algorithms within the PLC. The advantage of this function block is a more efficient execution time, since fewer BACnet properties have to be linked via process data. |
Local BACnet objects (raw versions)
RAW FBs enable specification of physical measured and control values from the PLC. This is in contrast to other FBs for physical measured and control values, which are linked directly to a hardware module. The corresponding RawIo* process record of the BACnet object is linked directly to a PLC variable via PLC automapping.
Function blocks | Description |
---|---|
A BACnet Accumulator object represents a measured value determined through pulse count. In this case this measured value is formed in the PLC. | |
A BACnet Analog Input object represents an analog input value. This function block can be used for postprocessing of analog input values in the PLC, or for generating read-only analog values directly in the PLC. | |
A BACnet Analog Output object represents an analog output value. This function block can be used in cases where an analog output signal is to be pre-processed prior the output, for example. | |
A Binary Input object represents a binary input value. This function block can used in cases where postprocessing of binary input values in the PLC is desirable (e.g. for debouncing) | |
A Binary Output object represents a binary output value. This function block can be used in cases where a binary output signal is to be pre-processed prior the output, for example. | |
A multi-state input object represents an integer/multi-stage input value. | |
A multi-state output object represents an integer/multi-stage output value. | |
A Pulse Converter object represents a measured value determined through pulse count. |
Function blocks | Description |
---|---|
Function block that is compatible with Revision 6. It should only be used with TwinCAT BACnet Revision 6. | |
Function block that is compatible with Revision 6. It should only be used with TwinCAT BACnet Revision 6. |
Client BACnet objects (remote)
The function blocks for remote objects offer access to BACnet objects of other devices. A distinction is made between three versions of remote FBs. The basic FBs without extension offer read access to the properties PresentValue and StatusFlags. The "_EX" versions support a wider range of properties. The "_WR" versions can be used for additional write access with minimum read properties. In general, function blocks with few properties are preferable, to minimize the network load.
The function. exp export (in the BACnet device) can be used for efficient integration of BACnet devices. It facilitates generation of PLC variable declarations for the remote FBs of scanned client configurations or configurations that were read via an EDE file.
Function blocks | Description |
---|---|
A BACnet Accumulator object represents a measured value determined through pulse count. | |
A BACnet Analog Input object represents an analog input value. | |
A BACnet Analog Output object represents an analog output value. | |
Represents an analog state value within a program. | |
Enables calculation of statistical data within a control system. | |
A Binary Input object represents a binary input value. | |
A Binary Output object represents a binary output value. | |
Represents a binary state value within a program. | |
Enables separate definition of exception days for schedules (schedule objects). | |
Enables control of complex sequences over chronologically staggered write commands for BACnet object properties. | |
Forms the logical entry point of a BACnet device. Includes the list of all BACnet objects for this device. | |
Enables configuration of rule-based event messages. The notification system integrated in many objects enables definition of comprehensive rules for triggering event messages. Example: additional or multiple limit value pairs for a PresentValue. | |
Represents properties of a file object. | |
Group objects enable consolidation of multiple Properties in a single data point. | |
Represents the properties of a PID controller. | |
Represents an integer/multi-stage input value. | |
Represents an integer/multi-stage output value. | |
Represents an integer/multi-stage state value. | |
The Notification Class object is used to configure the distribution of event messages (EventNotifications). | |
A BACnet Program object enables changing the states of a PLC program. | |
A Pulse Converter object represents a measured value determined through pulse count. | |
Represents a schedule which is used to write values of other BACnet objects on the basis of time-based switching entries. | |
Represents recorded historical data, which are recorded cyclically at fixed intervals or event-based. |
ADS function blocks for generic access to all online properties (raw data access)
Function blocks for access to BACnet properties via ADS. All BACnet properties of server and client objects can be read or written via ADS.
Function blocks | Description |
---|---|
Read access to properties | |
Write access to properties |
ADS function blocks for access to specific properties
Function blocks for specific access to BACnet properties with data type conversion via ADS. All BACnet properties of server and client objects can be read or written via ADS. Based on the function blocks FB_BACnet_ReadProp and FB_BACnet_WriteProp, the following function blocks are used to convert data read via ADS into PLC data types, or to code PLC data as BACnet data during write access. The size limitation of approx. 8 kbytes for the following ADS access operations is related to the global ADS data buffer (see ST_BACnet_GlobalAdsBuffer).
Function blocks | Description | Access |
---|---|---|
ADS access to the property Object_Name of type CharacterString, including decoding of UTF-8, UCS-2 and UCS-4 | Read | |
ADS access to the property Description of type CharacterString, including decoding of UTF-8, UCS-2 and UCS-4 | Read | |
ADS access to the property Event_Message_Texts of type CharacterStringExtList, including decoding of UTF-8, UCS-2 and UCS-4 | Read | |
ADS access to the property Object_List of type BACnetObjectIdentifier[] | Read | |
ADS access to the property Exception_Schedule of type BACnetSpecialEventList; only for entries with data type Bool | Read, write | |
ADS access to the property Weekly_Schedule of type BACnetDailyScheduleList; only for entries with data type Bool | Read, write | |
ADS access to the property Log_Buffer of type BACnetLogRecordList; only for entries with data type Real | Read | |
ADS access to the property Recipient_List of type BACnetDestination[] (e.g. NotificationClass object) | Read, write |
ADS blocks for access to service and diagnostic data
Function blocks | Description |
---|---|
ADS access to the diagnostic data of a BACnet adapter | |
ADS access to the BACnet Notification Sink: reading a BACnet event | |
ADS access to the BACnet Notification Sink: service to acknowledge a BACnet event | |
ADS access to the BACnet Notification Sink: deleting a BACnet event (replaces FB_BACnet_NotificationSinkDelEntry) | |
ADS access to the BACnet adapter: service for time synchronization in the BACnet network (broadcast) or locally. The function block provides the current system time cyclically as an output and should be used in each BACnet project as the time source in the PLC program. |
BACnet auxiliary blocks for date and time
Function blocks | Description |
---|---|
Function for checking the validity of a numerical date value (BYTE) for the day of the month. | |
Function for checking the validity of a numerical date value (BYTE) for the day of the week. | |
Function for checking the validity of a numerical time value (BYTE) for the hour indication. | |
Function for checking the validity of a numerical time value (BYTE) for the hundredths of a second indication. | |
Function for checking the validity of a numerical time value (BYTE) for the minute indication. | |
Function for checking the validity of a numerical date value (BYTE) for the month. | |
Function for checking the validity of a numerical time value (byte) for the second. | |
Function for checking the validity of a numerical date value (BYTE) for the week of the month. | |
Function for checking the validity a numerical date value (BYTE) for the year. | |
Function for checking for placeholders (255 → undefined) in a date. | |
Function for merging of two time stamps. | |
Function for converting a BACnet time stamp to data type TIMESTRUCT.. | |
Function for string representation of a BACnet time stamp. | |
Function for checking for placeholders (255 → undefined) in a date. | |
Function for calculating the number of days in a given month of a year. | |
Function for calculating the timestamp in 100 ms steps since 1900. | |
Function for calculating the time stamp in 100 ms steps since 00:00:00.0 hrs. | |
Function for checking for placeholders (255 → undefined) in a time specification. | |
Function for merging of two time stamps. | |
Function for string representation of a BACnet time stamp. | |
Function for converting a time stamp of data type TIMESTRUCT to a BACnet time stamp. | |
Function for checking for placeholders (255 → undefined) in a time specification. |
BACnet auxiliary blocks for bit conversion (bit strings)
Function blocks | Description |
---|---|
Function to decode the process data of the property Acked_Transitions of a BACnet object. | |
Function for encoding the value of the property Event_Enable of a BACnet object. | |
Function for encoding the value of the property Limit_Enable of a BACnet object. | |
Function for encoding the value of the property Status_Flags of a BACnet object. | |
Function to decode the process data of the property Limit_Enable of a BACnet object. | |
Function to decode the process data of the property Status_Flags of a BACnet object. |
BACnet auxiliary blocks for multi-state objects
Function blocks | Description |
---|---|
Function for implementing a UDINT value of the PLC in the process data value of a BACnet MultiState* object property Present_Value. |
BACnet auxiliary blocks for REAL values
Function blocks | Description |
---|---|
F_BACnet_RealPV (obsolete: F_BACnet_AnalogPV) | Function for implementing a REAL value of the PLC in the process data value of a BACnet analog* object property Present_Value. |
Function for checking a REAL value for finiteness. | |
Function for comparing two floating-point values considering the value range. | |
Function for comparing two floating-point values considering the value range. | |
Function for comparing two floating-point values considering the value range. | |
Function for comparing two floating-point values considering the value range. | |
Function for comparing two floating-point values considering the value range. | |
F_BACnet_RealNull (obsolete: F_BACnet_NAN) | Function returns the floating-point value "Not aNumber", which, as value of the property Present_Value of an analog* object, corresponds to the value Null (no value). |
Function returns the floating-point value "Not aNumber", which, as value of the property Present_Value of an analog* object, corresponds to the value Nothing (do not evaluate). Process data with the coded value Nothing are not processed by the BACnet stack from Revision 12. | |
Function for converting a floating-point number to a string, considering the value range. |
BACnet auxiliary blocks for string processing
Function blocks | Description |
---|---|
Function for outputting the object ID of a BACnet object as a short string. | |
Function block for decoding BACnet strings. | |
Function block for coding BACnet strings. |
Signal conversion
Function blocks | Description |
---|---|
Function block for generating a pulsating output signal, with defined switch-on and switch-off duration in percent of the cycle duration (pulse width modulation). |
Auxiliary functions for BACnet BinaryPV data types
Function blocks | Description |
---|---|
Function for logical linking of BACnet BinaryPV values. | |
Function for inverting a BACnet BinaryPV value. | |
Function for logical linking of BACnet BinaryPV values. | |
Function for logical linking of BACnet BinaryPV values. | |
Function for converting a BACnet BinaryPV value to data type BOOL. | |
Function for implementing a value with data type BOOL of the PLC in the process data value of a BACnet binary* object / property Present_Value. |
Other BACnet auxiliary functions
Function blocks | Description |
---|---|
Function for determining the position of a BACnet object ID in a list of IDs. | |
Function for coding the object type and the object instance in the BACnet Object_Identifier. | |
Function for decoding the BACnet Object_Identifier in the object instance (object number). | |
Function for decoding the BACnet Object_Identifier in the object type. | |
Function block for limiting signal change per time (maximum acceleration). | |
Function block for averaging an input variable X over n values. | |
PID controller block in parallel configuration or Ideal form. | |
Function block for emulating a 1st order deceleration. |
BACnet constants
Constants | Description |
---|---|
Global constants for default values, error messages, data range limits etc. |
BACnet diagnostic data
Data Types | Description |
---|---|
Describes diagnostic data of the Ethernet adapter such as sent, received or faulty messages. | |
Contains information on execution times within the BACnet stack. | |
Contains information on sent and received BACnet network packets. | |
Information on memory usage. | |
Contains information on persistent data and change statistics for the properties. | |
Describes diagnostic data of the Ethernet adapter. | |
Describes diagnostic data of the Ethernet adapter. | |
More detailed data for BACnet services |
BACnet data types
Data Types | Description |
---|---|
Structure with connection information for an ADS server of the BACnet driver | |
BACnet string, including the encoding format used. | |
List of BACnet strings. | |
Date with day, day of the week, month, and year. | |
Describes date and time. | |
See BACnet diagnostic data. | |
PLC mapping of BACnet data type BACnetEventTransitionBits (properties Event_Enable and Acked_Transitions). | |
Structure for data exchange of the property exception_schedule with the aid of function block FB_BACnet_ExceptionScheduleProperty | |
Partial data of property ExceptionSchedule of the Schedule object | |
PLC mapping of BACnet data type BACnetLimitEnable. See BACnet specification DIN EN ISO 16484-5 for property Limit_Enable. | |
PLC mapping of BACnet data type BACnetLogRecord for Log_Datum of type Real. See BACnet specification DIN EN ISO 16484-5 for property Log_Buffer. | |
Structure for data exchange of property Log_Buffer with the aid of function block FB_BACnet_LogBufferProperty | |
PLC mapping of the data of an event entry of the BACnet Notification Sink. | |
Structure for describing the object list of a device. See BACnet specification DIN EN ISO 16484-5 for property Object_List (device object). | |
PLC mapping of BACnet data type BACnetObjectTypesSupported. See BACnet specification DIN EN ISO 16484-5 for property Protocol_Object_Types_Supported. | |
Structure for operating the program object | |
Structure for operating the program object | |
Structure for data exchange of property Recipient_List with the aid of function block FB_BACnet_RecipientListProperty | |
Partial structure for data exchange of property Recipient_List with the aid of function block FB_BACnet_RecipientListProperty | |
PLC mapping of BACnet data type BACnetServicesSupported. See BACnet specification DIN EN ISO 16484-5 for property Protocol_Services_Supported. | |
PLC mapping of BACnet data type BACnetStatusFlags. See BACnet specification DIN EN ISO 16484-5 for property Status_Flags. | |
PLC mapping of BACnet data type Time. See BACnet specification DIN EN ISO 16484-5 for data type BACnetDateTime. | |
PLC mapping of BACnet data type BACnetTimeValue for entries of type Bool or Null. See BACnet specification DIN EN ISO 16484-5 for data type BACnetTimeValue. | |
PLC mapping of BACnet data type BACnetTimeValue for entries of type Bool. | |
List of BACnet_TimeValue entries. | |
Partial structure of ST_BACnet_TimeValue | |
Structure for data exchange of property Weekly_Schedule with the aid of function block FB_BACnet_WeeklyScheduleProperty |
BACnet Enumerationen
Data Types | Description |
---|---|
PLC mapping of BACnet data type BACnetAction. See BACnet specification DIN EN ISO 16484-5 for property Action. | |
Status of the BACnet adapter. | |
PLC mapping of BACnet data type BACnetBinaryPV. See BACnet specification DIN EN ISO 16484-5 for property Present_Value of binary* objects. | |
List of possible BACnet data types (excerpt). | |
Bit assignment of the days of the week | |
Status of the BACnet server object (see BACnet specification DIN EN ISO 16484-5 for BACnet device object and property System_Status). | |
PLC mapping of BACnet data type BACnetEventState. See BACnet specification DIN EN ISO 16484-5 for property Event_State. | |
Bit assignment of the event transition flags Event_Enable and Acked_Transitions). | |
PLC mapping of BACnet data type BACnetEventType. See BACnet specification DIN EN ISO 16484-5 for property Event_Type. | |
PLC mapping of BACnet data type BACnetFileAccessMethod. See BACnet specification DIN EN ISO 16484-5 for property File_Access_Method. | |
PLC mapping of BACnet data type BACnetLifeSafetyMode. See BACnet specification DIN EN ISO 16484-5 for property Mode and Accepted_Modes. | |
PLC mapping of BACnet data type BACnetLifeSafetyOperation. See BACnet specification DIN EN ISO 16484-5 for property Operation_Expected. | |
Bit assignment of the Limit-Enable-Flags (Limit_Enable). | |
PLC mapping of BACnet data type BACnetLoggingType. See BACnet specification DIN EN ISO 16484-5 for property Logging_Type. | |
Operating modes of PLC LOOP object FB_BACnet_LOOP | |
PLC mapping of BACnet data type BACnetNotifyType. See BACnet specification DIN EN ISO 16484-5 for property Notify_Type. | |
Bit assignment of the Object Types-Supported flags (Protocol_Object_Types_Supported). | |
List of possible BACnet objects (excerpt). | |
PLC mapping of proprietary BACnet data type PersistentDataState (see BACnet device object | |
E_BACNETPIDTUNINGMODE | Tuning modes of block FB_BACnet_LOOP |
PLC mapping of BACnet data type BACnetPolarity. See BACnet specification DIN EN ISO 16484-5 for property Polarity. | |
List of possible BACnet priorities of a commandable property (e.g. Present_Value). | |
PLC mapping of BACnet data type BACnetProgramError. See BACnet specification DIN EN ISO 16484-5 for property Reason_For_Halt and function block description FB_BACnet_Program | |
E_BACNETPROGRAMREQUEST | PLC mapping of BACnet data type BACnetProgramRequest. See BACnet specification DIN EN ISO 16484-5 for property Program_Change and function block description FB_BACnet_Program |
PLC mapping of BACnet data type BACnetProgramState. See BACnet specification DIN EN ISO 16484-5 for property Program_State and function block description FB_BACnet_Program | |
List of possible BACnet properties (excerpt). | |
List of possible values of BACnet property Reliability (excerpt). | |
PLC mapping of BACnet data type BACnetSegmentation. See BACnet specification DIN EN ISO 16484-5 for property Segmentation_Supported. | |
PLC mapping of BACnet data type BACnetSilencedState. See BACnet specification DIN EN ISO 16484-5 for property Silenced. | |
Bit assignment of the Status flags (property Status_Flags). | |
The enumeration contains a list of the string encodings supported by the BACnet driver. | |
PLC mapping of BACnet data type BACnetEngineeringUnits. See BACnet specification DIN EN ISO 16484-5 for property Units. |