Skip to main content

"diagnostics" monitoring module

Description

The task of the "diagnostics" monitoring module is to monitor various types of input data against defined criteria and then write the resulting alarm information to the smartCORE alarm database of the Alarm Manager.

This database can be connected to optiCloud, e.g., using the opticloud plugin, for further processing of the alarm messages.

The types of monitored input data include, among others

  • Boolean values, e.g., status flags or results of calculated logic
  • Double values (floating-point), e.g., measured values or calculated quantities that are compared against a fixed threshold. An adjustable hysteresis is provided for noise suppression. To track extreme values, message updates can be enabled.
  • Integer codes, e.g., status or ENUM codes, or specific bits or bit segments; where individual codes or code ranges can be filtered using a white/black list and assigned to the HIGH or LOW state, respectively. Mismatched codes are reported via a separate error status alarm until a valid code is received. To track status changes, message updates can be enabled.
  • String values (text), e.g., log messages from a device; text elements can be extracted using Regular Expressions (PCRE), filtered via a white/black list, and assigned to the HIGH or LOW state. Mismatched texts are reported via a separate error status alarm until a valid code is received.
  • ErrorCode: A sequence of error codes (<string>) associated with either a level channel or a transfer channel. The Diagnostics module maintains an internal table of error codes and their corresponding message instances. Messages can be assigned to individual codes, or as a template to a range of codes (wildcard), or to all incoming codes.

In addition, current values from smartCORE channels (so-called snapshots) are captured and user-defined metadata is integrated as part of the compilation of alarm messages. The following diagram provides an overview of the implemented functionality of the alarm logic. For each message entry, the blocks highlighted in light yellow are available:

Overview

From the perspective of the diagnostics plugin, the data from a monitored channel is processed, i.e., an implicit conversion to the expected data type takes place. Thus, the channel’s data type is irrelevant for evaluation, provided it can be converted accordingly.

Interfaces & Protocols Used

  • smartCORE alarm database

JSON Configuration

The following sections list example configurations and discuss the module parameters involved.

Example Configuration (Monitoring Boolean Values)

In this example, a channel is monitored for the value true when read as Boolean.

The following applies to data type conversion:

  • <integer, <unsigned integer>, or <double> is true if the sample is 0\ne 0,
  • <string> is true if the string is not empty
{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring someBooleanChannel",
"channel": "someBooleanChannel",
"activation": "high"
}
]
}
}

Example Configuration (Monitoring a Numeric Value Exceedance with Stabilization Delays and Hysteresis)

In this example, a channel is read as Double and monitored for exceeding the value of 42.0.

The following applies to data type conversion:

  • <bool> is translated to 0 and 1,
  • <string> returns the length of the string as the value

In the example, triggering requires that the exceedance lasts for at least 5 seconds, and deactivation requires that it has not occurred for at least 10 seconds and that the channel value is below the threshold minus its hysteresis.

An event-related message is also generated, containing the current value, the previous extreme value (i.e., the maximum in this case), and the threshold value.

This message is updated both upon the initial exceedance and upon deactivation. Furthermore, this message is also updated when deviations of the current value from the last reported extreme value exceed the hysteresis.

{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring measured someValueChannel",
"messageEvent": "A WARNING occurred (current value ${value} > ${boundary}) (maximum value ${minmax} on ${minmaxDate} at ${minmaxTime})",
"channel": "someValueChannel",
"threshold": 42.0,
"hysteresis": 7.0,
"activation": "high",
"stabilizationSecondsRaise": 5,
"stabilizationSecondsRelease": 10,
}
]
}
}

Example Configuration (Monitoring Enumerated Values)

In this example, a channel is read and monitored as an Integer value.

The following applies to data type conversion:

  • <bool> is translated to 0 and 1,
  • <float> or <double> is used without decimal places,
  • <string> returns the length of the string as the value

In this example, the value ranges 17 and 77–99 are interpreted as trigger conditions (HIGH), the value ranges 31–39, 66, and 69–71 as deactivation conditions (LOW), and all other ranges as invalid alarm conditions.

