Help - HMI Protocol

Overview:

The HMI protocol is intended to support a web based HMI system. It supports:

Tag based data table access.
Automatic data conversion and scaling.
Events.
Alarms.

The HMI protocol is based on JSON. While it is primarily intended for HMI systems, it can also be used as a general purpose web service for other applications such as enterprise integration.

The protocol itself is not described in detail here. Please consult the help pages for the HMI system for more details. The following provides a brief overview.

The HMI system uses a protocol called "Cascadas" which was developed for the purpose.

HMI Servers and Services

The HMI protocol can be configured to provide multiple services. These are:

HMI (Standard) - This is the standard HMI service and includes an integrated web server for loading HMI web pages. It allows read/write access via the HMI protocol.
Restricted HMI - This provides access to the same HMI protocol as the standard version, except that access is read-only. This can be used to provide HMI access to users without providing them the ability to write to the system data table or acknowledge alarms.
RSS Monitoring - This provides an RSS feed of selected HMI events. This is available on both the standard and restricted HMI ports.
ERP Protocol - This is a limited version of the HMI protocol intended to allow access for ERP/MRP applications. The ERP version however limits the features available, and allows tag access to be limited.
Alarm and Event Database Access - The alarm and event database can be queried via a web service API. This does not use the HMI protocol, but is accessed via the HMI servers (both normal and restricted versions).

The normal and restricted HMI servers will use different IP ports. Any available port may be used for either. Both the normal and restricted HMI servers use the same HMI configuration.

Address Tags

Address tags are aliases for addresses in the system data table. They can be used when reading from or writing to individual addresses (or series of addresses) when using the HMI protocol. For example, the tag name "PB1" may be used to represent the system data table coil address 100.

Type Conversions

Different data types may be associated with a tag, including integers, floating point numbers and strings. Details of these may be found in the section on "HMI Configuration". However, it is suffice to say here that the HMI configuration system can be used to automatically convert between different data types. For example, numbers can be converted between integers and floating point, depending on what is required for the application.

Scaling

Numerical values can be automatically scaled to convert between raw analogue values and engineering units. For example, a 12 bit analogue number (0 to 4095) representing an LVDT reading could be scaled to read the equivalent value in millimeters. The same applies when converting values input from an HMI screen and being written back to the system data table. This scaling can be specified in the configuration and requires no special logic to be written to support it.

Reserved Tags

The protocol has several pre-defined "reserved" tags. These are:

timeutc - This is the current time as UTC. This is a floating point number representing a POSIX time stamp.
timelocal - This is the current time as local time on the server. This is also a POSIX time stamp.
clientversion - This is a string representing the current version of the client.
protocolversion - This is a string representing the version of the HMI protocol supported by the server.

Alarms

Alarms are messages which are brought to the attention of the operator and which the operator must acknowledge. Each alarm is associated with an "alarm tag". Each alarm tag is in turn associated with a coil address in the system data table. The HMI protocol provides alarm messages with the following features:

Alarm Tag - The alarm message passes the alarm tag to the HMI client (e.g. web page), not the actual alarm message. Associating the alarm tag with an actual text message is the responsibility of the HMI client. This means it is possible for the same HMI message to support multiple languages (e.g. both English and French) simultaneously.
Time - The time at which the alarm condition was detected is included in the message. This time is sent as UTC (GMT) so the system can operate independently of time zones.
Time OK - The time at which the alarm condition became "OK" (the cause is no longer present) is also part of the message.
State - The state of the alarm is also included (see below for an explanation of alarm states).
Count - The number of times that an alarm occured before "going away" is included. This means that if an alarm condition occurs multiple times before being corrected, the number of times this happens can be displayed to the operator. This allows alarms to be summarised in a compact and easy to understand form.

Acknowledging Alarms

Alarms must be acknowledged by the operator. Acknowledging an alarms means sending a message that the operator has been made aware of the alarm. This is accomplished by sending a message from the HMI client to the HMI server.

Alarm States

Alarms can be in the following states:

alarm - The alarm condition is true, and the alarm has not been acknowledged.
ackalarm - The alarm condition is true, and the alarm has been acknowledged.
ok - The alarm condition is false, but the alarm has not been acknowledged yet.
ackok - The alarm condition is false, and the alarm has been acknowledged.
inactive - The alarm condition is false, and the alarm has been acknowledged.

Alarm History

Once an alarm message has been acknowledged and the condition causing the alarm is no longer present, the alarm message itself goes into the "alarm history". The alarm history is available for viewing by the operator. The alarm history also includes which operator station acknowledged the alarm.

Triggering Alarm

Once an alarm has been defined in the HMI configuration it can be triggered by turning on the associated coil address in the system data table. The alarm address may be turned on by any source able to write to the system data table.

An alarm is present when the alarm adress is on (or "1", or "true").

Events

Events are similar to alarms in that they represent occurances which are brought to the attention of the operator. Unlike alarms, events do not require the operator to acknowledge them. While alarms normally represent problems which require the operator to take corrective actions, events are usually simply status information which the operator can review. Like alarms, events are associated with coil addresses in the system data table. Event messages include the following:

Event Tag - Like alarm messages, event messages include an "event tag" representing the event, but not the actual event message text. Again, the reason for this is to allow the HMI system to support multiple languages simultaneously.
Time - This is the time at which the event occured (in UTC).

Triggering Events

Once an event has been defined in the HMI configuration it can be triggered by turning on the associated coil address in the system data table. The event address may be turned on by any source able to write to the system data table.

Events are "edge triggered". That is, they are triggered when the event address changes from off to on (or "0" to "1", or "false" to "true").

On start up, the system initialses the event system with the current state of the event addresses. That means that events addresses which are initially "on" will not trigger an event until the event address turns "off" and then "on" again.

Alarm and Event Zones

Alarms, alarm history, and events are grouped into user defined "zones". These zones allow an individual HMI client to ask for and receive only those alarms or events of interest to it. Typical small to medium size HMI systems would normally simply group all alarms and events into a single set of zones (zone definitions for alarms and events are independent of each other). Larger HMI applications however may wish to use several different zones to represent different areas of a machine, production line, or plant.

Alarm and Event Serial Numbers

The system uses message serial numbers to track messages. The actual values used for these serial numbers is not significant and should not be relied on for any other purposes.

Supporting Multiple HMI Systems

The HMI protocol is designed to inherently support multiple HMI displays without requring any explicit coordination between them. This includes data, alarms, events, and alarm acknowledge messages.

Logging Alarm History and Events

Alarm history and events are automatically logged to a database. On start up, the system will retrieve the most recent set of alarm history and event messages from the database and make them available for an HMI client.

Current alarms are not logged in the database as they represent a dynamically changing condition. Once the alarm has become part of the alarm history however (the alarm condition is no longer present, and the operator has acknowledged it), it is automatically logged as part of the alarm history.

The contents of the database can be retrieved by other programs via a web service protocol. This protocol is documented as one of the sytem services.

Help Topics

Topic Details for Communications