The “overall” alarm threshold is used to calculate alarm status for scalar DATA_POINT measurements on measurement points, where inspection point uses QUESTION_ANSWERS measurements.
The type of threshold type field sets which type of threshold is used. The reason why this is a top level field is mostly due to legacy. This was initially the only type of thresholds the were supported (i.e. either overall or inspection), and other alarm threshold types were added later.
0 simply means that no overall or inspection alarm threshold is configured. This is the default when creating a new point in Enlight.
Overall alarm thresholds are given by threshold type 1 and 2, where these values represent an “in window” and “out of window” threshold, respectively.
An “in window” threshold will trigger when a value falls within a defined window, and “out of window” when it falls outside of the window.
Examples showing the different alarm definitions are available [here][/v1/docs/service/threshold#overall].
Normally an overall alarm is calculated from DATA_POINT measurements. There is however a special case where inspection points can have overall alarm thresholds defined, which are calculated using QUESTION_ANSWERS measurements. This is relevant where e.g. an inspection point is used to indicate the temperature for an asset using a gauge. The temperature is recorded as a numeric value (as a string) in a QUESTION_ANSWERS measurement. When this is received by PAS the string value is cast to a numeric value, and is then compared to the defined overall threshold.
An inspection alarm is set by threshold type 3.
Inspection thresholds are used to set alarm levels for answers to either single or multiple choice questions. The answer recorded in a QUESTION_ANSWERS measurement are compared to the choices defined in the alarm threshold, and the appropriate alarm status is set.
Note: PAS does not do any validation that the answers defined in the alarm threshold matches answers defined on the inspection point.
Note: This alarm type is mostly unused, as it’s not possible to set through Enlight.
Overall values ingested by the Measurements service will, whenever possible, include a “rate of change” value which indicates how much the value of that overall changed compared to the last one. This is then given as the value change in percent, i.e if the last value was 20.0 and a new overall is ingested with value 25.0, the rate of change would be 25, indicating that the rate of change is 25%.
A rate of change alarm allows a user to set an alarm threshold on this rate of change property, so that if the rate of change exceeds a certain threshold an alarm is set.
The alarm threshold works by setting a window which defines the boundaries of an acceptable rate of change. It is possible to set low and high limits which trigger ALERT and DANGER alarms.
{
"rateOfChange":
{
"unit": "gE",
"outerHigh": 20,
"innerHigh": 10,
"innerLow": -10,
"outerLow": -20
}
}
| Limit | Value | Status |
|---|---|---|
| Danger | ||
| Outer high | 20 | |
| Alert | ||
| Inner high | 10 | |
| Good | ||
| Inner low | -10 | |
| Alert | ||
| Outer low | -20 | |
| Danger |
Given the threshold definition above, a rate of change with value 5 would trigger an “alarm” status of GOOD, whereas a rate of change of -15 would trigger an ALERT alarm status.
It is possible to omit any of the limit fields if needed. If the user only wishes to get an alert if the rate of change goes up over a certain limit, it is possible to only set the innerHigh limit.
Calculates an overall for a defined frequency band on a spectrum measurement, and checks against pre-set alarm levels.
The minFrequency and maxFrequency objects sets the lower and upper bounds of the frequency band for which an overall value is calculated.
The valueType in the band alarm minFrequency and maxFrequency is an integer enumeration setting whether or not the specified frequency is an absolute value, or a multiple of the speed of the spectrum. For a FIXED type the frequency is simply the exact minimum or maximum frequency. For a SPEED_MULTIPLE type, the value represents a multiple for the spectrum speed in Hz. Speed in a spectrum is represented in RPM which is then recalculated into Hz and multiplied by the given value to get the minimum and maximum frequency. E.g., a maximum frequency SPEED_MULTIPLE value of 10 applied to a spectrum with speed 1780 RPM would have frequency (1780 / 60) * 10 = 290.
The API allows having different frequency types for minFrequency and maxFrequency. E.g. it is possible to have a fixed value minFrequency and a speed multiple maxFrequency. Users should be aware that this can lead to calculations where e.g. the actual maxFrequency for a spectrum is lower than minFrequency. In these cases the alarm status will be set to 1 (i.e. NO_DATA). The reason field of the alarm status would then indicate what the frequencies were for the spectrum.
The mapping of values is documented here.
The valueType field in the band alarm thresholds (under overallThreshold) specifies how the threshold in the corresponding value field is interpreted.
ABSOLUTESetting 1 indicates that the value is an absolute value limit. If the calculated band overall value is higher than this value the corresponding alarm level is set.
RELATIVE_FULLSCALESetting 2 means the actual threshold level is calculated relative to the configured fullScale value. The value is a percentage value that is multiplied with the fullScale value to return the threshold to be compared to the calculated band overall, i.e. fullScale * (value / 100).
Given the example threshold below, the value used when calculating the alarm status for upperDanger would be 0.5 * (70 / 100) = 0.4, and upperAlert would be 0.5 * (50 / 100) = 0.25.
{
"nodeId": "123e4567-e89b-12d3-a456-426614174000",
"fullScale": 0.5,
"bandAlarms": [
{
"label": "2X RPM",
"maxFrequency":
{
"valueType": 1,
"value": 200
},
"minFrequency":
{
"valueType": 1,
"value": 100
},
"overallThreshold": {
"unit": "gE",
"upperDanger":
{
"valueType": 2,
"value": 80
},
"upperAlert":
{
"valueType": 2,
"value": 50
}
}
}
]
}
The mapping of values is documented here.
RELATIVE_OVERALLA setting of 3 indicates that the actual threshold value is calculated relative to the overall threshold corresponding to the band threshold.
Similar to RELATIVE_FULLSCALE the value in this case is a percentage value that is multiplied with the corresponding overall threshold to form the actual alarm threshold.
The table below specifies which overall threshold field is compared to which band threshold field.
| Band threshold | Overall threshold |
|---|---|
upperAlert |
innerHigh |
upperDanger |
outerHigh |
Setting a RELATIVE_OVERALL requires setting the corresponding overall threshold while the thresholdType should be OVERALL_OUT_OF_WINDOW (i.e. 2).
Given the example threshold below, the value used when calculating the alarm status for upperDanger would be 5.0 * (80 / 100) = 4.0, and 2 * (50 / 100) = 1.0 for upperAlert.
{
"nodeId": "123e4567-e89b-12d3-a456-426614174000",
"thresholdType": 2,
"overall"
{
"unit": "gE",
"outerHigh": 5,
"innerHigh": 2
},
"bandAlarms": [
{
"label": "2X RPM",
"maxFrequency":
{
"valueType": 1,
"value": 200
},
"minFrequency":
{
"valueType": 1,
"value": 100
},
"overallThreshold": {
"unit": "gE",
"upperDanger":
{
"valueType": 3,
"value": 80
},
"upperAlert":
{
"valueType": 3,
"value": 50
}
}
}
]
}
The mapping of values is documented here.
The unit field in the overallThreshold corresponds to the Y unit label of a spectrum. The value of the unit must match the Y unit value of spectrums available on the measurement point for overall values to be calculated. If the unit type does not match, no overall will be calculated and the alarm status will be set to NO_DATA.
General information about the threshold endpoint is available here.
{
"nodeId": "123e4567-e89b-12d3-a456-426614174000",
"thresholdType": 0,
"bandAlarms": [
{
"label": "2X RPM",
"maxFrequency":
{
"valueType": 1,
"value": 200
},
"minFrequency":
{
"valueType": 1,
"value": 100
},
"overallThreshold": {
"upperDanger":
{
"valueType": 1,
"value": 0.7
},
"upperAlert":
{
"valueType": 1,
"value": 0.5
}
}
}
]
}
General information about the alarm status endpoint is available here.
The status fields in the response contains overall and specific alarm statuses, with values documented here.
updatedAt contains the time when the alarm status was last updated, given as epoch in milliseconds.
triggeringMeasurement contains the ID of the measurement used to calculate this alarm status.
label is either the name of a GLOBAL alarm, or the name of a fault frequency (in the case of alarm type FREQUENCY).
{
"nodeId": "123e4567-e89b-12d3-a456-426614174000",
"updatedAt": 1633939101250,
"status": 2,
"bandAlarms":
[
{
"status": 2,
"triggeringMeasurement": "123e4567-e89b-12d3-a456-426614174000",
"label": "2X RPM",
"maxFrequency":
{
"valueType": 1,
"value": 200
},
"minFrequency":
{
"valueType": 1,
"value": 100
},
"calculatedOverall":
{
"unit": "g",
"value": 0.2
}
}
]
}
Note: It is not possible to configure HAL alarms in Enlight. The only source of HAL alarm thresholds is imports from Analyst.
Checks a calculated HAL index against pre-set alarm levels.
There are two types of alarm thresholds.
A GLOBAL alarm threshold is compared to all HAL indexes calculated for a given spectrum. The highest HAL index is used, and is then compared to the levels configured for the threshold.
A FREQUENCY alarm threshold is compared to a specific HAL index. For a custom fault frequency the label of the alarm threshold is compared to the name of the calculated HAL index. For a bearing fault frequency, the label as well as the bearing manufacturer and model number must match in the alarm threshold and calculated HAL index.
Example:
Given the threshold below, and a spectrum with the given HAL data tags, the alarm status would be set as DANGER.
{
"nodeId": "5984c776-5d41-46f2-98f3-3436d47ecd93",
"thresholdType": 0,
"halAlarms":
[
{
"label": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 5.5,
"upperAlert": 2.5
}
]
}
{
"nodeId": "5984c776-5d41-46f2-98f3-3436d47ecd93",
"contentType": "SPECTRUM",
"createdAt": "2020-12-17T13:10:37.0037Z",
"spectrum":
{
"coordinates": null,
"xUnit": "Hz",
"yUnit": "g",
"windowFunction": "hanning",
"speed": 225
},
"tags":
{
"hal-data":
{
"HAL-0":
{
"name": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"rpmFactor": 6.4299998,
"frequency": 24.1124992,
"halIndex": 6.79
}
}
}
}
The HAL indexes are calculated by the Measurements service, and are included in the tags field of the measurement as shown in the example above. When a spectrum is ingested, custom fault frequencies are fetched on the measurement point of the measurement, and bearing fault frequencies are fetched for bearings attached to the asset of the measurement point. A HAL index is then calculated for each of these fault frequencies. Since bearings have 4 standard fault frequencies, each bearing attached to the asset will lead to 4 HAL indexes being calculated for the spectrum (in addition to any custom fault frequencies). So a measurement point on an asset with 2 bearings attached, and 2 custom fault frequencies set on the measurement point will lead to 10 HAL indexes being calculated for each spectrum.
General information about the threshold endpoint is available here.
upperAlert represents the threshold for when alarm status ALERT is set. If the HAL index corresponding to this threshold is over this value, the alarm status of the threshold is set to ALERT.
upperDanger represents the threshold for when alarm status DANGER is set. If upperAlert is specified, upperDanger must be higher than upperAlert. As with upperAlert, if the HAL index calculated for this threshold is over the specified limit, the alarm status is set to DANGER.
bearing must be included if the specified alarm threshold is related to a bearing fault frequency. The value should be an object that contains the bearing manufacturer and model number, as given in the example below.
{
"nodeId": "00000000-0000-0000-0000-000000000000",
"thresholdType": 0,
"halAlarms":
[
{
"label": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2222"
},
"halAlarmType": "FREQUENCY",
"upperDanger": 7.5,
"upperAlert": 2.5
}
]
}
General information about the alarm status endpoint is available here.
The status fields in the response contains overall and specific alarm statuses with values documented here.
updatedAt contains the time when the alarm status was last updated, given as epoch in milliseconds.
triggeringMeasurement contains the ID of the measurement used to calculate this alarm status.
label is either the name of a GLOBAL alarm, or the name of a fault frequency (in the case of alarm type FREQUENCY).
bearing is included if the HAL index is calculated for a fault frequency belonging to a bearing. The object contains the manufacturer and model number of the bearing.
halIndex is the HAL index calculated for the given fault frequency for the spectrum.
faultFrequency is the fundamental frequency which was used when calculating the HAL index.
rpmFactor is included if it was specified by the fault frequency the HAL index corresponds to. rpmFactor is used as a multiple of the speed of the spectrum. If this value is included, the faultFrequency is calculated using this rpmFactor.
numberOfHarmonicsUsed contains the number of harmonic peaks that was used when calculating the HAL index.
{
"nodeId": "00000000-0000-0000-0000-000000000000",
"status": 2,
"updatedAt": 1633939101250,
"halAlarms":
[
{
"status": 2,
"triggeringMeasurement": "123e4567-e89b-12d3-a456-426614174000"
"label": "bpfo",
"bearing":
{
"manufacturer": "SKF",
"modelNumber": "2221CRB"
},
"halIndex": 1.9,
"faultFrequency": 299.72314,
"rpmFactor": 6.4299998,
"numberOfHarmonicsUsed": 55.8
}
]
}