{ 
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring someEnumeratedChannel",
"messageEvent": "Some WARNING occurred",
"messageFailure": "INVALID error occurred",
"channel": "someEnumeratedChannel",
"activation": "enum",
"valuesHigh": "17,77-99",
"valuesLow": "31-39,66,69-71"
}
]
}
}

Example Configuration (Monitoring an Error Stream)

In this example, error codes (ErrorCode) are monitored from a so-called error stream. This consists of the two sourceErrorCode and sourceErrorLevel channels, which must be synchronized in time. The error code channel is read as <string>, so that almost any channel can be used as a source. The error level channel must provide integer <integer> values. The codes extracted from this error stream are available for processing in all ErrorCode messages in the order in which they are defined. A specific code can only be included in one ErrorCode message at a time.

In the example, the user-specific error code "47:11", error codes beginning with "ERR:", and all other unknown error codes are monitored. If the message object is to be used for different codes, it must be marked as a template.

{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"sourceErrorCode": "Some.Name.Space.ErrorCodeChannel",
"sourceErrorLevel": "Some.Name.Space.ErrorLevelChannel",
"messages": [
{
"errorCode": "47:11",
"messageLevel": "ALARM",
"context": "Monitoring Error-Stream for 47:11",
"messageEvent": "ALARM ${errorCode} occurred"
},
{
"isTemplate": true,
"errorCode": "ERR:*",
"messageLevel": "ERROR",
"context": "Monitoring for ERR-codes",
"messageEvent": "Error ${errorCode} occurred"
},
{
"isTemplate": true,
"messageLevel": "WARNING",
"context": "Collection of unknown codes",
"messageEvent": "Unknown code ${errorCode} occurred"
}
]
}
}

Sample Configuration (Using Metadata)

In this example, a channel is monitored for the value true, as in Example 1. The purpose of this example is to illustrate how to supplement alarm messages with user-specific metadata.

To do this, metadata is added in the form of a JSON object during the assembly of the alarm message, whereby the global metadata is always supplemented with the metadata specified within the message or replaced at the top level of the JSON object.

{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"globalMetadata": {
"actionToBePerformed":"some generic action",
"consequences":[
"consequence1",
"consequence2"
]
},
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring someBooleanChannel",
"channel": "someBooleanChannel",
"activation": "high",
"metadata": {
"actionToBePerformed":"some CRITICAL action",
"consequences":[
"some SEVERE consequence",
"consequence1",
"consequence2"
],
"additionalRemarks":[
"some REMARK"
]
}
}
]
}
}

Sample Configuration (Using Snapshot Channels)

In this example, a channel is monitored for the value true, as in Example 1.

The goal of this example is to illustrate how alarm messages can be supplemented with a user-specific snapshot of channel values.

To do this, a snapshot of the listed smartCORE channels is taken at the time of the initial occurrence of the alarm condition, consisting of the union of all global and message-related snapshot channels.

{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"globalSnapshot": [
"someGps.Location",
"someOutsideTemperature"
]
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring someBooleanChannel",
"channel": "someBooleanChannel",
"activation": "high",
"snapshot": [
"somePressure",
"someTemperature",
"someQuantity",
]
}
]
}
}

Example Configuration (Using Snapshot Groups)

In this example, a channel is monitored for the value true, as in Example 1.

This example also illustrates the use of so-called snapshot groups.

{
"module": "diagnostics",
"factory": "diagnostics",
"config": {
"pollingIntervalMs": 1000,
"snapshotGroups": [
{
"name": "gpsInfoChannels",
"channels": [
"GPS.Location",
"GPS.Altitude",
"GPS.SatCount"
]
},
{
"name": "EngineOilPTQChannels",
"channels": [
"Engine.Oil.Pressure",
"Engine.Oil.Temperature",
"Engine.Oil.Quantity"
]
}
],
"globalSnapshot": [
"gpsInfoChannels",
"someOutsideTemperature"
]
"messages": [
{
"messageLevel": "WARNING",
"context": "Monitoring someBooleanChannel",
"channel": "someBooleanChannel",
"activation": "high",
"snapshot": [
"Engine.Revs",
"EngineOilPTQChannels"
]
}
]
}
}

