From 776bf54278c4aa05d882789d6cfef37f92b172b2 Mon Sep 17 00:00:00 2001 From: tbrennan3 Date: Sun, 7 Mar 2010 05:42:19 +0000 Subject: [PATCH] Added partial documentation of DS-COV. Dropped the Latex output from default doxyfile. Added a convenience starting point for HTML output, the only format that has worked well for this project on doxygen. --- bacnet-stack/BACnet-stack.doxyfile | 16 ++++---- bacnet-stack/demo/handler/h_cov.c | 55 +++++++++++++++++++++++++- bacnet-stack/doc/README.doxygen | 12 ++++-- bacnet-stack/doc/output/BAC_stack.html | 16 ++++++++ bacnet-stack/include/cov.h | 15 +++++++ 5 files changed, 100 insertions(+), 14 deletions(-) create mode 100644 bacnet-stack/doc/output/BAC_stack.html diff --git a/bacnet-stack/BACnet-stack.doxyfile b/bacnet-stack/BACnet-stack.doxyfile index 7f288892..b6186ad5 100644 --- a/bacnet-stack/BACnet-stack.doxyfile +++ b/bacnet-stack/BACnet-stack.doxyfile @@ -529,7 +529,7 @@ FILE_PATTERNS = # should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should # excluded from the INPUT source files. This way you can easily exclude a @@ -781,7 +781,7 @@ HTML_DYNAMIC_SECTIONS = NO # can add a path in front of the file if the result should not be # written to the html output directory. -CHM_FILE = +CHM_FILE = BAC-stack.chm # If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can # be used to specify the location (absolute path including file name) of @@ -840,7 +840,7 @@ TREEVIEW_WIDTH = 250 # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. -GENERATE_LATEX = YES +GENERATE_LATEX = NO # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be @@ -938,7 +938,7 @@ COMPACT_RTF = NO # programs which support those fields. # Note: wordpad (write) and others do not support links. -RTF_HYPERLINKS = NO +RTF_HYPERLINKS = YES # Load stylesheet definitions from file. Syntax is similar to doxygen's # config file, i.e. a series of assignments. You only have to provide @@ -1208,14 +1208,14 @@ HAVE_DOT = NO # indirect inheritance relations. Setting this tag to YES will force the # the CLASS_DIAGRAMS tag to NO. -CLASS_GRAPH = YES +CLASS_GRAPH = NO # If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and # indirect implementation dependencies (inheritance, containment, and # class references variables) of the class with other documented classes. -COLLABORATION_GRAPH = YES +COLLABORATION_GRAPH = NO # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen # will generate a graph for groups, showing the direct groups dependencies @@ -1245,7 +1245,7 @@ INCLUDE_GRAPH = YES # documented header file showing the documented files that directly or # indirectly include this file. -INCLUDED_BY_GRAPH = YES +INCLUDED_BY_GRAPH = NO # If the CALL_GRAPH and HAVE_DOT options are set to YES then # doxygen will generate a call dependency graph for every global function @@ -1266,7 +1266,7 @@ CALLER_GRAPH = NO # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen # will graphical hierarchy of all classes instead of a textual one. -GRAPHICAL_HIERARCHY = YES +GRAPHICAL_HIERARCHY = NO # If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES # then doxygen will show the dependencies a directory has on other directories diff --git a/bacnet-stack/demo/handler/h_cov.c b/bacnet-stack/demo/handler/h_cov.c index 1167a09a..5d8f05c4 100644 --- a/bacnet-stack/demo/handler/h_cov.c +++ b/bacnet-stack/demo/handler/h_cov.c @@ -177,6 +177,17 @@ static int cov_encode_subscription( return apdu_len; } +/** Handle a request to list all the COV subscriptions. + * @ingroup DSCOV + * Invoked by a request to read the Device object's PROP_ACTIVE_COV_SUBSCRIPTIONS. + * Loops through the list of COV Subscriptions, and, for each valid one, + * adds its description to the APDU. + * @note This function needs some work to better handle buffer overruns. + * @param apdu [out] Buffer in which the APDU contents are built. + * @param max_apdu [in] Max length of the APDU buffer. + * @return How many bytes were encoded in the buffer, or -2 if the response + * would not fit within the buffer. + */ int handler_cov_encode_subscriptions( uint8_t * apdu, int max_apdu) @@ -192,6 +203,7 @@ int handler_cov_encode_subscriptions( cov_encode_subscription(&apdu[apdu_len], max_apdu - apdu_len, &COV_Subscriptions[index]); apdu_len += len; + /* TODO: too late here to notice that we overran the buffer */ if (apdu_len > max_apdu) { return -2; } @@ -202,6 +214,9 @@ int handler_cov_encode_subscriptions( return apdu_len; } +/** Handler to initialize the COV list, clearing and disabling each entry. + * @ingroup DSCOV + */ void handler_cov_init( void) { @@ -368,8 +383,27 @@ static bool cov_send_request( return status; } -/* note: worst case tasking: MS/TP with the ability to send only - one notification per task cycle */ +/** Handler to check the list of subscribed objects for any that have changed + * and so need to have notifications sent. + * @ingroup DSCOV + * This handler will be invoked by the main program every second or so. + * This example only handles Binary Inputs, but can be easily extended to + * support other types. + * For each subscribed object, + * - See if the subscription has timed out + * - Remove it if it has timed out. + * - See if the subscribed object instance has changed + * (eg, check with Binary_Input_Change_Of_Value() ) + * - If changed, + * - Clear the COV (eg, Binary_Input_Change_Of_Value_Clear() ) + * - Send the notice with cov_send_request() + * - Will be confirmed or unconfirmed, as per the subscription. + * + * @note worst case tasking: MS/TP with the ability to send only + * one notification per task cycle. + * + * @param elapsed_seconds [in] How many seconds have elapsed since last called. + */ void handler_cov_task( uint32_t elapsed_seconds) { @@ -447,6 +481,23 @@ static bool cov_subscribe( return status; } +/** Handler for a COV Subscribe Service request. + * @ingroup DSCOV + * This handler will be invoked by apdu_handler() if it has been enabled + * by a call to apdu_set_confirmed_handler(). + * This handler builds a response packet, which is + * - an Abort if + * - the message is segmented + * - if decoding fails + * - an ACK, if cov_subscribe() succeeds + * - an Error if cov_subscribe() fails + * + * @param service_request [in] The contents of the service request. + * @param service_len [in] The length of the service_request. + * @param src [in] BACNET_ADDRESS of the source of the message + * @param service_data [in] The BACNET_CONFIRMED_SERVICE_DATA information + * decoded from the APDU header of this message. + */ void handler_cov_subscribe( uint8_t * service_request, uint16_t service_len, diff --git a/bacnet-stack/doc/README.doxygen b/bacnet-stack/doc/README.doxygen index dc088285..4cfdf733 100644 --- a/bacnet-stack/doc/README.doxygen +++ b/bacnet-stack/doc/README.doxygen @@ -6,18 +6,22 @@ To build the Doxygen documentation for the BACnet Stack: graphviz installed. - To build from the command line, just enter doxygen BACnet-stack.doxyfile -- Output is built in doc/output/html and doc/output/latex -- The Latex output can be converted into a PDF (see doxygen manual, - google, and good luck!) +- Output is built in doc/output/html, and there is a convenient + starting point at doc/output/BAC_stack.html. - If you use Eclipse, - install the eClox plugin to support doxygen within Eclipse - Build the documents by right clicking on BACnet-stack.doxyfile, and selecting "@ Build Documentation" - Feel free to tweak the doxygen output to your tastes, interests, and choice of output formats. +- The Latex output can be converted into a PDF (see doxygen manual, + google, and good luck!) +- I have tried the PDF, man, and RTF outputs and not liked the results + for any of them (500+ pages). I recommend the HTML output, as it is + well organized and has an obvious flow, both of which the others lack. The doxygen output is not checked into this project because it consists of - over 10,000 little files (for HTML and Latex), and it is easily + over 5,000 little files (for HTML with call graphs), and it is easily regenerated. For speed, the function call graphs are not enabled in the SVN version diff --git a/bacnet-stack/doc/output/BAC_stack.html b/bacnet-stack/doc/output/BAC_stack.html new file mode 100644 index 00000000..0182bfc8 --- /dev/null +++ b/bacnet-stack/doc/output/BAC_stack.html @@ -0,0 +1,16 @@ + + + + +BAC-stack + + + + + + <body> + <a href="html/main.html">Frames are disabled. Click here to go to the main page.</a> + </body> + + + diff --git a/bacnet-stack/include/cov.h b/bacnet-stack/include/cov.h index 90c0b58e..e89a32f8 100644 --- a/bacnet-stack/include/cov.h +++ b/bacnet-stack/include/cov.h @@ -126,4 +126,19 @@ extern "C" { #ifdef __cplusplus } #endif /* __cplusplus */ + +/** @defgroup DSCOV Data Sharing - Change of Value Service (DS-COV) + * @ingroup DataShare + * 13.1 Change of Value Reporting
+ * Change of value (COV) reporting allows a COV-client to subscribe with a + * COV-server, on a permanent or temporary basis, to receive reports of some + * changes of value of some referenced property based on fixed criteria. + * If an object provides COV reporting, then changes of value of any + * subscribed-to properties of the object, in some cases based on programmable + * increments, trigger COV notifications to be sent to subscribing clients. + * Typically, COV notifications are sent to supervisory programs in COV-client + * devices or to operators or logging devices. Any object, proprietary or + * standard, may support COV reporting at the implementor's option. + */ + #endif