Added some javadoc-type function comments.

Reduced the default hop count from way-big 255 to 15.

bacnet-stack/demo/handler/h_npdu.c

@@ -40,6 +40,26 @@
 
 /** @file h_npdu.c  Handles messages at the NPDU level of the BACnet stack. */
 
+/** Handler for the NPDU portion of a received packet.
+ *  Aside from error-checking, if the NPDU doesn't contain routing info,
+ *  this handler doesn't do much besides stepping over the NPDU header
+ *  and passing the remaining bytes to the apdu_handler.
+ *  @note The routing (except src) and NCPI information, including 
+ *  npdu_data->data_expecting_reply, are discarded.
+ *  
+ * @param src  [out] Returned with routing source information if the NPDU 
+ *                   has any and if this points to non-null storage for it. 
+ *                   If src->net and src->len are 0 on return, 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, and this
+ *                   is passed down into the apdu_handler; however, I don't 
+ *                   think this project's code has any use for the src info  
+ *                   on return from this handler, since the response has 
+ *                   already been sent via the apdu_handler.
+ *  @param pdu [in]  Buffer containing the NPDU and APDU of the received packet.
+ *  @param pdu_len [in] The size of the received message in the pdu[] buffer.
+ */
 void npdu_handler(
     BACNET_ADDRESS * src,       /* source address */
     uint8_t * pdu,      /* PDU data */

bacnet-stack/demo/handler/s_router.c

@@ -56,7 +56,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 = 255;
+        npdu_data->hop_count = 15;		/* Set a generous but reasonable upper bound */
     }
 }
 
@@ -101,8 +101,10 @@ void Send_Who_Is_Router_To_Network(
 #endif
 }
 
-/* pDNET_list: list of networks for which I am a router,
+/** Broadcast an I-am-router-to-network message, giving the list of networks we can reach.
-   terminated with -1 */
+ * The message will be sent to our normal DataLink Layer interface, not the routed backend.
+ * @param DNET_list [in] list of BACnet network numbers for which I am a router, terminated with -1
+ */
 void Send_I_Am_Router_To_Network(
     const int DNET_list[])
 {
@@ -121,7 +123,7 @@ void Send_I_Am_Router_To_Network(
         npdu_encode_pdu(&Handler_Transmit_Buffer[0], NULL, NULL, &npdu_data);
     /* encode the optional DNET list portion of the packet */
 #if PRINT_ENABLED
-    fprintf(stderr, "Send I-Am-Router-To-Network message to:\n");
+    fprintf(stderr, "Sending I-Am-Router-To-Network message for networks:\n");
 #endif
     while (DNET_list[index] != -1) {
         dnet = (uint16_t) DNET_list[index];
@@ -129,7 +131,7 @@ void Send_I_Am_Router_To_Network(
         pdu_len += len;
         index++;
 #if PRINT_ENABLED
-        fprintf(stderr, "%u\n", dnet);
+        fprintf(stderr, "  %u\n", dnet);
 #endif
     }
     /* I-Am-Router-To-Network shall always be transmitted with

bacnet-stack/src/npdu.c

@@ -178,7 +178,7 @@ int npdu_encode_pdu(
         /* destined for a remote network, i.e., if DNET is present. */
         /* This is a one-octet field that is initialized to a value of 0xff. */
         if (dest && dest->net) {
-            npdu[len] = npdu_data->hop_count;
+            npdu[len] = npdu_data->hop_count -1;
             len++;
         }
         if (npdu_data->network_layer_message) {
@@ -243,6 +243,27 @@ void npdu_encode_npdu_data(
     }
 }
 
+/** Decode the NPDU portion of a received message, particularly the NCPI byte.
+ *  The Network Layer Protocol Control Information byte is described 
+ *  in section 6.2.2 of the BACnet standard.
+ * @param npdu [in] Buffer holding the received NPDU header bytes (must be at least 2)
+ * @param dest [out] Returned with routing destination information if the NPDU 
+ *                   has any and if this points to non-null storage for it. 
+ *                   If dest->net and dest->len are 0 on return, there is no
+ *                   routing destination information.
+ * @param src  [out] Returned with routing source information if the NPDU 
+ *                   has any and if this points to non-null storage for it. 
+ *                   If src->net and src->len are 0 on return, 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 [out] Returns a filled-out structure with information
+ * 					 decoded from the NCPI and other NPDU bytes.
+ * @return On success, returns the number of bytes which were decoded from the 
+ * 		   NPDU section; if this is a  network layer message, there may be more
+ *         bytes left in the NPDU; if not a network msg, the APDU follows.
+ *         If 0 or negative, there were problems with the data or arguments.
+ */
 int npdu_decode(
     uint8_t * npdu,
     BACNET_ADDRESS * dest,
@@ -370,7 +391,8 @@ int npdu_decode(
             if (npdu_data->network_message_type >= 0x80)
                 len += decode_unsigned16(&npdu[len], &npdu_data->vendor_id);
         } else {
-            /* FIXME: another value for this? */
+            /* Since npdu_data->network_layer_message is false,
+             * it doesn't much matter what we set here; this is safe: */
             npdu_data->network_message_type = NETWORK_MESSAGE_INVALID;
         }
     }