Global Module Parameters

The following section discusses all parameters of the module.

Parameter NameRequiredData TypeValid RangeDefault ValueDescription
pollingIntervalMsNoINT1 -1000 (1 s)Processing interval [ms]
globalMetadataNoJSON ObjectEMPTY JSON ObjectJSON object containing arbitrary user-specified metadata
globalSnapshotNoJSON Array of STRINGEMPTY JSON ArrayJSON array containing a global list of channels whose values are to be captured at specific points in time when an alarm is triggered
snapshotGroupsNoJSON Array of JSON ObjectEMPTY JSON Arraysee below
activationMode1(deprecated)See description of messages
messagesYESJSON array of JSON objectsNO default valuesee below
for error stream or error table
sourceErrorCodeNo/Yes2 3STRINGNO default valuesmartCORE channel, read as <string>, containing a time-variable error code
sourceErrorLevelNo/Yes2STRINGNO default valuesmartCORE channel, read as <integer>, containing a synchronous error level
neutralErrorLevel
neutraErrorCode4
No2
(obsolete)
INTEGER0Neutral error level at which NO alarm is triggered
sourceBufferTransferNo/Yes3STRINGNO default valuesmartCORE channel, read as <bool>, which controls the framing for the transmission of the error table
timeoutBufferTransferNo/Yes3DOUBLE0Minimum pause between the transmission of error tables in seconds

Global Snapshot Groups "snapshotGroups"

Multiple channels to be captured within a snapshot can be configured as a JSON object in the form of a snapshot group, whose name can then be used as a channel name in groups and signal lists during the rest of the configuration process. It makes sense to name these groups so that they do not conflict with existing channel names, since a name in a signal list is first checked as a group name during interpretation.

If channel names are included in different groups or signal lists and are thus duplicated, they are included only once in the snapshot when it is compiled.

Parameter NameRequiredData TypeRecommended Value RangeDefault ValueDescription
nameYESSTRINGName or alias of the snapshot group
channelsYESJSON Array of STRINGList of all channel names or already defined groups

Configuration of "messages" alarm notifications

The "messages" alarm notifications are in the form of JSON objects and are configured differently depending on the type of monitoring.

important

The selection of parameters determines which type of monitoring is performed. The following table summarizes this. As soon as a named parameter is used, the corresponding function is activated:

Monitoring as...Parameters for activationRequiredAdditional recommended parametersNote
ErrorCodeisTemplate
errorCode
No
No
Ignores channelName because data source is Error-Stream/-Table,
activation := HIGH
No filtering function
Doublethreshold
boundary5
hysteresis
Yes
(deprecated)
Yes
channel
activation
stabilizationSecondsRaise
stabilizationSecondsRelease
Hysteresis is always >0.0\gt 0.0
IntegerstartBit
numberOfBits
valuesWhite
valuesBlack
valuesHigh
valuesLow
No
No
No
No
Recommended
Recommended
channel
activation
stabilizationSecondsRaise
stabilizationSecondsRelease
When numberOfBits == 1, the selected bit is treated as in Boolean mode.
StringregxWhite
regxBlack
regxHigh
regxLow
No
No
Recommended
Recommended
channel
activation
stabilizationSecondsRaise
stabilizationSecondsRelease
If regxWhite defines subexpressions, these are extracted for all subsequent tests and concatenated with ';'.
Booleanchannel
activation
stabilizationSecondsRaise
stabilizationSecondsRelease

Common Configuration Parameters

Regardless of the type of monitoring, the following parameters are defined for messages:

