IAlarming

Namespace

ZApplication

INTERFACE IAlarming

Some critical processes running in the industries may cause faults due to some failure of equipment, out-of-control process loops, (etc.). Fault can be generated when some measured variable goes out of the range, e.g. this can be level, flow, temperature, pressure or any other kind of parameter. Therefore, PLCs usually need a mechanism to inform an operator about potential issues or even require the operators acknowledgement before continuing with production.

The Alarming function-block implements a convientent mechanism to send messages to an operator. We distinguish between three kinds of messages

• message that do not require acknowledgment Such messages may appear spontaneously during production and do not stop the ongoing process. They are intended solely for indications and no interaction of the user is required. Messages with this severity level are internally acknowledged automatically.
• message that require single acknowledgment Usually such messages are caused if a sequence failed, because some requirements were not met and the machine is unable to continue production. They may require special attention of an operator, since he has to manually acknowledge such messages. The single acknowledgment can, for instance, be "pressing a specific button in the HMI" or "start homing of the machine"
• messages that require dual acknowledgment For special cases it is possible to require acknowledgment of an operator after the message appeared and additionally, after the reason for the error disappeared.

The alarming system is implemented and used in the framework in the following way. Each alarm (aka message) has an alarm-states to indicate

• if a message was sent (Incoming and is waiting for acknowledment
• if a message was sent and acknowledged (Incoming & IncomingAcknowledged
• if the reason for the alarm is no longer present (Outgoing
• if the reason for the alarm is no longer present and this is acknowledged (Outgoing & OutgoingAcknowledged

To add an alarm to the alarming system, the function-block provides a general purpose Alarm method, where the alarm can be configured to every detail (i.e. initial state of the alarm to configure if the alarm required acknowledgment or not, triggers to automatically acknowledge the incoming or outgoing state, ...). However, in most cases it is sufficient to use predefined alarming methods.

Alarming METHOD	Description	initial state
trace	No acknowledge required	Incoming | IncomingAcknowledged | Outgoing | OutgoingAcknowledged
debug	No acknowledge required	Incoming | IncomingAcknowledged | Outgoing | OutgoingAcknowledged
warning	No acknowledge required	Incoming | IncomingAcknowledged | Outgoing | OutgoingAcknowledged
info	No acknowledge required	Incoming | IncomingAcknowledged | Outgoing | OutgoingAcknowledged
error	No acknowledge required	Incoming | IncomingAcknowledged | Outgoing | OutgoingAcknowledged
critical	Single acknowledgment when the alarm comes up	Incoming | Outgoing | OutgoingAcknowledged
fatal	Dual acknowledment; first, when the alarm comes up and then again after fixing the problem	Incoming | Outgoing | OutgoingAcknowledged

Properties

AlarmRaised

PROPERTY AlarmRaised : BOOL

This property returns TRUE if an alarm is present and has not yet been solved.

Property Value

BOOL

Busy

PROPERTY Busy : BOOL

Returns TRUE if the alarming system is working properly and no acknowledgment for any alarm is required.

Property Value

BOOL

Done

PROPERTY Done : BOOL

This property is usually not used, the alarming system is always busy and is never "done".

Property Value

BOOL

Methods

Alarm

METHOD Alarm (
 [input] source : ZCore.ZString,
 [input] text : ZCore.ZString,
 [input] logLevel : ZCore.LogLevel,
 [input] state : AlarmingState,
 [input] incomingAcknowledgementTrigger : ZCore.ITrigger,
 [input] outgoingTrigger : ZCore.ITrigger,
 [input] outgoingAcknowledgementTrigger : ZCore.ITrigger)

Inputs

source ZString

source of the alarm

text ZString

description of the alarm

logLevel LogLevel

severity level of the alarm, messages with higher severity level are prioritized in the alarming system if the maximum number of messages is exceeded

state AlarmingState

initial state of the alarm, bitencoded. The minimum viable state if Incoming

incomingAcknowledgementTrigger ITrigger

(optional) trigger that automatically acknowledges the incoming Incoming state. If set to 0, the alarm has to be acknowledged by an HMI.

outgoingTrigger ITrigger

(optional) trigger that signals that the reason for the alarm has been fixed. If set to 0, the alarm is automatically outgoing

outgoingAcknowledgementTrigger ITrigger

(optional) trigger that automatically acknowledges the outgoing Outgoing state. If set to 0, the alarm has to be acknowledged by an HMI or by a Unit's homing sequence

AlarmRef

METHOD AlarmRef (
 [input] source : REFERENCE TO ZCore.ZString,
 [input] text : REFERENCE TO ZCore.ZString,
 [input] logLevel : ZCore.LogLevel,
 [input] state : AlarmingState,
 [input] incomingAcknowledgementTrigger : ZCore.ITrigger,
 [input] outgoingTrigger : ZCore.ITrigger,
 [input] outgoingAcknowledgementTrigger : ZCore.ITrigger)

General purpose method to add an alarm to the alarming system. This method may be used if special triggers for acknowledgement should be used, otherwise the more convienent alarm methods (i.e. Warning, Error as described Here.

Inputs

source REFERENCE TO ZString

source of the alarm

text REFERENCE TO ZString

description of the alarm

logLevel LogLevel

severity level of the alarm, messages with higher severity level are prioritized in the alarming system if the maximum number of messages is exceeded

state AlarmingState

initial state of the alarm, bitencoded. The minimum viable state if Incoming

incomingAcknowledgementTrigger ITrigger

(optional) trigger that automatically acknowledges the incoming Incoming state. If set to 0, the alarm has to be acknowledged by an HMI.

outgoingTrigger ITrigger

(optional) trigger that signals that the reason for the alarm has been fixed. If set to 0, the alarm is automatically outgoing

outgoingAcknowledgementTrigger ITrigger

(optional) trigger that automatically acknowledges the outgoing Outgoing state. If set to 0, the alarm has to be acknowledged by an HMI or by a Unit's homing sequence

Clear

METHOD Clear ()

Removes all alarms that have been acknowledged

Critical

METHOD Critical (
 [input] text : ZCore.ZString)

See Critical The alarm's source is automatically set to the name that is provided when constructing this object.

Inputs

text ZString

Debug

METHOD Debug (
 [input] text : ZString)

Logs a message to the logger with log-severity level Debug if the severity level applies.

A Debug message is less granular compared to the trace level, but it is more than you will need in everyday use. The debug log level should be used for information that may be needed for diagnosing issues and troubleshooting or when running an application in a test environment for the purpose of making sure everything is running correctly. For more information about this loglevel, see sematext.

Inputs

text ZString

Desired debug message as ASCII text

Error

METHOD Error (
 [input] text : ZString)

Logs a message to the logger with log-severity level Error if the severity level applies.

The error level should be used when the application hits an issue preventing one or more functionalities from properly functioning. For instance, if a servo-motor can not reach its desired position or if a sudden pneumatic pressure drop occurs. For more information about this loglevel, see sematext.

Inputs

text ZString

Desired error message as ASCII text

ErrorId

METHOD ErrorId () : UDINT

Returns the error code of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

Returns

UDINT

ErrorMessage

METHOD ErrorMessage () : ZCore.ZString

Returns the error description of the first error source for this object. The method recursively goes down the error stack until the initial source of error of this object can be found. For performance reasons, the error stack is not cleared when the error state is reset. So this method should always used in conjunction with Error.

Returns

ZString

ErrorSource

METHOD ErrorSource () : ZCore.IError

this method returns the direct error source of this object. This method can then be used to retrieve the actual error source by using the method of the returned IError.

Returns

IError

Fatal

METHOD Fatal (
 [input] text : ZCore.ZString)

See Fatal The alarm's source is automatically set to the name that is provided when constructing this object.

Inputs

text ZString

Info

METHOD Info (
 [input] text : ZString)

Logs a message to the logger with log-severity level Info if the severity level applies.

Info is the standard log level and is indicating that something happened, i.e. the application entered a certain state For instance, an operator of your production system starts the automatic sequence and this can be logged as info if it was successfull or not. The information logged using the info log level should be purely informative and not looking into them on a regular basis shouldn’t result in missing any important information. For more information about this loglevel, see sematext.

Inputs

text ZString

Desired information message as ASCII text

SetLevel

METHOD SetLevel (
 [input] logLevel : ZCore.LogLevel)

See SetLevel

Inputs

logLevel LogLevel

SetLevelRef

METHOD SetLevelRef (
 [input] logLevelRef : REFERENCE TO ZCore.LogLevel)

See SetLevelRef

Inputs

logLevelRef REFERENCE TO LogLevel

Trace

METHOD Trace (
 [input] text : ZString)

Logs a message to the logger with log-severity level Trace if the severity level applies.

Trace is the most fine-grained information only used in rare cases where you need the full visibility of what is happening in your application and inside the third-party libraries that you use. You can expect the trace logging level to be very verbose. You can use it for example to annotate each step in a sequence or extra entries in different if branches. For more information about this loglevel, see sematext.

Inputs

text ZString

Desired trace message as ASCII text

Warning

METHOD Warning (
 [input] text : ZString)

Logs a message to the logger with log-severity level Warning if the severity level applies.

A warning indicates that something unexpected happened in the application, a problem, or a situation that might disturb one of the processes. But that doesn’t mean that the application failed or the production system had to be stopped. The warning log level should be used in situations that are unexpected, but the code can continue the work. For example, an electric motor (servo) has two levels for overheating. A warning temperature and a temperature were it is very likely that it will soon get broken. For more information about this loglevel, see sematext.

Inputs

text ZString

Desired warning message as ASCII text