BACnet for EPICS - Read BACnet data into EPICS IOCs

Four tarballs for download:

    BACnet for Linux - modified with methods to export data to EPICS Device Support
             (latest version, 01-April-2010, fixes many warnings reported by gcc  4.1.2)

    BACnetSupport - EPICS device support module to acquire BACNet data from bacnet4linux

    BACnetApp - A sample application that uses BACnetSupport

    BACnetWebAppl - A Web-based database management tool for coordinating bacnet4linux with all EPICS components

Notes for users/installers

There are three PowerPoint files that explain a lot of the details of running and installing the full system. These are somewhat a work in progress, but should provide enough information to get you going. It is expected that you have a basic understanding of building applications from sources on a Linux host, and are familiar with the EPICS build system. Some aspects of the installation will require root privileges.

    BACnetRuntime.ppt  -  An overview of the system. Focus is largely on the bacnet4linux component.

    BACnet4EPICS-EPICS.ppt - Information on the EPICS-specific components.

    BACnetWebAppl.ppt - Information on the Web-based database configuration tool.

Download all packages, and break out the tarballs to appropriate directories.  BACnetSupport and BACnetApp use standard EPICS build system configurations. You will have to edit configure/RELEASE in each package to reflect local directory structures.

The bacnet4linux package can be built simply by running 'make'. You will need some additional support libraries, which should be installed before building bacnet4linux:

expat - XML parser library
fuse - Filesystem in USEersapce
  - if using the standalone FUSE package (no fuse as part of Linux kernel), then the fuse package from the distribution webpage should work
  - if using fuse as a kernel built-in (recent kernels), then the fuse-devel package need to be installed (probably a distribution-supported package)
pthread - POSIX thread library, probably included with most Linux distributions

The fuse library may now be included with modern Linux distributions. At TRIUMF, it was installed as a third-party package built from sources obtained at sourceforge.net. 
[2010-Apr-01] I have now built the bacnet4linux package on Scientific Linux 5.4, which has fuse as a built-in kernel module. TO do so required installation of the fuse-devel package, which provides header files and libraries for building fuse-enabled packages.

The Makefile contains a macro that should be modified to reflect the local filesystem. It points to an arbitrary filename or directory, which must exist at runtime. It is used only as a seed for the key generator used with the IPC MSG Queue system. No data will be stored there. There is a corresponding configuration item in the EPICS IOC startup script. See below.

At TRIUMF, only the BACnet/Ethernet datalink layer is used. Other datalink layers are included in the bacnet4linux package, and are believed to be fully functional and compatible with the rest of the system.

bacnet4linux is an original work created by Steve Karg.

EPICS Device Support

EPICS device support requires knowledge of some data structures that are used in the bacnet4linux package, in order to disassemble data that is transferred through the message queues. These data structures are defined in three C header files that are part of bacnet4linux. To build the EPICS support package, these headers can be symbolic links to the bacnet4linux source files.

From 'devBACnetMsg.c':
#include    "bacnet_enum.h
#include    "bacnet_struct.h
#include    "bacnet_text.h"
In the src directory,
ln -s /directory/name/of/bacnet4linux/bacnet_enum.h .
ln -s /directory/name/of/bacnet4linux/bacnet_struct.h .
ln -s /directory/name/of/bacnet4linux/bacnet_text.h .

Database Config. Tool

The Web-based database configuration tool requires a functioning Apache (or other, Apache is the only server tested) HTTP server. It also requires a functioning Postgresql database server. It is possible to run the Web tool on a host separate from the bacnet4linux/EPICS IOC host. Files to and from the application can be copied using whatever means appropriate. A one-time-only database configuration is required. There are two SQL scripts contained in the Web Application package to assist with this. Some minor editing of these scripts may be required to satisfy local conventions.
A support library of Perl code to build EPICS EDM panels is required. It can be downloaded at TRIUMFedlbuild.html. Instructions for installation and configuration to suit local conventions are on the EdlBuild web pages. If the library is installed in a non-standard location, then one line in the Web Application tool Perl script 'bacnetDb.pl' can be edited to suit:
use lib '/usr/local/perllib';

Edit the line to reflect the installation location of the perl library.

Unpack the BACnetWebAppl package into the Apache cgi-bin directory. bacnetDb.pl must be executable by the Apache web server. The user-id of the Apache web server is used to access the Postgresql database. Edit bacnetDb.pl :
my $dbiUser = "apache";
my $dbName = "bacnet001";