Parameter NameRequiredData TypeUseful Value RangeDefault ValueDescription
messageLevelYESSTRINGinfo, action, service, warning, alarm, error, fatalNO default valueSeverity level of the alarm message
contextYESSTRINGContext of the alarm message
Static text for identifying a message
channelYES/NO6STRINGName of the monitored smartCORE channel
activationYESSTRINGlow, high, minimum, maximum, positiveEdge, negativeEdge, enumCodehighType of alarm activation.
messageEventNoSTRINGAlarm message when the alarm is triggered.
Placeholders can be used for dynamic message content.
needAcknowledgeNoBOOLEANfalse, truefalseIs an acknowledgment required on the cloud side?
keepAcknowledgedStatusNoBOOLEANfalse, truefalseShould the acknowledged status be retained
metadataNoJSON ObjectEMPTY JSON ObjectUser-defined metadata that can potentially override the global metadata
snapshotNoJSON Array of STRINGEMPTY JSON ArrayChannels to be captured during the initial occurrence of the alarm condition. The global snapshot "globalSnapshot" is merged with the snapshot groups specified and resolved here (from "snapshotGroups") as well as the channels specified individually here.
If the filter function is available:
stabilizationSecondsRaiseNoINTEGER1 -0Stabilization delay after which the alarm should be triggered (the initial time of the first occurrence of the alarm condition is reported)
stabilizationSecondsReleaseNoINTEGER1 -0Stabilization delay after which the alarm should be deactivated (the initial time of the first occurrence of the deactivation condition is reported)
If an error event can be triggered:
messageFailureNoSTRINGAlarm message when the alarm condition is invalid.
Placeholders can be used for dynamic message content.

Activation configuration: activation

The following values can be selected for alarm activation:

Enum valueAliasMeaningNote
lowTriggered as long as source is LOWDouble mode monitors for minimum
high, (Default)Triggered as long as source is HIGHDouble mode monitors for maximum
minimumminTriggers as long as source is LOW with updatesDouble mode monitors for minimum with updates
maximummaxTriggers as long as source is HIGH with updatesDouble mode monitors for maximum with updates
negativeEdgenegEdgeTransition from HIGH to LOW triggersReported as a stateless event7
positiveEdgeposEdgeTransition from LOW to HIGH triggersMessage as stateless event7
enumCodeenumTriggers as long as source provides HIGH with updatesInteger/String modes update respectively for the new error code

Placeholders for message texts

The following placeholders can be used in the message texts messageEvent and messageFailure to dynamically supplement the text with current values for each event or update. In the case of templated error code messages, certain placeholders can also be replaced in context when the error code is registered for the first time.

PlaceholderReplaced byExample
${channel}Channel name of the messagesomeChannelName
${unit}Physical unit of the channel°C
${value}8The current data value of the channel3.14159
${date}The date of the event, YYYY-MM-DD2026-12-31
${time}The time of the event, hh:mm:ss18:05:27
${errorCode}9The triggering error codeERR:243:881
${errorLevel}9The triggering error level8
${boundary}10
${raiseBoundary}10
Set threshold value for activation threshold10.0
${releaseBoundary}10Threshold value for deactivation threshold ±\pm hysteresis8.5
${minmax}10Last extreme value since event
or if not determined:
17.9
(n.a.)
${minmaxDate}10Date of the extreme value
or if not assigned:
2026-12-31
(n.a.)
${minmaxTime}10Time of the extreme value
or, if not assigned:
18:12:35
(n.a.)

All other placeholders ${...} and any unavailable placeholders are replaced with "(n.d.)".

Channel Value Monitoring as Boolean

Monitoring as a Boolean value is set up if no individual parameters are added to the Messages object. The channel directly outputs the values true (HIGH) and false (LOW). The activation parameter determines at which level or with which edge the message is triggered.

Channel value monitoring as a double

When monitoring the numerical value of a smartCORE channel, the configuration object in messages is supplemented by the threshold or hysteresis parameters. The activation parameter determines whether the threshold limit is to be interpreted as a minimum or maximum, and consequently whether the hysteresis must lie below or above the limit as a return to the non-critical range.

