From d40188a8ec3a4f671798c02cf5daa68907e76df5 Mon Sep 17 00:00:00 2001 From: Steve Karg Date: Fri, 2 Jan 2026 10:00:12 -0600 Subject: [PATCH] Updated doc/README.developer with some path name and helpful info --- doc/README.developer | 147 +++++++++++++++++++++++-------------------- 1 file changed, 78 insertions(+), 69 deletions(-) diff --git a/doc/README.developer b/doc/README.developer index b100f250..b42b9f01 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -5,7 +5,8 @@ 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) and a single Device Object. This even applies to a BACnet client on a +(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 @@ -37,41 +38,41 @@ from the following BACnet services (messages) provided by this BACnet stack: * 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 I like to add unit testing, a demo -handler and send function, as well as a demo command line example. +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. There are example handlers -and send functions for all the services that the stack supports: +add a handler and possibly a sending function. Some example handlers +and send functions for the services that the stack supports include: - * demo/handler/h_alarm_ack.c - Alarm ACK service handler example - * demo/handler/h_arf.c - AtomicReadFile service handler example - * demo/handler/h_arf_a.c - AtomicReadFile ACK service handler example - * demo/handler/h_awf.c - AtomicWriteFile service handler example - * demo/handler/h_ccov.c - ConfirmedCOVNotification service handler example - * demo/handler/h_cov.c - SubscribeCOV service handler example - * demo/handler/h_dcc.c - DeviceCommuncationControl service handler example - * demo/handler/h_get_alarm_sum.c - GetAlarmSummary service handler example - * demo/handler/h_get_event.c - GetEventInformation service handler example - * demo/handler/h_iam.c - I-Am service handler example - * demo/handler/h_ihave.c - I-Have service handler example - * demo/handler/h_lso.c - LifeSafetyOperation service handler example - * demo/handler/h_pt.c - PrivateTransfer service handler example - * demo/handler/h_pt_a.c - PrivateTransfer ACK service handler example - * demo/handler/h_rp.c - ReadProperty service handler example - * demo/handler/h_rp_a.c - ReadProperty ACK service handler example - * demo/handler/h_rpm.c - ReadPropertyMultiple service handler example - * demo/handler/h_rpm_a.c - ReadPropertyMultiple ACK service handler example - * demo/handler/h_rr.c - ReadRange service handler example - * demo/handler/h_rr_a.c - ReadRange ACK service handler example - * demo/handler/h_ts.c - TimeSynchronization service handler example - * demo/handler/h_ucov.c - UnconfirmedCOV service handler example - * demo/handler/h_upt.c - UnconfirmedPrivateTransfer service handler example - * demo/handler/h_whohas.c - WhoHas service handler example - * demo/handler/h_whois.c - Who-Is service handler example - * demo/handler/h_wp.c - WriteProperty ACK service handler example - * demo/handler/h_wpm.c - WritePropertyMultiple service handler example - * demo/handler/h_noserv.c - unrecognized service handler example + * 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 @@ -106,20 +107,34 @@ 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. The -example object files in the BACnet stack include: +in the Device Object, since the Device Object contains an object list. Some tips +for adding a new object include: - * demo/object/ai.c - analog input object demo - * demo/object/ao.c - analog output object demo - * demo/object/av.c - analog value object demo - * demo/object/bacfile.c - File object demo - * demo/object/device.c - device object demo - * demo/object/bi.c - binary input object demo - * demo/object/bo.c - binary output object demo - * demo/object/bv.c - binary value object demo - * demo/object/lc.c - load control object demo - * demo/object/lsp.c - life safety point object demo - * demo/object/mso.c - multi-step output object demo + * 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: @@ -131,33 +146,27 @@ packets that come in from the datalink layer. The core files include: * 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 - * demo/handler/h_npdu.c - handles dispatching of the network message + * 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 currently supports one datalink layer at a time, and uses a +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 following files are used for the -datalink handling in this BACnet stack, and may have to be developed for -your particular hardware: +functions defined in datalink.h. The datalink common files are in +the src/bacnet/datalink folder, and port specific files are in ports/xx. - * bip.c - BACnet/IP functionality - depends on bip_init.c in port/xx - * dllmstp.c - MS/TP datalink layer, also in port/xx - * mstp.c - MS/TP master and receive state machine - * crc.c - computes CRC checksum for MS/TP - * ringbuf.c - MS/TP ring buffer used for testing - * arcnet.c - ARCNET datalink layer functionality, in port/xx - * ethernet.c - BACnet Ethernet datalink layer functionality, in port/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. -There are a dozen demonstration applications in the demo directory, -along with many demonstation objects and handlers. All the demos accept -command line options and have been tested under Win32 and Linux. -There is a makefile in the respective demo directory for Linux and -for Borland C++ compilers, and a master makefile at the root level -(Makefile=Linux, makefile.b32=Borland). - -The simplest demonstration is to run demo/server/bacserv on one PC (or +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 communcations -using Wireshark protocol analyzer, or test the BACnet server using -BACnet Visual Test Shell VTS3. +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/