diff --git a/bacnet-stack/BACnet-stack.doxyfile b/bacnet-stack/BACnet-stack.doxyfile
index bfa46a29..94325096 100644
--- a/bacnet-stack/BACnet-stack.doxyfile
+++ b/bacnet-stack/BACnet-stack.doxyfile
@@ -271,7 +271,7 @@ EXTRACT_PRIVATE = YES
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
-EXTRACT_STATIC = YES
+EXTRACT_STATIC = NO
# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
# defined locally in source files will be included in the documentation.
@@ -506,7 +506,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = include src demo/server ports/linux demo/handler demo/object
+INPUT = include src demo/server ports/linux demo/handler demo/object
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -1108,7 +1108,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED =
+PREDEFINED = FOR_DOXYGEN
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/bacnet-stack/include/bip.h b/bacnet-stack/include/bip.h
index fb04e953..542cdc3e 100644
--- a/bacnet-stack/include/bip.h
+++ b/bacnet-stack/include/bip.h
@@ -122,4 +122,14 @@ extern "C" {
#ifdef __cplusplus
}
#endif /* __cplusplus */
+
+/** @defgroup DLBIP BACnet/IP DataLink Network Layer
+ * @ingroup DataLink
+ * Implementation of the Network Layer using BACnet/IP as the transport, as
+ * described in Annex J.
+ * The functions described here fulfill the roles defined generically at the
+ * DataLink level by serving as the implementation of the function templates.
+ *
+ */
+
#endif
diff --git a/bacnet-stack/include/datalink.h b/bacnet-stack/include/datalink.h
index dc7926f1..bca2f574 100644
--- a/bacnet-stack/include/datalink.h
+++ b/bacnet-stack/include/datalink.h
@@ -83,7 +83,7 @@
#define datalink_get_broadcast_address bip_get_broadcast_address
#define datalink_get_my_address bip_get_my_address
-#else
+#else /* Ie, BACDL_ALL */
#include "npdu.h"
#define MAX_HEADER (8)
@@ -118,4 +118,35 @@ extern "C" {
}
#endif /* __cplusplus */
#endif
+
+/** @defgroup DataLink The BACnet Network (DataLink) Layer
+ * 6 THE NETWORK LAYER
+ * The purpose of the BACnet network layer is to provide the means by which
+ * messages can be relayed from one BACnet network to another, regardless of
+ * the BACnet data link technology in use on that network. Whereas the data
+ * link layer provides the capability to address messages to a single device
+ * or broadcast them to all devices on the local network, the network layer
+ * allows messages to be directed to a single remote device, broadcast on a
+ * remote network, or broadcast globally to all devices on all networks.
+ * A BACnet Device is uniquely located by a network number and a MAC address.
+ *
+ * Each client or server application must define exactly one of these
+ * DataLink settings, which will control which parts of the code will be built:
+ * - BACDL_ETHERNET -- for Clause 7 ISO 8802-3 ("Ethernet") LAN
+ * - BACDL_ARCNET -- for Clause 8 ARCNET LAN
+ * - BACDL_MSTP -- for Clause 9 MASTER-SLAVE/TOKEN PASSING (MS/TP) LAN
+ * - BACDL_BIP -- for ANNEX J - BACnet/IP
+ * - BACDL_ALL -- Unspecified for the build, so the transport can be
+ * chosen at runtime from among these choices.
+ * - Clause 10 POINT-TO-POINT (PTP) and Clause 11 EIA/CEA-709.1 ("LonTalk") LAN
+ * are not currently supported by this project.
+ */
+
+/** @defgroup DLTemplates DataLink Template Functions
+ * @ingroup DataLink
+ * Most of the functions in this group are function templates which are assigned
+ * to a specific DataLink network layer implementation either at compile time or
+ * at runtime.
+ */
+
#endif
diff --git a/bacnet-stack/ports/linux/bip-init.c b/bacnet-stack/ports/linux/bip-init.c
index 2aad427c..5d94e63e 100644
--- a/bacnet-stack/ports/linux/bip-init.c
+++ b/bacnet-stack/ports/linux/bip-init.c
@@ -96,7 +96,12 @@ static int get_local_address_ioctl(
return rv;
}
-/* on Linux, ifname is eth0, ath0, arc0, and others. */
+/** Gets the local IP address and local broadcast address from the system,
+ * and saves it into the BACnet/IP data structures.
+ *
+ * @param ifname [in] The named interface to use for the network layer.
+ * Eg, for Linux, ifname is eth0, ath0, arc0, and others.
+ */
static void bip_set_interface(
char *ifname)
{
@@ -128,6 +133,24 @@ static void bip_set_interface(
}
}
+/** Initialize the BACnet/IP services at the given interface.
+ * @ingroup DLBIP
+ * -# Gets the local IP address and local broadcast address from the system,
+ * and saves it into the BACnet/IP data structures.
+ * -# Opens a UDP socket
+ * -# Configures the socket for sending and receiving
+ * -# Configures the socket so it can send broadcasts
+ * -# Binds the socket to the local IP address at the specified port for
+ * BACnet/IP (by default, 0xBAC0 = 47808).
+ *
+ * @note For Linux, ifname is eth0, ath0, arc0, and others.
+ For Windows, ifname is the dotted ip address of the interface.
+
+ * @param ifname [in] The named interface to use for the network layer.
+ * If NULL, the "eth0" interface is assigned.
+ * @return True if the socket is successfully opened for BACnet/IP,
+ * else False if the socket functions fail.
+ */
bool bip_init(
char *ifname)
{
@@ -163,7 +186,7 @@ bool bip_init(
if (status < 0) {
close(sock_fd);
bip_set_socket(-1);
- return status;
+ return false;
}
/* bind the socket to the local port number and IP address */
sin.sin_family = AF_INET;
diff --git a/bacnet-stack/src/bip.c b/bacnet-stack/src/bip.c
index bdafce75..7cb6e092 100644
--- a/bacnet-stack/src/bip.c
+++ b/bacnet-stack/src/bip.c
@@ -52,12 +52,20 @@ static struct in_addr BIP_Address;
/* Broadcast Address - stored in host byte order */
static struct in_addr BIP_Broadcast_Address;
+/** Setter for the BACnet/IP socket handle.
+ *
+ * @param sock_fd [in] Handle for the BACnet/IP socket.
+ */
void bip_set_socket(
int sock_fd)
{
BIP_Socket = sock_fd;
}
+/** Getter for the BACnet/IP socket handle.
+ *
+ * @return The handle to the BACnet/IP socket.
+ */
int bip_socket(
void)
{
@@ -70,6 +78,9 @@ bool bip_valid(
return (BIP_Socket != -1);
}
+/** Cleanup and close out the BACnet/IP services by closing the socket.
+ * @ingroup DLBIP
+ */
void bip_cleanup(
void)
{
@@ -140,8 +151,15 @@ static int bip_decode_bip_address(
return len;
}
-/* function to send a packet out the BACnet/IP socket (Annex J) */
-/* returns number of bytes sent on success, negative number on failure */
+/** Function to send a packet out the BACnet/IP socket (Annex J).
+ * @ingroup DLBIP
+ *
+ * @param dest [in] Destination address (may encode an IP address and port #).
+ * @param npdu_data [in] The NPDU header (Network) information (not used).
+ * @param pdu [in] Buffer of data to be sent - may be null (why?).
+ * @param pdu_len [in] Number of bytes in the pdu buffer.
+ * @return Number of bytes sent on success, negative number on failure.
+ */
int bip_send_pdu(
BACNET_ADDRESS * dest, /* destination address */
BACNET_NPDU_DATA * npdu_data, /* network information */
diff --git a/bacnet-stack/src/datalink.c b/bacnet-stack/src/datalink.c
index 7a8a681a..108d70e8 100644
--- a/bacnet-stack/src/datalink.c
+++ b/bacnet-stack/src/datalink.c
@@ -36,10 +36,30 @@
/** @file datalink.c Optional run-time assignment of datalink transport */
-#if defined(BACDL_ALL)
+#if defined(BACDL_ALL) || defined FOR_DOXYGEN
/* Function pointers - point to your datalink */
+
+/** Function template to Initialize the DataLink services at the given interface.
+ * @ingroup DLTemplates
+ *
+ * @note For Linux, ifname is eth0, ath0, arc0, ttyS0, and others.
+ For Windows, ifname is the COM port or dotted ip address of the interface.
+
+ * @param ifname [in] The named interface to use for the network layer.
+ * @return True if the interface is successfully initialized,
+ * else False if the initialization fails.
+ */
bool(*datalink_init) (char *ifname);
+/** Function template to send a packet via the DataLink.
+ * @ingroup DLTemplates
+ *
+ * @param dest [in] Destination address.
+ * @param npdu_data [in] The NPDU header (Network) information.
+ * @param pdu [in] Buffer of data to be sent - may be null.
+ * @param pdu_len [in] Number of bytes in the pdu buffer.
+ * @return Number of bytes sent on success, negative number on failure.
+ */
int (
*datalink_send_pdu) (
BACNET_ADDRESS * dest,
@@ -50,6 +70,9 @@ int (
uint16_t(*datalink_receive) (BACNET_ADDRESS * src, uint8_t * pdu,
uint16_t max_pdu, unsigned timeout);
+/** Function template to close the DataLink services and perform any cleanup.
+ * @ingroup DLTemplates
+ */
void (
*datalink_cleanup) (
void);