Change the user id and database name to reflect the actual username and database names chosen. The two SQL scripts used to initialize the database can be similarly modified. Some helper Perl modules are installed in the BACnet subdirectory of the cgi-bin directory. The tarball structure should reflect this arrangement.

For the purpose of testing/experimenting, a sample XML database acquired at TRIUMF can be downloaded here.


Sample IOC startup script.


#!/usr1/local/epics/appl/bacnet4linux/bin/BACnet
## IOC startup script for TRIUMF IPCMSG/BACnet Device Support

cd /usr1/local/epics/appl/bacnet4linux

epicsEnvSet("EPICS_CA_ADDR_LIST","localhost")
epicsEnvSet("EPICS_CA_REPEATER_PORT","9101")
epicsEnvSet("EPICS_CA_SERVER_PORT","9102")

##
## bacnet4linux set this with -m commandline switch
epicsEnvSet("BACNET_VFS_MOUNTPOINT","/mnt/BACnet")

## Register all support components
##
dbLoadDatabase("dbd/BACnet.dbd")
BACnet_registerRecordDeviceDriver(pdbbase)
var debugFlag 3

## setup MSG Queue Environment for message queue 1
##
## field(INP,"@1 4 'f' "312:0:3"): the '1' in this address corresponds
## to the "1" in the first arg to ipcmConnect()
##
## (bacnet4linux sets these in Makefile or bacnet_msg.h)
BACnetMsgConnect( "1", "/var/BACnet", 9999 );


## Load record instances
#
# Main IBCS database, usually a soft link to a dated version
#
dbLoadRecords("db/bacnet.db")

var debugFlag 0

iocInit()

var debugFlag 1


Two files/directories are named in the startup script. The BACNET_VFS_MOUNTPOINT directory is a directory that is used by bacnet4linux as the mountpoint of the virtual filesystem. Device support finds this directory through the environment variable named in the startup script. The bacnet4linux component gets this value from the -m commandline switch. Needless to say, the values supplied in both places must be the same, and the specified directory must exist. The IPC MSG queue key seed are defined as macros in the bacnet4linux Makefile. The values are arbitrary, but the file or directory specified must exist (must have a filesystem inode), and the values chosen must be the same in both the Makefile and the IOC startup script.

There are some low-level testing and diagnostics tools included in the bacnet4linux package. These may be used to test the IPC MSG Queues and the Virtual Filesystem, as well as serving as sample applications for development of other tools. These are documented in 'C' and in 'Perl'.  The standard Linux tool 'ipcs' is indispensable for monitoring behavior of the Message Queues. ipcs may be required to delete unused or over-flowed queues due to misconfiguration during testing. At times, during setup, a misconfiguration of the Virtual Filesystem may occur, or the bacnet4linux component may fail to start due to misconfiguration. Sometimes, this results in a mounted filesystem, but the  bacnet4linux application is no longer running to support it. Re-running bacnet4linux will then fail, with a message like 'unable to mount virtual filesystem...'. If this happens, simply use the standard Linux tool 'umount' to unmount the disconnected virtual filesystem. Subsequently, running bacnet4linux should succeed in mounting a new virtual filesystem. Orderly shutdown of bacnet4linux is accomplished by issuing a Ctrl-C at its console, and this should correctly close off all file and network connections.

The EPICS-specific components are named to suggest EPICS compatibility with EPICS release 3.14.10, and this is the version against which they have been built and run here at TRIUMF. I feel certain that there is nothing which should limit the code from building and running against any 3.14 release of EPICS.

In the bacnet4linux package, there are provisions for specifying a BACnet device ID and a BACnet vendor ID. At TRIUMF, these were chosen somewhat arbitrarily, and were not given any official designation. In particular, for a rigorous conformity to BACnet rules, the vendor ID should be issued by ASHRAE. It is up to local installations to chose what to do. Do note, however, that the bacnet4linux tool will probably show up on existing operator screens as a device previously unknown. Also note that when a device ID is chosen, every effort should be made to use an ID that is not already in use on your network. It is unknown what will happen if a BACnet device ID is used non-uniquely, but I think it is safe to say that it cannot be good.

The packages  and source code may contain references to 'IBCS', which is the original ISAC Building Control System acronym used at TRIUMF.

Rod  Nussbaumer
ISAC Controls, TRIUMF
Vancouver, Canada

This page last modified 2010-Apr-01