From cc0dadf906978072b06600d59fc5cf3076708002 Mon Sep 17 00:00:00 2001 From: skarg Date: Sun, 8 Oct 2006 10:36:41 +0000 Subject: [PATCH] updated the readme documentation. --- bacnet-stack/doc/README.build | 9 +-- bacnet-stack/doc/readme.txt | 103 ++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 6 deletions(-) create mode 100644 bacnet-stack/doc/readme.txt diff --git a/bacnet-stack/doc/README.build b/bacnet-stack/doc/README.build index 2771a749..43ae1b73 100644 --- a/bacnet-stack/doc/README.build +++ b/bacnet-stack/doc/README.build @@ -2,11 +2,8 @@ BACnet Stack Developer Build This BACnet Stack is designed as a library for an embedded product. -However, there are a number of demos in the demo/ directory that -show how it can be used for client and server applications. +However, there are a number of example applications in the demo/ directory +that show how it can be used for client and server applications. The demos can be built using makefiles in the root directory, or by -using individual makefiles in the demo directories. - - - +using individual makefiles in the demo directories. \ No newline at end of file diff --git a/bacnet-stack/doc/readme.txt b/bacnet-stack/doc/readme.txt new file mode 100644 index 00000000..2543c7f0 --- /dev/null +++ b/bacnet-stack/doc/readme.txt @@ -0,0 +1,103 @@ +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) and a single Device Object. 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. The following BACnet +services (messages) are provided by this BACnet stack files: + + * abort.c - BACnet Abort service encode/decode + * bacerror.c - BACnet Error service encode/decode + * reject.c - BACnet Reject service encode/decode + * rp.c - BACnet ReadProperty service encode/decode + * arf.c - AtomicReadFile service encode/decode + * awf.c - AtomicWriteFile 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 + * 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 + +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 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. The +example object files in the BACnet stack include: + + * demo/object/ai.c - analog input object demo + * demo/object/ao.c - analog output 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/lsp.c - life safety point demo + +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 + * bacstr.c - BACnet string encoding and decoding + * bigend.c - determines if CPU is bigendian + * datalink.c - generic API for all datalink layers + * npdu.c - handles dispatching of the network message to the apdu +dispatcher. It would be where routing is handled if the stack supported more +than one physical layer. + +The DataLink Layer controls orderly access to the physical medium. The following +files are used for the datalink handling in this BACnet stack: + + * bip.c - BACnet/IP functionality - depends on bip_init.c in port/xx + * dllmstp.h - MS/TP datalink layer (see also dlmstp.c,mstp.c,crc.c) + * arcnet.h - ARCNET datalink layer functionality API + * ethernet.h - BACnet Ethernet datalink layer functionality API + +There are several demonstration applications in the demo directory, along with +several 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).