Libraries

Alerts

Description

This library facilitates the handling of alarms and warnings and supports you in generating them. It also generates the data records that must be sent to the server in order to subsequently inform users about the problem (e.g. via SMS)

It offers the following features:

Function to check whether an alarm or warning for a specific measured value needs to be triggered or reset
Function to reset all alarms and warnings for a specific measured value
Function to trigger or reset a technical fault warning for a specific measured value
Function to trigger or reset a technical fault alarm for a specific measured value

OVERVIEW

alerts_Abstract:

The library does not trigger a server connection if a data record was created. To trigger a server connection use uplinkFlush().

The libary offers the following features:

Function to check whether an alarm or warning for a specific measured value needs to be triggered or reset

Function to reset all alarms and warnings for a specific measured value

Function to trigger or reset a technical fault warning for a specific measured value

Function to trigger or reset a technical fault alarm for a specific measured value

Migration Guide V1 to V2

Functions:

Migrating from "V1" to "V2"

Search your project for all calls to Alerts_CheckAlarm_f32() and replace these calls with the Alerts_CheckAlarm_hyst_perc_f32() function.

// alerts-microtronics V1: Alerts_CheckAlarm_f32(iState, iHistdataID, iField, fValue, fAlertHigh, fWarningHigh, fAlertLow, fWarningLow, fHyst) | V // alerts-microtronics V2: Alerts_CheckAlarm_hyst_perc_f32(iState, iHistdataID, iField, fValue, fAlertHigh, fWarningHigh, fAlertLow, fWarningLow, fHyst)

Detailed Explanation

With version 1 of the library, the "fHysteresis" parameter of Alerts_CheckAlarm_f32() was interpreted as a percent value. This is useful for applications, that want to support different types of input signals (e.g. mm, °C , liters,... ) for the same measurement channel. An example of this would be universal data loggers. But it makes the function more difficult to apply correctly, because the width of the hysteresis (as an absolute value) is calculated for each of the 4 thresholds (Alarm high, Warning high, Warning low and Alarm low) individually and therefore varies depending on the height of the threshold (e.g. hyst = 5%, warning at 10 -> all-clear at 9,5 --> hyst as an absolute value = 0,5; hyst = 5%, alarm at 100 -> all-clear at 95 --> hyst as an absolute value = 5).

Furthermore, an alert was reset, if the measurement value fell below or equal to the threshold minus the hysteresis. This meant the function was not suitable for digital measurements, because with a hysteresis of less than 100%, the threshold for triggering the alarm was equal to the threshold for resetting the alarm (e.g. hyst = 5%, alarm at 1 -> all-clear at 0.95 rounded 1 because there are no decimal places in digital mode). This means that the warning/alarm would be permanently triggered and reset (alarm at >=1, all-clear at <= 1).

With version 2 of the library the "fHysteresis" parameter of Alerts_CheckAlarm_f32() is interpreted as an absolute value. This makes the function easier to apply correctly, since the width of the hysteresis stays the same for each threshold.

Furthermore, an alert is now reset, if the measurement value falls below the threshold minus the hysteresis. This means the function is now suitable for digital measurements. (alarm at >=1, all-clear at < 1).

BASIC

ALERTS_ERROR_x:

Alert library Errors Codes

ALERTS_ERROR_CHANNEL_ID = (-1) - An invalid Histdata channel ID was provided. (Valid: 0-9 or autogenerated 'DDE_x_id' defines)

ALERTS_ERROR_FIELD_ID = (-2) - An invalid field ID was provided. (Valid: 0-999)

ALERTS_ERROR_VALUE_NAN = (-3) - An NAN value was provided

ALERTS_ERROR_THRESHOLD_ORDER = (-4) - The alert thresholds were configured in an incorrect order.

Correct order, from lowest value to highest value: AlertLow -> WarningLow -> WarningHigh -> AlertHigh

ALERTS_ERROR_HYSTERESIS = (-5) - A negative Hysteresis was provided (Valid >= 0)

