Steve Karg
173 lines
10 KiB
Plaintext
173 lines
10 KiB
Plaintext
This BACnet stack is service driven. It handles the services (BACnet requests
|
|
like WhoIs, I-Am, ReadProperty, etc) to/from the network layer to functions that
|
|
handle the application layer. There are a bunch of functions that facilitate
|
|
encoding and decoding to/from the network message data to/from something
|
|
meaningful in the program.
|
|
|
|
A BACnet device is supposed to support, at a minimum, ReadProperty service
|
|
(server), a single Device Object, and a Network Port object
|
|
(protocol-revision 17 and later). This even applies to a BACnet client on a
|
|
PC that is used for reading other BACnet devices.
|
|
|
|
There are a number of core files that you will need. Services such as
|
|
ReadProperty, I-Am, and Reject are consided core files. After determining
|
|
which services you want in your device, add files to your project or makefile
|
|
from the following BACnet services (messages) provided by this BACnet stack:
|
|
|
|
* abort.c - BACnet Abort service encode/decode
|
|
* bacerror.c - BACnet Error service encode/decode
|
|
* reject.c - BACnet Reject service encode/decode
|
|
* arf.c - AtomicReadFile service encode/decode
|
|
* awf.c - AtomicWriteFile service encode/decode
|
|
* rp.c - BACnet ReadProperty service encode/decode
|
|
* rpm.c - ReadPropertyMultiple service encode/decode
|
|
* iam.c - I-Am service encode/decode
|
|
* whois.c - WhoIs service encode/decode
|
|
* wp.c - WriteProperty service encode/decode
|
|
* wpm.c - WritePropertyMultiple service encode/decode
|
|
* dcc.c - DeviceCommunicationControl service encode/decode
|
|
* ihave.c - I-Have service encode/decode
|
|
* rd.c - ReinitializedDevice service encode/decode
|
|
* timesync.c - TimeSynchronization service encode/decode
|
|
* whohas.c - WhoHas service encode/decode
|
|
* event.c - EventNotification service encode/decode
|
|
* get_alarm_sum.c - GetAlarmSummary service encode/decode
|
|
* getevent.c - GetEventInformation service encode/decode
|
|
* lso.c - LifeSafetyOperation service encode/decode
|
|
* ptransfer.c - PrivateTransfer service encode/deco
|
|
* readrange.c - ReadRange service encode/decode
|
|
|
|
Adding additional services is a matter of adding the encoding and decoding for
|
|
the service into/from meaningful data, and unit testing, a basic
|
|
handler and send function, as well as a basic command line example.
|
|
|
|
For each service that you add to your project or makefile, you will need to
|
|
add a handler and possibly a sending function. Some example handlers
|
|
and send functions for the services that the stack supports include:
|
|
|
|
* basic/service/h_alarm_ack.c - Alarm ACK service handler example
|
|
* basic/service/h_arf.c - AtomicReadFile service handler example
|
|
* basic/service/h_arf_a.c - AtomicReadFile ACK service handler example
|
|
* basic/service/h_awf.c - AtomicWriteFile service handler example
|
|
* basic/service/h_ccov.c - ConfirmedCOVNotification service handler example
|
|
* basic/service/h_cov.c - SubscribeCOV service handler example
|
|
* basic/service/h_dcc.c - DeviceCommuncationControl service handler example
|
|
* basic/service/h_get_alarm_sum.c - GetAlarmSummary service handler example
|
|
* basic/service/h_get_event.c - GetEventInformation service handler example
|
|
* basic/service/h_iam.c - I-Am service handler example
|
|
* basic/service/h_ihave.c - I-Have service handler example
|
|
* basic/service/h_lso.c - LifeSafetyOperation service handler example
|
|
* basic/service/h_pt.c - PrivateTransfer service handler example
|
|
* basic/service/h_pt_a.c - PrivateTransfer ACK service handler example
|
|
* basic/service/h_rp.c - ReadProperty service handler example
|
|
* basic/service/h_rp_a.c - ReadProperty ACK service handler example
|
|
* basic/service/h_rpm.c - ReadPropertyMultiple service handler example
|
|
* basic/service/h_rpm_a.c - ReadPropertyMultiple ACK service handler example
|
|
* basic/service/h_rr.c - ReadRange service handler example
|
|
* basic/service/h_rr_a.c - ReadRange ACK service handler example
|
|
* basic/service/h_ts.c - TimeSynchronization service handler example
|
|
* basic/service/h_ucov.c - UnconfirmedCOV service handler example
|
|
* basic/service/h_upt.c - UnconfirmedPrivateTransfer service handler example
|
|
* basic/service/h_whohas.c - WhoHas service handler example
|
|
* basic/service/h_whois.c - Who-Is service handler example
|
|
* basic/service/h_wp.c - WriteProperty ACK service handler example
|
|
* basic/service/h_wpm.c - WritePropertyMultiple service handler example
|
|
* basic/service/h_noserv.c - unrecognized service handler example
|
|
|
|
The BACnet stack also includes files for handling client functionality, which
|
|
requires Confirmed messages, and utilizes something called binding. Binding is a
|
|
way of acquiring a Device Object Instance's MAC address by sending a broadcast
|
|
Who-Is to that Device Object and waiting for the I-Am from that Device Object.
|
|
When the I-Am arrives, the MAC address can be stored and used to send unicast
|
|
messages to that Device Object and its member objects or properties. Here are
|
|
the files that handle BACnet binding:
|
|
|
|
* address.c - This module is used to handle the address binding that occurs
|
|
in BACnet. A device id is bound to a MAC address. The normal method is using
|
|
Who-Is, and binding with the data from I-Am. This is needed for client
|
|
functionality.
|
|
* tsm.c - Transaction State Machine handles resending messages if a timeout
|
|
occurs, and is needed for client functionality. The transaction state machine is
|
|
used for Confirmed messages and segmentation. For confirmed messages, it
|
|
automatically (via tsm_timer_milliseconds) handles the retries and the timeout.
|
|
It uses the InvokeID as the unique key (although officially it should be the
|
|
combination of InvokeID, DeviceID, and service). So if you tried to send a
|
|
confirmed request to a device that was taken offline, you would see the retry go
|
|
out after every apdu_timeout until apdu retries had completed. Then the
|
|
transaction would self-delete (free). The stack as it is written (and most
|
|
stacks are written this way) has a limited amount of transactions, and if you
|
|
are sending alot of confirmed data, it can be a bottleneck if they are not freed
|
|
in a timely manner.
|
|
|
|
This BACnet stack includes a number of example objects. The reason that they are
|
|
examples is because your device and its objects and their properties will
|
|
undoubtedly be unique to your product. The example objects in this BACnet stack
|
|
are the same and contiguous for each object represented - but this is not
|
|
required. This stack does not include an example of every type of BACnet object
|
|
or property - but have no fear! Adding a new object type is mostly just a matter
|
|
of adding all the data encoding/decoding for that object for each service and
|
|
property supported. When a new object is added, it must also add some API hooks
|
|
in the Device Object, since the Device Object contains an object list. Some tips
|
|
for adding a new object include:
|
|
|
|
* Copy an existing BACnet object that is similar in functionality,
|
|
and search/replace the names of the API.
|
|
* Copy an existing BACnet object unit test in the test/ folder
|
|
for the similar object and search/replace the names of the API.
|
|
Use the unit test for verifying functionality and code coverage.
|
|
* There is a BACnet property list file that includes all the object
|
|
REQUIRED and OPTIONAL property enumerations and those can be used
|
|
as a guide for the BACnet properties in a basic example object.
|
|
* Add the BACnet object C file to the CMakeLists.txt file and the
|
|
apps/server/Makefile and others as needed.
|
|
* Add the BACnet object API to the device object(s) modules.
|
|
|
|
Some example object files in the BACnet stack include:
|
|
|
|
* basic/object/ai.c - analog input object example
|
|
* basic/object/ao.c - analog output object example
|
|
* basic/object/av.c - analog value object example
|
|
* basic/object/bacfile.c - File object example
|
|
* basic/object/device.c - device object example
|
|
* basic/object/bi.c - binary input object example
|
|
* basic/object/bo.c - binary output object example
|
|
* basic/object/bv.c - binary value object example
|
|
* basic/object/lc.c - load control object example
|
|
* basic/object/lsp.c - life safety point object example
|
|
* basic/object/mso.c - multi-state output object example
|
|
|
|
The BACnet stack includes a number of core files that handle the service
|
|
packets that come in from the datalink layer. The core files include:
|
|
|
|
* apdu.c - handles dispatching the services to the proper handlers
|
|
* bacdcode.c - primitive BACnet datatype encoding and decoding
|
|
* bacint.c - primitive BACnet integer datatype encoding and decoding
|
|
* bacreal.c - primitive BACnet REAL datatype encoding and decoding
|
|
* bacstr.c - primative BACnet string datatype encoding and decoding
|
|
* bacapp.c - application data encoding and decoding
|
|
* npdu.c - encoding and decoding of the NPDU layer data
|
|
* basic/service/h_npdu.c - handles dispatching of the network message
|
|
to the apdu dispatcher.
|
|
|
|
The DataLink Layer controls orderly access to the physical medium.
|
|
The stack, by default, supports one datalink layer at a time, and uses a
|
|
macro defined in config.h or your makefile/project to choose the macro
|
|
functions defined in datalink.h. The datalink common files are in
|
|
the src/bacnet/datalink folder, and port specific files are in ports/xx.
|
|
|
|
There are a few dozen demonstration applications in the apps/ directory,
|
|
along with many demonstation objects and service handlers. All the demos
|
|
accept command line options and have been tested under Win32 and Linux.
|
|
There is an apps/Makefile that is common for all the apps using GNU Make
|
|
build, and a Makefile in each respective apps/xx directory for the specific
|
|
application. The root Makefile is typically used for pipeline builds, tests,
|
|
and other convenience builds for the entire library. There is also
|
|
a CMakeLists.txt file that can be used to build the library and all
|
|
the applications.
|
|
|
|
The simplest demonstration is to run apps/server/bacserv on one PC (or
|
|
virtual PC), and run the other client demonstration applications one
|
|
at time on another PC (or virtual PC). Monitor the network communications
|
|
using Wireshark protocol analyzer, or interact with the BACnet server using
|
|
YABE - see https://sourceforge.net/projects/yetanotherbacnetexplorer/
|