diff --git a/bacnet-stack/demo/handler/dlenv.c b/bacnet-stack/demo/handler/dlenv.c index f4c5bb2f..f163e5e9 100644 --- a/bacnet-stack/demo/handler/dlenv.c +++ b/bacnet-stack/demo/handler/dlenv.c @@ -37,6 +37,34 @@ /** @file dlenv.c Initialize the DataLink configuration. */ +/** Initialize the DataLink configuration from Environment variables, + * or else to defaults. + * @ingroup MISCHNDLR + * The items configured depend on which BACDL_ the code is built for, + * eg, BACDL_BIP. + * + * For most items, checks first for an environment variable, and, if + * found, uses that to set the item's value. Otherwise, will set + * to a default value. + * + * The Environment Variables, by BACDL_ type, are: + * - BACDL_ALL: (the general-purpose solution) + * - BACNET_DATALINK to set which BACDL_ type we are using. + * - (Any): + * - BACNET_APDU_TIMEOUT + * - BACNET_IFACE + * - BACDL_BIP: (BACnet/IP) + * - BACNET_IP_PORT + * - with BBMD_ENABLED also: + * - BACNET_BBMD_PORT + * - BACNET_BBMD_TIMETOLIVE + * - BACNET_BBMD_ADDRESS + * - BACDL_MSTP: (BACnet MS/TP) + * - BACNET_MAX_INFO_FRAMES + * - BACNET_MAX_MASTER + * - BACNET_MSTP_BAUD + * - BACNET_MSTP_MAC + */ void dlenv_init( void) { diff --git a/bacnet-stack/demo/handler/h_alarm_ack.c b/bacnet-stack/demo/handler/h_alarm_ack.c index 51d2c7d0..94a04a5a 100644 --- a/bacnet-stack/demo/handler/h_alarm_ack.c +++ b/bacnet-stack/demo/handler/h_alarm_ack.c @@ -39,6 +39,22 @@ /** @file h_alarm_ack.c Handles Alarm Acknowledgment. */ +/** Handler for an Alarm/Event Acknowledgement. + * @ingroup ALMACK + * 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 + * - Otherwise, sends a simple ACK + * + * @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_alarm_ack( uint8_t * service_request, uint16_t service_len, diff --git a/bacnet-stack/demo/handler/h_ucov.c b/bacnet-stack/demo/handler/h_ucov.c index 94f1f1cc..7a267216 100644 --- a/bacnet-stack/demo/handler/h_ucov.c +++ b/bacnet-stack/demo/handler/h_ucov.c @@ -44,8 +44,18 @@ /** @file h_ucov.c Handles Unconfirmed COV Notifications. */ -/* note: nothing is specified in BACnet about what to do with the - information received from Unconfirmed COV Notifications. */ +/* */ +/** Handler for an Unconfirmed COV Notification. + * @ingroup DSCOV + * Decodes the received list of Properties to update, + * and print them out with the subscription information. + * @note Nothing is specified in BACnet about what to do with the + * information received from Unconfirmed COV Notifications. + * + * @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 (unused) + */ void handler_ucov_notification( uint8_t * service_request, uint16_t service_len, diff --git a/bacnet-stack/demo/handler/noserv.c b/bacnet-stack/demo/handler/noserv.c index bf02c429..99c64c43 100644 --- a/bacnet-stack/demo/handler/noserv.c +++ b/bacnet-stack/demo/handler/noserv.c @@ -36,6 +36,17 @@ /** @file noserv.c Handles an unrecognized/unsupported service. */ +/** Handler to be invoked when a Service request is received for which no + * handler has been defined. + * @ingroup MISCHNDLR + * This handler builds a Reject response packet, and sends it. + * + * @param service_request [in] The contents of the service request (unused). + * @param service_len [in] The length of the service_request (unused). + * @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_unrecognized_service( uint8_t * service_request, uint16_t service_len, diff --git a/bacnet-stack/demo/handler/s_cevent.c b/bacnet-stack/demo/handler/s_cevent.c index e82e8364..662df472 100644 --- a/bacnet-stack/demo/handler/s_cevent.c +++ b/bacnet-stack/demo/handler/s_cevent.c @@ -36,7 +36,14 @@ /** @file s_cevent.c Send a ConfirmedEventNotification Request. */ -/* returns the invoke id, 0=unsuccessful */ +/** Sends an Confirmed Alarm/Event Notification. + * @ingroup EVNOTFCN + * + * @param device_id [in] ID of the destination device + * @param data [in] The information about the Event to be sent. + * @return invoke id of outgoing message, or 0 if communication is disabled, + * or no tsm slot is available. + */ uint8_t Send_CEvent_Notify( uint32_t device_id, BACNET_EVENT_NOTIFICATION_DATA * data) diff --git a/bacnet-stack/demo/handler/s_cov.c b/bacnet-stack/demo/handler/s_cov.c index be1cd625..941d3d27 100644 --- a/bacnet-stack/demo/handler/s_cov.c +++ b/bacnet-stack/demo/handler/s_cov.c @@ -64,6 +64,13 @@ int ucov_notify_encode_pdu( return pdu_len; } +/** Sends an Unconfirmed COV Notification. + * @ingroup DSCOV + * + * @param buffer [in,out] The buffer to build the message in for sending. + * @param cov_data [in] The COV update information to be encoded. + * @return Size of the message sent (bytes), or a negative value on error. + */ int Send_UCOV_Notify( uint8_t * buffer, BACNET_COV_DATA * cov_data) @@ -79,6 +86,14 @@ int Send_UCOV_Notify( return bytes_sent; } +/** Sends a COV Subscription request. + * @ingroup DSCOV + * + * @param device_id [in] ID of the destination device + * @param cov_data [in] The COV subscription information to be encoded. + * @return invoke id of outgoing message, or 0 if communication is disabled or + * no slot is available from the tsm for sending. + */ uint8_t Send_COV_Subscribe( uint32_t device_id, BACNET_SUBSCRIBE_COV_DATA * cov_data) diff --git a/bacnet-stack/demo/handler/s_uevent.c b/bacnet-stack/demo/handler/s_uevent.c index 4b372684..4c7b03ea 100644 --- a/bacnet-stack/demo/handler/s_uevent.c +++ b/bacnet-stack/demo/handler/s_uevent.c @@ -30,6 +30,14 @@ /** @file s_uevent.c Send an Unconfirmed Event Notification. */ +/** Sends an Unconfirmed Alarm/Event Notification. + * @ingroup EVNOTFCN + * + * @param buffer [in,out] The buffer to build the message in for sending. + * @param data [in] The information about the Event to be sent. + * @param dest [in] The destination address information (may be a broadcast). + * @return Size of the message sent (bytes), or a negative value on error. + */ int Send_UEvent_Notify( uint8_t * buffer, BACNET_EVENT_NOTIFICATION_DATA * data, diff --git a/bacnet-stack/include/event.h b/bacnet-stack/include/event.h index 644a5856..34a8e587 100644 --- a/bacnet-stack/include/event.h +++ b/bacnet-stack/include/event.h @@ -209,4 +209,42 @@ extern "C" { #ifdef __cplusplus } #endif /* __cplusplus */ + +/** @defgroup ALMEVNT Alarm and Event Management BIBBs + * These BIBBs prescribe the BACnet capabilities required to interoperably + * perform the alarm and event management functions enumerated in 22.2.1.2 + * for the BACnet devices defined therein. + */ + +/** @defgroup EVNOTFCN Alarm and Event-Notification (AE-N) + * @ingroup ALMEVNT + * 13.6 ConfirmedCOVNotification Service
+ * The ConfirmedCOVNotification service is used to notify subscribers about + * changes that may have occurred to the properties of a particular object. + * Subscriptions for COV notifications are made using the SubscribeCOV service + * or the SubscribeCOVProperty service. + * + * 13.7 UnconfirmedCOVNotification Service
+ * The UnconfirmedCOVNotification Service is used to notify subscribers about + * changes that may have occurred to the properties of a particular object, + * or to distribute object properties of wide interest (such as outside air + * conditions) to many devices simultaneously without a subscription. + * Subscriptions for COV notifications are made using the SubscribeCOV service. + * For unsubscribed notifications, the algorithm for determining when to issue + * this service is a local matter and may be based on a change of value, + * periodic updating, or some other criteria. + */ + +/** @defgroup ALMACK Alarm and Event-ACK (AE-ACK) + * @ingroup ALMEVNT + * 13.5 AcknowledgeAlarm Service
+ * In some systems a device may need to know that an operator has seen the alarm + * notification. The AcknowledgeAlarm service is used by a notification-client + * to acknowledge that a human operator has seen and responded to an event + * notification with 'AckRequired' = TRUE. Ensuring that the acknowledgment + * actually comes from a person with appropriate authority is a local matter. + * This service may be used in conjunction with either the + * ConfirmedEventNotification service or the UnconfirmedEventNotification service. + */ + #endif /* BACNET_EVENT_H_ */ diff --git a/bacnet-stack/include/handlers.h b/bacnet-stack/include/handlers.h index 5f8f96ec..f1db7e53 100644 --- a/bacnet-stack/include/handlers.h +++ b/bacnet-stack/include/handlers.h @@ -250,4 +250,10 @@ extern "C" { #ifdef __cplusplus } #endif /* __cplusplus */ + +/** @defgroup MISCHNDLR Miscellaneous Handler Utilities + * Various utilities and functions to support the Handlers. + */ + + #endif