More function documentation.

Defined a default Hop Count value, and used 15 instead of 255.

bacnet-stack/demo/handler/s_router.c

@@ -41,8 +41,21 @@
 #include "txbuf.h"
 #include "client.h"
 
-/** @file s_router.c  Send BACnet Router requests. */
+/** @file s_router.c  Methods to send various BACnet Router Network Layer Messages. */
 
+/** Initialize an npdu_data structure with given parameters and good defaults,
+ * and add the Network Layer Message fields.
+ * The name is a misnomer, as it doesn't do any actual encoding here.
+ * @see npdu_encode_npdu_data for a simpler version to use when sending an
+ *           APDU instead of a Network Layer Message.
+ * 
+ * @param npdu_data [out] Returns a filled-out structure with information
+ * 					 provided by the other arguments and good defaults.
+ * @param network_message_type [in] The type of Network Layer Message.
+ * @param data_expecting_reply [in] True if message should have a reply.
+ * @param priority [in] One of the 4 priorities defined in section 6.2.2,
+ *                      like B'11' = Life Safety message
+ */
 static void npdu_encode_npdu_network(
     BACNET_NPDU_DATA * npdu_data,
     BACNET_NETWORK_MESSAGE_TYPE network_message_type,
@@ -56,7 +69,7 @@ static void npdu_encode_npdu_network(
         npdu_data->network_message_type = network_message_type; /* optional */
         npdu_data->vendor_id = 0;       /* optional, if net message type is > 0x80 */
         npdu_data->priority = priority;
-        npdu_data->hop_count = 15;		/* Set a generous but reasonable upper bound */
+        npdu_data->hop_count = DFLT_HOP_COUNT;		
     }
 }
 

bacnet-stack/include/npdu.h

@@ -39,6 +39,9 @@
 #include "bacdef.h"
 #include "bacenum.h"
 
+/** Use a hop count default that is generous but reasonable. */
+#define DFLT_HOP_COUNT 15
+
 /* an NPDU structure keeps the parameter stack to a minimum */
 typedef struct bacnet_npdu_data_t {
     uint8_t protocol_version;
@@ -52,14 +55,17 @@ typedef struct bacnet_npdu_data_t {
     uint8_t hop_count;
 } BACNET_NPDU_DATA;
 
-/* Port Info structure used by Routers */
 struct router_port_t;
+/** The info[] string has no agreed-upon purpose, hence it is useless. 
+ * Keeping it short here. This size could be 0-255. */
+#define ROUTER_PORT_INFO_LEN 2
+/** Port Info structure used by Routers for their routing table. */
 typedef struct router_port_t {
-    uint16_t dnet;
+    uint16_t dnet;		/**< The DNET number that identifies this port. */
-    uint8_t id;
+    uint8_t id;			/**< Either 0 or some ill-defined, meaningless value. */
-    uint8_t info[256];  /* size could be 1-255 */
+    uint8_t info[ROUTER_PORT_INFO_LEN];  /**< Info like 'modem dialing string' */
-    uint8_t info_len;
+    uint8_t info_len;	/**< Length of info[]. */
-    struct router_port_t *next; /* linked list */
+    struct router_port_t *next; 	/**< Point to next in linked list */
 } BACNET_ROUTER_PORT;
 
 #ifdef __cplusplus

bacnet-stack/src/npdu.c

@@ -43,6 +43,10 @@
 
 /** @file npdu.c  Encode/Decode NPDUs - Network Protocol Data Units */
 
+/** Copy the npdu_data structure information from src to dest.
+ * @param dest [out] The 'to' structure
+ * @param src   [in] The 'from' structure 
+ */
 void npdu_copy_data(
     BACNET_NPDU_DATA * dest,
     BACNET_NPDU_DATA * src)
@@ -98,6 +102,33 @@ ABORT.request                  Yes          No         Yes        No
 ABORT.indication               Yes         Yes         Yes        No
 */
 
+
+/** Encode the NPDU portion of a message to be sent, based on the npdu_data
+ *  and associated data.
+ *  If this is to be a Network Layer Control Message, there are probably
+ *  more bytes which will need to be encoded following the ones encoded here.
+ *  The Network Layer Protocol Control Information byte is described 
+ *  in section 6.2.2 of the BACnet standard.
+ * @param npdu [out] Buffer which will hold the encoded NPDU header bytes.
+ * 					 The size isn't given, but it must be at least 2 bytes
+ *                   for the simplest case, and should always be at least 24
+ *                   bytes to accommodate the maximal case (all fields loaded).
+ * @param dest [in] The routing destination information if the message must
+ *                   be routed to reach its destination. 
+ *                   If dest->net and dest->len are 0, there is no
+ *                   routing destination information.
+ * @param src  [in] The routing source information if the message was routed
+ *                   from another BACnet network.
+ *                   If src->net and src->len are 0, there is no
+ *                   routing source information.
+ *                   This src describes the original source of the message when
+ *                   it had to be routed to reach this BACnet Device.
+ * @param npdu_data [in] The structure which describes how the NCPI and other 
+ *                   NPDU bytes should be encoded.
+ * @return On success, returns the number of bytes which were encoded into the 
+ * 		   NPDU section.
+ *         If 0 or negative, there were problems with the data or encoding.
+ */
 int npdu_encode_pdu(
     uint8_t * npdu,
     BACNET_ADDRESS * dest,
@@ -227,6 +258,17 @@ described in 6.2.2.
 whether (TRUE) or not (FALSE) a reply service primitive
 is expected for the service being issued.
 */
+
+/** Initialize an npdu_data structure to good defaults.
+ * The name is a misnomer, as it doesn't do any actual encoding here.
+ * @see npdu_encode_npdu_network if you need to set a network layer msg.
+ * 
+ * @param npdu_data [out] Returns a filled-out structure with information
+ * 					 provided by the other arguments and good defaults.
+ * @param data_expecting_reply [in] True if message should have a reply.
+ * @param priority [in] One of the 4 priorities defined in section 6.2.2,
+ *                      like B'11' = Life Safety message
+ */
 void npdu_encode_npdu_data(
     BACNET_NPDU_DATA * npdu_data,
     bool data_expecting_reply,
@@ -239,7 +281,7 @@ void npdu_encode_npdu_data(
         npdu_data->network_message_type = NETWORK_MESSAGE_INVALID;      /* optional */
         npdu_data->vendor_id = 0;       /* optional, if net message type is > 0x80 */
         npdu_data->priority = priority;
-        npdu_data->hop_count = 255;
+        npdu_data->hop_count = DFLT_HOP_COUNT;
     }
 }