diff --git a/bacnet-stack/demo/handler/h_dcc.c b/bacnet-stack/demo/handler/h_dcc.c
index e10a29fa..8354e5cc 100644
--- a/bacnet-stack/demo/handler/h_dcc.c
+++ b/bacnet-stack/demo/handler/h_dcc.c
@@ -42,6 +42,9 @@
static char My_Password[32] = "filister";
+/** Sets (non-volatile hold) the password to be used for DCC requests.
+ * @param new_password [in] The new DCC password, of up to 31 characters.
+ */
void handler_dcc_password_set(
char *new_password)
{
@@ -62,6 +65,26 @@ void handler_dcc_password_set(
}
}
+
+/** Handler for a Device Communication Control (DCC) request.
+ * @ingroup DMDCC
+ * 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
+ * - if not a known DCC state
+ * - an Error if the DCC password is incorrect
+ * - else tries to send a simple ACK for the DCC on success,
+ * and sets the DCC state requested.
+ *
+ * @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_device_communication_control(
uint8_t * service_request,
uint16_t service_len,
diff --git a/bacnet-stack/demo/handler/h_iam.c b/bacnet-stack/demo/handler/h_iam.c
index cbab378b..52f886a0 100644
--- a/bacnet-stack/demo/handler/h_iam.c
+++ b/bacnet-stack/demo/handler/h_iam.c
@@ -34,6 +34,13 @@
/** @file h_iam.c Handles I-Am requests. */
+/** Handler for I-Am responses.
+ * Will add the responder to our cache, or update its binding.
+ * @ingroup DMDDB
+ * @param service_request [in] The received message to be handled.
+ * @param service_len [in] Length of the service_request message.
+ * @param src [in] The BACNET_ADDRESS of the message's source.
+ */
void handler_i_am_add(
uint8_t * service_request,
uint16_t service_len,
@@ -68,6 +75,14 @@ void handler_i_am_add(
return;
}
+/** Handler for I-Am responses (older binding-update-only version).
+ * Will update the responder's binding, but if already in our cache.
+ * @note This handler is deprecated, in favor of handler_i_am_add().
+ *
+ * @param service_request [in] The received message to be handled.
+ * @param service_len [in] Length of the service_request message.
+ * @param src [in] The BACNET_ADDRESS of the message's source.
+ */
void handler_i_am_bind(
uint8_t * service_request,
uint16_t service_len,
diff --git a/bacnet-stack/demo/handler/h_rd.c b/bacnet-stack/demo/handler/h_rd.c
index f6974053..9709e5c9 100644
--- a/bacnet-stack/demo/handler/h_rd.c
+++ b/bacnet-stack/demo/handler/h_rd.c
@@ -42,6 +42,26 @@
/** @file h_rd.c Handles Reinitialize Device requests. */
+/** Handler for a Reinitialize Device (RD) request.
+ * @ingroup DMRD
+ * 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 Error if
+ * - the RD password is incorrect
+ * - the Reinitialize Device operation fails
+ * - a Reject if the request state is invalid
+ * - else tries to send a simple ACK for the RD on success.
+ *
+ * @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_reinitialize_device(
uint8_t * service_request,
uint16_t service_len,
diff --git a/bacnet-stack/demo/handler/h_whois.c b/bacnet-stack/demo/handler/h_whois.c
index 8565140c..c8e50bf8 100644
--- a/bacnet-stack/demo/handler/h_whois.c
+++ b/bacnet-stack/demo/handler/h_whois.c
@@ -39,7 +39,8 @@
/** @file h_whois.c Handles Who-Is requests. */
-/** Handler for Who-Is requests.
+/** Handler for Who-Is requests, with broadcast I-Am response.
+ * @ingroup DMDDB
* @param service_request [in] The received message to be handled.
* @param service_len [in] Length of the service_request message.
* @param src [in] The BACNET_ADDRESS of the message's source.
@@ -73,7 +74,8 @@ void handler_who_is(
return;
}
-/** Handler for Who-Is requests - Unicast (per Addendum 135-2004q).
+/** Handler for Who-Is requests, with Unicast I-Am response (per Addendum 135-2004q).
+ * @ingroup DMDDB
* @param service_request [in] The received message to be handled.
* @param service_len [in] Length of the service_request message.
* @param src [in] The BACNET_ADDRESS of the message's source.
diff --git a/bacnet-stack/demo/handler/s_dcc.c b/bacnet-stack/demo/handler/s_dcc.c
index d30ed91f..47118cc8 100644
--- a/bacnet-stack/demo/handler/s_dcc.c
+++ b/bacnet-stack/demo/handler/s_dcc.c
@@ -44,6 +44,17 @@
/** @file s_dcc.c Send a Device Communication Control (DCC) request. */
+/** Sends a Device Communication Control (DCC) request.
+ * @ingroup DMDCC
+ *
+ * @param device_id [in] The index to the device address in our address cache.
+ * @param timeDuration [in] If non-zero, the minutes that the remote device
+ * shall ignore all APDUs except DCC and, if supported, RD APDUs.
+ * @param state [in] Choice to Enable or Disable communication.
+ * @param password [in] Optional password, up to 20 chars.
+ * @return The invokeID of the transmitted message, or 0 on failure.
+ */
+
uint8_t Send_Device_Communication_Control_Request(
uint32_t device_id,
uint16_t timeDuration, /* 0=optional */
diff --git a/bacnet-stack/demo/handler/s_iam.c b/bacnet-stack/demo/handler/s_iam.c
index b0121b4e..fcb1108a 100644
--- a/bacnet-stack/demo/handler/s_iam.c
+++ b/bacnet-stack/demo/handler/s_iam.c
@@ -70,6 +70,8 @@ int iam_encode_pdu(
}
/** Broadcast an I Am message.
+ * @ingroup DMDDB
+ *
* @param buffer [in] The buffer to use for building and sending the message.
*/
void Send_I_Am(
@@ -104,10 +106,10 @@ void Send_I_Am(
}
/** Encode an I Am message to be unicast directly back to the src.
- * If the src address is not given, the dest address will be
- * a broadcast address.
+ *
* @param buffer [in,out] The buffer to use for building the message.
- * @param src [in] The source address information.
+ * @param src [in] The source address information. If the src address is not
+ * given, the dest address will be a broadcast address.
* @param dest [out] The destination address information.
* @param npdu_data [out] The NPDU structure describing the message.
* @return The length of the message in buffer[].
@@ -139,10 +141,12 @@ int iam_unicast_encode_pdu(
}
/** Send an I-Am message by unicasting directly back to the src.
+ * @ingroup DMDDB
* @note As of Addendum 135-2008q-1, unicast responses are allowed;
* in modern firewalled corporate networks, this may be the
* only type of response that will reach the source on
- * another subnet (without using the BBMD).
+ * another subnet (without using the BBMD).
+ * However, some BACnet routers may not correctly handle this message.
*
* @param buffer [in] The buffer to use for building and sending the message.
* @param src [in] The source address information from service handler.
diff --git a/bacnet-stack/demo/handler/s_rd.c b/bacnet-stack/demo/handler/s_rd.c
index b5069e20..42a5ff04 100644
--- a/bacnet-stack/demo/handler/s_rd.c
+++ b/bacnet-stack/demo/handler/s_rd.c
@@ -45,6 +45,14 @@
/** @file s_rd.c Send a Reinitialize Device request. */
+/** Sends a Reinitialize Device (RD) request.
+ * @ingroup DMRD
+ *
+ * @param device_id [in] The index to the device address in our address cache.
+ * @param state [in] Specifies the desired state of the device after reinitialization.
+ * @param password [in] Optional password, up to 20 chars.
+ * @return The invokeID of the transmitted message, or 0 on failure.
+ */
uint8_t Send_Reinitialize_Device_Request(
uint32_t device_id,
BACNET_REINITIALIZED_STATE state,
diff --git a/bacnet-stack/demo/handler/s_whois.c b/bacnet-stack/demo/handler/s_whois.c
index e0867bda..edcc4b7a 100644
--- a/bacnet-stack/demo/handler/s_whois.c
+++ b/bacnet-stack/demo/handler/s_whois.c
@@ -45,7 +45,15 @@
/** @file s_whois.c Send a Who-Is request. */
-/* find a specific device, or use -1 for limit if you want unlimited */
+/** Send a Who-Is request for a specific device, a range, or any device.
+ * @ingroup DMDDB
+ * If low_limit and high_limit both are -1, then the range is unlimited.
+ * If low_limit and high_limit have the same non-negative value, then only
+ * that device will respond.
+ * Otherwise, low_limit must be less than high_limit.
+ * @param low_limit [in] Device Instance Low Range, 0 - 4,194,303 or -1
+ * @param high_limit [in] Device Instance High Range, 0 - 4,194,303 or -1
+ */
void Send_WhoIs(
int32_t low_limit,
int32_t high_limit)
diff --git a/bacnet-stack/include/dcc.h b/bacnet-stack/include/dcc.h
index 448d07e5..11dec57b 100644
--- a/bacnet-stack/include/dcc.h
+++ b/bacnet-stack/include/dcc.h
@@ -97,4 +97,26 @@ extern "C" {
#ifdef __cplusplus
}
#endif /* __cplusplus */
+
+/** @defgroup RDMS Remote Device Management Services BIBBs
+ * These device management BIBBs prescribe the BACnet capabilities required
+ * to interoperably perform the device management functions enumerated in
+ * 22.2.1.5 for the BACnet devices defined therein.
+ */
+
+/** @defgroup DMDCC Device Management-Device Communication Control (DM-DCC)
+ * @ingroup RDMS
+ * 16.1 DeviceCommunicationControl Service
+ * The DeviceCommunicationControl service is used by a client BACnet-user to
+ * instruct a remote device to stop initiating and optionally stop responding
+ * to all APDUs (except DeviceCommunicationControl or, if supported,
+ * ReinitializeDevice) on the communication network or internetwork for a
+ * specified duration of time. This service is primarily used by a human operator
+ * for diagnostic purposes. A password may be required from the client
+ * BACnet-user prior to executing the service. The time duration may be set to
+ * "indefinite," meaning communication must be re-enabled by a
+ * DeviceCommunicationControl or, if supported, ReinitializeDevice service,
+ * not by time.
+ */
+
#endif
diff --git a/bacnet-stack/include/rd.h b/bacnet-stack/include/rd.h
index eb893f93..521774e6 100644
--- a/bacnet-stack/include/rd.h
+++ b/bacnet-stack/include/rd.h
@@ -83,4 +83,20 @@ extern "C" {
#ifdef __cplusplus
}
#endif /* __cplusplus */
+
+/** @defgroup DMRD Device Management-ReinitializeDevice (DM-RD)
+ * @ingroup RDMS
+ * 16.4 ReinitializeDevice Service
+ * The ReinitializeDevice service is used by a client BACnet-user to instruct
+ * a remote device to reboot itself (cold start), reset itself to some
+ * predefined initial state (warm start), or to control the backup or restore
+ * procedure. Resetting or rebooting a device is primarily initiated by a human
+ * operator for diagnostic purposes. Use of this service during the backup or
+ * restore procedure is usually initiated on behalf of the user by the device
+ * controlling the backup or restore. Due to the sensitive nature of this
+ * service, a password may be required from the responding BACnet-user prior
+ * to executing the service.
+ *
+ */
+
#endif
diff --git a/bacnet-stack/include/whois.h b/bacnet-stack/include/whois.h
index d5f4ca0e..eeb5d407 100644
--- a/bacnet-stack/include/whois.h
+++ b/bacnet-stack/include/whois.h
@@ -67,4 +67,25 @@ extern "C" {
#ifdef __cplusplus
}
#endif /* __cplusplus */
+
+/** @defgroup DMDDB Device Management-Dynamic Device Binding (DM-DDB)
+ * @ingroup RDMS
+ * 16.10 Who-Is and I-Am Services
+ * The Who-Is service is used by a sending BACnet-user to determine the device
+ * object identifier, the network address, or both, of other BACnet devices
+ * that share the same internetwork.
+ * The Who-Is service is an unconfirmed service. The Who-Is service may be used
+ * to determine the device object identifier and network addresses of all devices
+ * on the network, or to determine the network address of a specific device whose
+ * device object identifier is known, but whose address is not.
+ * The I-Am service is also an unconfirmed service. The I-Am service is used to
+ * respond to Who-Is service requests. However, the I-Am service request may be
+ * issued at any time. It does not need to be preceded by the receipt of a
+ * Who-Is service request. In particular, a device may wish to broadcast an I-Am
+ * service request when it powers up. The network address is derived either
+ * from the MAC address associated with the I-Am service request, if the device
+ * issuing the request is on the local network, or from the NPCI if the device
+ * is on a remote network.
+ */
+
#endif