ALERTS_ERROR_RECORD_FAILED = (-6) - Failed to record the alert data record. Call the Alerts_CheckAlarm_f32() function again later. If this error occurs frequently, you have chosen the size of the "Record Queue" too small (see record-queue and rM2M_RecDataQ_BUFFER_BYTES).

ALERTS_ERROR_2nd_RECORD_FAILED = (-7) - Failed to record the alarm data record, but successfully recorded the warning data record, during a violation of warning and alarm thresholds at the same time. Call the Alerts_CheckAlarm_f32() function again later. If this error occurs frequently, you have chosen the size of the "Record Queue" too small (see record-queue and rM2M_RecDataQ_BUFFER_BYTES).

Alerts_CheckAlarm_f32(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThresholdAlertHigh=F32_NAN, Float:fThresholdWarningHigh=F32_NAN, Float:fThresholdAlertLow=F32_NAN, Float:fThresholdWarningLow=F32_NAN, Float:fHysteresis=5.0)

Checks for the transferred measurement value whether an alarm or warning has to be triggered or reset (fHysteresis interpreted as absolute value).

The function checks whether the transferred measurement value violated one of the thresholds. iAlertState is used to detect changes of the state of alert compared to the previous call to the function. During the first call of the function and if no other Alerts_x function was called previously, the function will create an alert data record for the current detected state. This is done since there is no previous state which could be used for comparison in this case.

Individual thresholds can be disabled using F32_NAN. An absolute hysteresis value of 5 will be used if not specified otherwise.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the transferred and to be checked measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the transferred and to be checked measurement value within the Histdata channel.

fCurrentValue : f32 - Measurement value to be checked

fThresholdAlertHigh : f32 - Alert high threshold. An alarm is triggered, if the measurement value meets or exceeds this value.

fThresholdWarningHigh : f32 - Warning high threshold. A warning is triggered, if the measurement value meets or exceeds this value.

fThresholdAlertLow : f32 - Alert low threshold. An alarm is triggered, if the measurement value drops to or below this value.

fThresholdWarningLow : f32 - Warning low threshold. A warning is triggered, if the measurement value drops to or below this value.

fHysteresis : f32 - Hysteresis (as an absolute value) for all-clear in event of alarm/warning (e.g. fHysteresis = 5, alarm or warning at >=100 -> all-clear at < 95)

returns : s32

ALERTS_OK_NO_CHANGE - No change was detected (see ALERTS_OK_x)

ALERTS_OK_CHANGED - A change was detected and recorded (see ALERTS_OK_x)

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_VALUE_NAN - fCurrentValue is NAN (see ALERTS_ERROR_x)

ALERTS_ERROR_THRESHOLD_ORDER - Invalid threshold order (see ALERTS_ERROR_x)