Parameter NameRequiredData TypeValid Value RangeDefault ValueDescription
threshold
boundary5
YESFLOAT0Threshold value; exceeding or falling below this value leads to the initial fulfillment of the alarm condition
hysteresisYESFLOATlow, high, minimum, maximum0.5Zone below/above the threshold value in which the last state is maintained.
activationYESSTRINGlow, high, minimum, maximumHIGHDetermines whether the threshold value should be read as a minimum or maximum and whether the extreme value should be tracked with renewed signaling.

Channel Value Monitoring as Integer

If the configuration object in messages is supplemented by at least one of the following individual parameters, the channel to be monitored is read as <integer>. Optionally, a bit group of adjustable length can be extracted from this value for further processing. This value is filtered and interpreted as a status code or ENUM value:

Parameter NameRequiredData TypeValid Value RangeDefault ValueDescription
bitPositionNoINTEGER0..630Defines a right shift of the integer value prior to analysis.
numberOfBitsNoINTEGER1..64
0: no masking
0Masks the corresponding number of bits from the status word for analysis. The masked value is unsigned for numberOfBits <64\lt 64. If numberOfBits == 1, the bit is further processed as a Boolean.
valuesWhiteNoSTRING11(empty)Permitted value ranges for the analysis; values not included are ignored.
valuesBlackNoSTRING11(empty)Non-permitted value ranges for the analysis; values included are ignored.
valuesLowOPTIONALSTRING11(empty)Specification of the value ranges corresponding to a deactivated alarm condition
valuesHighOPTIONALSTRING11(empty)Specification of the value ranges corresponding to a triggered alarm condition
activationYESSTRINGhigh
enum
HIGHType of alarm activation

Before the channel’s values are fed into an evaluation, they can optionally be filtered via the white or black list. Only values contained in the valuesWhite list are processed. All values excluded in the valuesBlack list are ignored.

Either one or both of the above-mentioned value range specifications valuesLow and valuesHigh can be used. If only one specification is used, e.g., valuesHigh, all other values are automatically assigned to the opposite, in this case LOW. If, however, both specifications are used, the uncovered value ranges correspond to an invalid alarm condition. For this, an invalid alarm message with the text messageFailure can be specified.

Channel Value Monitoring as a String

If the configuration object in messages is supplemented by at least one of the following individual parameters, the channel to be monitored is interpreted as a <string> (text), e.g., as a log entry of a subsystem:

Parameter NameRequiredData TypeValid RangeDefault ValueDescription
regxWhiteNoSTRING12(empty)Regular expression that checks for valid text and formatting.
regxBlackNoSTRING12(empty)Regular expression that determines text to be ignored.
regxLowOPTIONALSTRING12(empty)Regular expression that describes the LOW state
regxHighOPTIONALSTRING12(empty)Regular expression describing the HIGH state
activationYESSTRINGhigh
enum
HIGHType of alarm activation

Before the channel’s values are fed into an evaluation, they can optionally be filtered using the white or black expressions. Only text matching the regxWhite expression is processed. All values matching the regxBlack expression are ignored.

If regxWhite contains sub-expressions (terms in (...)), these are extracted upon a match and linked together with ';' for all subsequent analyses. This simplifies further interpretation, as the core elements have already been extracted from the often complex context.

Example:

"regxWhite": "Level:([A-Z]+),\\s+(.*)$"
"regxHigh" : "(ERROR|WARNING);"

Extracted from a log line:

2345987.3256346, abcDevice, Level:ERROR, Here some message!

the elements "ERROR" and "Here some message!". Further checking is performed on the text "ERROR;Here some message!". regxHigh can now simply check for the two valid error codes.

Either one or both of the above expressions regxLow and regxHigh can be used. If only one expression is used, e.g., regxHigh, all other values are automatically assigned the opposite, in this case, e.g., LOW. If, on the other hand, both expressions are used, the patterns not covered correspond to an invalid alarm condition. For this, an invalid alarm message with the text messageFailure can be specified.

