Table of Contents

Alarming

Namespace
ZApplication
Implements

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

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 
FUNCTION_BLOCK Alarming IMPLEMENTS ZApplication.IAlarming

Constructor

FB_init

The constructor of ManagedObject takes a parent as parameter, which is then notified about the creation of this instance.

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject,
 datetime : ZCore.IDateTime,
 com : REFERENCE TO AlarmingCom) : BOOL

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

parent IManagedObject

Interface to the ManagedObject that is the parent of this object

datetime IDateTime

com REFERENCE TO AlarmingCom

used to interact with alarming from an external application, i.e. an HMI

Returns

BOOL

Properties

Acknowledge 

PROPERTY Acknowledge : BOOL

Property Value

BOOL

AlarmRaised

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

PROPERTY AlarmRaised : BOOL

Property Value

BOOL

Busy

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

PROPERTY Busy : BOOL

Property Value

BOOL

Done

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

PROPERTY Done : BOOL

Property Value

BOOL

Pending 

PROPERTY Pending : REFERENCE TO AlarmingMessageCom

Property Value

REFERENCE TO AlarmingMessageCom

Methods

Alarm

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.

METHOD Alarm (
 source : ZCore.ZString,
 text : ZCore.ZString,
 logLevel : ZCore.LogLevel,
 state : AlarmingState,
 incomingAcknowledgementTrigger : ZCore.ITrigger,
 outgoingTrigger : ZCore.ITrigger,
 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

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.

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

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

Removes all Messages that have been acknowledged

METHOD Clear ()

Critical

Adds an alarm according to the specification described in the Function-block.

The critical log level means that the crucial part of the application is not working and we are not delivering a business logic, so a total failure. You can potentially create alerts on error log level messages as well, but that highly depends on the functionality. Usually such message require single acknowledgment after the alarm comes up. For more information about this loglevel, see sematext.

METHOD Critical (
 text : ZCore.ZString)

Inputs

text ZString

Debug

Adds an alarm according to the specification described in the Function-block.

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.

METHOD Debug (
 text : ZCore.ZString)

Inputs

text ZString

Error

Adds an alarm according to the specification described in the Function-block.

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.

METHOD Error (
 text : ZCore.ZString)

Inputs

text ZString

ErrorId

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.

METHOD ErrorId () : UDINT

Returns

UDINT

ErrorMessage

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.

METHOD ErrorMessage () : ZCore.ZString

Returns

ZString

ErrorSource

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.

METHOD ErrorSource () : ZCore.IError

Returns

IError

Fatal

Adds an alarm according to the specification described in the Function-block.

the log level that tells that the application encountered an event or entered a state in which one of the crucial business functionality is no longer working. A fatal log level may be used when the PLC booting process failed because some ethercat slave devices are not connected to the busmaster or the axes of the machine are not allowed to move because the machine detected the lubricant is missing. Usually such message require dual acknowledgment: first, when the alarm comes up and then again after fixing the problem.

METHOD Fatal (
 text : ZCore.ZString)

Inputs

text ZString

Info

Adds an alarm according to the specification described in the Function-block.

METHOD Info (
 text : ZCore.ZString)

Inputs

text ZString

LogMessageRef

This method may be used to create an alarm that is automatically acknowledged. Usually this method should not be used in an application, use one of the specialized methods instead (i.e. Debug, Trace).

The timestamp property is overwritten by the actual timestamp if timestamp=0.

METHOD LogMessageRef (
 timestamp : ULINT,
 text : REFERENCE TO ZCore.ZString,
 logLevel : ZCore.LogLevel)

Inputs

timestamp ULINT

unused, the timestamp can not be set externally for alarm, the datetime instance that has been injected during initisation (via construct (FB_init)) is used for this.

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

SetLevel

Sets the threshold of alarming to logLevel. Alarms that have the same severity level or higher will be emitted handled by the logger (others are ignored).

Note

Calling this method will unlink the logger instance from the pointer that has been passed with SetLevelRef The Logger uses whatever method was called last.

METHOD SetLevel (
 logLevel : ZCore.LogLevel)

Inputs

logLevel LogLevel

SetLevelRef

Sets the threshold of logged messages to LogLevelRef^. Since the passed value is a reference, it can be changed at any time externally. Alarms that have the same severity level or higher will be emitted handled by the logger (others are ignored).

Note

Calling this method will not effect the logLevel that has been set with SetLevel. The Logger uses whatever method was called last.

METHOD SetLevelRef (
 logLevelRef : REFERENCE TO ZCore.LogLevel)

Inputs

logLevelRef REFERENCE TO LogLevel

Trace

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.

METHOD Trace (
 text : ZCore.ZString)

Inputs

text ZString

Warning

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.

METHOD Warning (
 text : ZCore.ZString)

Inputs

text ZString