ALERTS_ERROR_HYSTERESIS - Invalid hysteresis (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the alert data record (see ALERTS_ERROR_x)

ALERTS_ERROR_2nd_RECORD_FAILED - Failed to record the alarm data record, but successfully recorded the warning data record (see ALERTS_ERROR_x)

Alerts_ClearAlarm(&iAlertState, iHistdataID, iField)

Clears all active set alarms and warnings (including technical fault warning and technical fault alarm) for a measurement value of a Histdata channel.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the desired measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the desired measurement value within the Histdata channel.

returns : s32

OK - if successful

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the "alerts cleared" data record (see ALERTS_ERROR_x)

Alerts_SetFaultAlarm(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThreshold)

Sets a technical fault alarm for a measurement value of a Histdata channel.

The function can be used to create a "technical fault alarm" data record. Previous alerts remain intact.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the desired measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the desired measurement value within the Histdata channel.

fCurrentValue : f32 - Current measurement value

fThreshold : f32 - Threshold that was violated

returns : s32

OK - if successful

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the "technical fault alarm" data record (see ALERTS_ERROR_x)

Alerts_ClearFaultAlarm(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThreshold)

Clears a technical fault alarm for a measurement value of a Histdata channel.

The function can be used to create a "technical fault alarm cleared" data record. Other alerts are not effected by this function.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the desired measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the desired measurement value within the Histdata channel.

fCurrentValue : f32 - Current measurement value

fThreshold : f32 - Threshold that was undershooted

returns : s32

OK - if successful

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the "technical fault alarm cleared" data record (see ALERTS_ERROR_x)

Alerts_SetFaultWarning(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThreshold)

Sets a technical fault warning for a measurement value of a Histdata channel.

The function can be used to create a "technical fault warning" data record. Previous alerts remain intact.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the desired measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the desired measurement value within the Histdata channel.

fCurrentValue : f32 - Current measurement value

fThreshold : f32 - Threshold that was violated

returns : s32

OK - if successful

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the "technical fault warning" data record (see ALERTS_ERROR_x)

Alerts_ClearFaultWarning(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThreshold)

Clears a technical fault warning for a measurement value of a Histdata channel.

The function can be used to create a "technical fault warning cleared" data record. Other alerts are not effected by this function.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the desired measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the desired measurement value within the Histdata channel.

fCurrentValue : f32 - Current measurement value

fThreshold : f32 - Threshold that was undershooted

returns : s32

OK - if successful

ALERTS_ERROR_CHANNEL_ID - Invalid Histdata channel ID (see ALERTS_ERROR_x)

ALERTS_ERROR_FIELD_ID - Invalid field ID (see ALERTS_ERROR_x)

ALERTS_ERROR_RECORD_FAILED - Failed to record the "technical fault warning cleared" data record (see ALERTS_ERROR_x)

EXPERT

Advanced Config:

The settings mentioned in this chapter should only be changed if really required (e.g. for testing purposes). To adapt the settings add the following macro to the main.dde file.

/** ---------------------------------------------------------------------------- * alerts-microtronics: Advanced Config * ----------------------------------------------------------------------------- * * Use this macro to adapt the advanced configuration settings: * */ #define ALERTS_DISABLE_ALERT_RECORDS 1 // Disables all data recording functions of the library

Alerts_CheckAlarm_hyst_perc_f32(&iAlertState, iHistdataID, iField, Float:fCurrentValue, Float:fThresholdAlertHigh=F32_NAN, Float:fThresholdWarningHigh=F32_NAN, Float:fThresholdAlertLow=F32_NAN, Float:fThresholdWarningLow=F32_NAN, Float:fHysteresis=5.0)

Checks for the transferred measurement value whether an alarm or warning has to be triggered or reset (fHysteresis interpreted as percent value).

Individual thresholds can be disabled using F32_NAN. A hysteresis of 5% will be used if not specified otherwise.

iAlertState : s32 - Variable in which the library stores the current state of alert and the previous state of alert.

This variable must not be modified directly by the user program and must be persistent (i.e. static or global variable). A separate variable is required for each measurement value.

iHistdataID : s32 - ID of the Histdata Channel (0-9 or autogenerated 'DDE_x_id' defines) to which the transferred and to be checked measurement value is assigned.

iField : s32 - Field ID (0-999). Corresponds to the position of the transferred and to be checked measurement value within the Histdata channel.

fCurrentValue : f32 - Measurement value to be checked

fThresholdAlertHigh : f32 - Alert high threshold. An alarm is triggered, if the measurement value meets or exceeds this value.

fThresholdWarningHigh : f32 - Warning high threshold. A warning is triggered, if the measurement value meets or exceeds this value.

fThresholdAlertLow : f32 - Alert low threshold. An alarm is triggered, if the measurement value drops to or below this value.

fThresholdWarningLow : f32 - Warning low threshold. A warning is triggered, if the measurement value drops to or below this value.

fHysteresis : f32 - Hysteresis[%] for all-clear in event of alarm/warning (e.g. fHysteresis = 5%, alarm or warning at >=100 -> all-clear at < 95)

The width of the hysteresis (as an absolute value) is calculated for each of the 4 thresholds (Alarm high, Warning high, Warning low and Alarm low) individually and therefore varies depending on the height of the threshold (e.g. hyst = 5%, warning at 10 -> all-clear at 9,5 --> hyst as an absolute value = 0,5; hyst = 5%, alarm at 100 -> all-clear at 95 --> hyst as an absolute value = 5).