Monitoring of error codes: ErrorCode

Devices that control systems or system components can communicate their error states externally in various forms:

  1. In the form of individual codes, each combined with the status "Incoming" or "Outgoing"

  2. In the form of fully transmitted error code tables (error memory) containing the pending codes. Here, observation must be used to determine which individual codes are "coming" (newly added) or "going" (no longer present). The transmission of the table is indicated by a control signal or is completed by a timeout after the last error code.

The example in the following diagram illustrates this for error codes 17, 42, B7, and E8. For maximum flexibility, the codes on the sourceErrorCodes channel are always read and processed as <string>.

Example of error codes

The Diagnostics module centrally reads the channels

  1. sourceErrorCode and sourceErrorLevel to interpret an error stream, or

  2. sourceErrorCode and sourceBufferTransfer to track the transmission of error code tables.

important

No data reduction filters may be configured at the source for these channels. The timestamps play a crucial role in localizing and synchronizing the data!

In general, the timestamp of the error code in the sourceErrorCode channel is decisive for interpretation. The sourceErrorLevel channel must provide the corresponding level with exactly identical timestamps. It is read as <integer> and compared against the neutralErrorLevel ("ok") to determine the activation state.

The level of the sourceBufferTransfer channel must switch to true* no later than** the first error code in a table and must fall back to false* after** the last code in the table. The transmission rate or order of the error codes is irrelevant. As an alternative to the control channel, a time interval timeoutBufferTransfer can also be used. The transmission of the table is considered complete if no further error codes arrive within this interval after the presumed last error code.

If the configuration object in messages is supplemented by at least one of the following individual parameters, the corresponding "messages" access these error codes in the order they are defined. In doing so, a specific error code can be monitored and reported, or a group of codes can be used as a template, or simply all (remaining) codes. For each individual code, a separate alarm message is automatically created that tracks the incoming/outgoing status. Text modules can be used to dynamically configure the initial context and message texts.

Parameter NameRequiredData TypeValid RangeDefault ValueDescription
errorCodeOPTIONALSTRING(empty)Error code monitored by this monitoring unit, possibly as WildMask text if isTemplate is set.
(empty) corresponds to "*"
isTemplateOPTIONALBOOLEANfalse, truefalseSet if this message entry is to automatically generate message entries dynamically for matching error codes.

Module Information

InformationValue
AuthorsoptiMEAS GmbH
Since smartCORE2.6
Module TypeConsumer
DependenciesNONE

Footnotes

  1. Prior to smartCORE 2.10.1, activationMode was used to switch between channel monitoring and error stream mode. This is no longer necessary as of 2.10.1; the parameter is ignored.

  2. To use the error stream function, these parameters must be specified. 2 3

  3. To use the error table function, these parameters must be specified. 2 3

  4. Prior to smartCORE 2.10.1, neutraError<u>Code</u> was used, even though the value refers to the ErrorLevel channel. Although the parameter is still read, it should no longer be used.

  5. "threshold" is used as a limit value in many places, including here. The boundary parameter is still read for threshold, but should no longer be used. 2

  6. If the message is configured in Error-Stream or Error-Table mode, the internal data source in the Diagnostics module is used and the channel is ignored.

  7. An alarm message is generated that contains only the event time—no "Coming"/"Going". 2

  8. In the case of Integer messages, this may be the bit range extracted from the actual channel value. In the case of String, this may be the concatenated text from sub-expressions.

  9. only in conjunction with ErrorCode 2

  10. only in conjunction with Double 2 3 4 5 6

  11. Contains a comma-separated list of individual <integer> values or value ranges in the form <integer> - <integer>. Spaces are ignored; signs are allowed. Example: "-100, -20 - -5, 12 - 34,47,55-57" 2 3 4

  12. A Regular Expression (PCRE) is expected here, whose control characters must be correctly escaped. The expressions are applied without regard to case (case-insensitive). 2 3 4