Help Topics

HMI Client Libraries

Help - HMI Client Event Library

Overview:

The HMI system is based on open standards such as JSON, Javascript, SVG, and HTML. The HMI client event library is not required to build a web based HMI which can interact with the HMI server. However, the HMI client events library provides a number of useful functions which make creating web based HMI systems easier. These functions are documented below.

The client event library ("libmbevents.js") is implemented as a series of independent objects. Most of these objects are designed to be compatible with the HMI communications library "display list".

Event Display:

"Events" is the standard term for occurances which an operator must be notified of, but which does not require acknowledgement.

Parameters:

eventdoc - A reference to the HTML document.
eventtableID (string) - The id of the html table used to display events.
maxlength (integer) - The maximum number of rows to display.
eventtexts (array) - An array of strings with the event messages.


	function MB_EventDisplay(eventdoc, eventtableID, maxlength, eventtexts)

MB_EventDisplay requires one table with four columns. For example -


	<table id="EventDisplay" border="5" cellpadding="5">
	<tr>
	<td><b>Event #:</b></td> 
	<td><b>Date:</b></td> 
	<td><b>Event:</b></td> 
	<td><b>State:</b></td>
	</tr>
	</table>

The first column will be the Event number. The second column is the date, the third column is the event name, and the fourth column is the event state. These column assignments are fixed, and cannot be changed without editing the code.

The Javascript code to display events is shown below.


	// This is to display the events.
	var EventDisplay = new MB_EventDisplay(document, "EventDisplay", 50, event_text);
	// Add this to the display list.
	MBHMIProtocol.AddToDisplayList(EventDisplay, "events", "events");

The texts displayed on the screen are not carried in the actual messages, but must be provided by the client. The messages are expected to be in object literals with the message tags acting as keys to the actual messages. An easy way of implementing this is to put the messages into external Javascript files containing just the data definitions. For example:


	event_text = {
	"PumpRunning" : "Tank pump is running.",
	"PumpStopped" : "Tank pump is stopped.",
	"Tank1Empty" : "Tank 1 is empty.",
	"Tank1Full" : "Tank 1 is full.",
	"Tank2Empty" : "Tank 2 is empty.",
	"Tank2Full" : "Tank 2 is full."
	}

Alarms Display:

"Alarms" is the standard term for occurances which an operator must be notified of, and which must be acknowledged.

Parameters:

alarmdoc - A reference to the HTML document.
alarmtableID (string) - The id of the html table used to display alarms.
alarmtexts (object) - An object of strings with the alarm messages.
alarmstatetexts (object) - An object of strings with the alarm states.
alarmcolour (string) - The HML colour to indicate alarm conditions.
ackcolour (string) - The HML colour to indicate acknowledged conditions.
okcolour (string) - The HML colour to indicate OK conditions.


	function MB_AlarmDisplay(alarmdoc, alarmtableID, alarmtexts, alarmstatetexts,
		alarmcolour, ackcolour, okcolour)

MB_AlarmDisplay requires one table with five columns. For example -


	<table id="AlarmDisplay" border="5" cellpadding="5">
	<tr> 
	<td><b>Alarm:</b></td>
	<td><b>Alarm State:</b></td>
	<td><b>Time:</b></td> 
	<td><b>Time OK:</b></td> 
	<td><b>Count:</b></td>
	</tr>
	</table>

The first column will display the name of the alarm. The second column will display the alarm state. The third column will display the time at which the fault was detected. The fourth column will display the time at which the fault became OK. The fifth column will display the number of times the fault occured while the alarm was displayed.

The Javascript code to display alarms is shown below.


	// This is to display the alarms.
	var AlarmDisplay = new MB_AlarmDisplay(document, "AlarmDisplay", 
		alarm_text, alarmstates_text, "red", "orange", "green");
	// Add this to the display list.
	MBHMIProtocol.AddToDisplayList(AlarmDisplay, "alarms", "alarms");


	alarm_text = {
	"PB1Alarm" : "PB1 was pressed.",
	"PB2Alarm" : "PB2 was pressed.",
	"PB3Alarm" : "PB3 was pressed.",
	"PB4Alarm" : "PB4 was pressed."
	}

The texts used to describe the alarm states are not carried in the actual messages, but must be provided by the client. The messages are expected to be in object literals with the message tags acting as keys to the actual messages. An easy way of implementing this is to put the messages into external Javascript files containing just the data definitions. For example:


	alarmstates_text = {
	"alarm" : "Fault is active",
	"ackalarm" : "Alarm acknowledged",
	"ok" : "Fault cleared",
	"ackok" : "Fault cleared and acknowledged",
	"inactive" : "Alarm inactive"
	}

MB_AlarmDisplay does not provide a function to input the alarm acknowledge action. However an appropriate function is provided in the libhmiclient library which can be attached to a button on the screen.


	<!-- Push button to acknowledge alarms. -->
	<g transform="translate(50, 10)" onclick="MBHMIProtocol.AddAlarmAck();">
	
		<!-- Put some SVG or other suitable mark up in here to display a button -->
	
	</g>

Alarms History Display:

"Alarms" is the standard term for occurances which an operator must be notified of and acknowledge. Alarm history is a record of past alarms.

Parameters:

alarmhistorydoc - A reference to the HTML document.
alarmhistorytableID (string) - The id of the html table used to display alarm history.
maxlength (integer) - The maximum number of rows to display.
alarmtexts (array) - An array of strings with the alarm messages.


	function MB_AlarmHistoryDisplay(alarmhistorydoc, alarmhistorytableID, maxlength, alarmtexts)

MB_AlarmHistoryDisplay requires one table with four columns. For example -


	<table id="AlarmHistoryDisplay" border="5" cellpadding="5">
	<tr>
	<td><b>Alarm:</b></td>
	<td><b>Alarm Time:</b></td> 
	<td><b>Time OK:</b></td> 
	<td><b>Ack By:</b></td> 
	</tr>
	</table>

The first column is the alarm name. The second column will display the time at which the fault was detected. The third column will display the time at which the fault became OK. The fourth column will display who (which client ID) acknowledged the alarm.

The Javascript code to display alarm history is shown below.


	// This is to display the alarm history.
	var AlarmHistoryDisplay = new MB_AlarmHistoryDisplay(document, 
		"AlarmHistoryDisplay", 50, alarm_text);
	// Add this to the display list.
	MBHMIProtocol.AddToDisplayList(AlarmHistoryDisplay, "alarmhistory", "alarmhistory");


	alarm_text = {
	"PB1Alarm" : "PB1 was pressed.",
	"PB2Alarm" : "PB2 was pressed.",
	"PB3Alarm" : "PB3 was pressed.",
	"PB4Alarm" : "PB4 was pressed."
	}

Error and Status Display:

Error and Status display shows protocol errors and communications status in HTML tables. These require that certain HTML tables already exist for them to be associated with. They then add and remove rows of data to or from these tables to display logs of communications errors.

Errors and communications status are not buffered in the server. Reloading the browser will cause the existing record to be erased.

MB_TagErrorDisplay requires one table with three columns. The first column will be the current date and time. The second column is the name of the tag which encountered an error, and the third column is the text description of the error. These column assignments are fixed, and cannot be changed without editing the source code.

MB_TagErrorDisplay(errordoc, errortableID, maxlength, errortexts)

Display protocol errors on an HTML screen. Parameters:

errordoc - A reference to the HTML document.
errortableID (string) - The id of the html table used to display errors.
maxlength (integer) - The maximum number of rows to display.
errortexts (array) - An object with the error messages.


	// This is to display the communications errors.
	var ErrorDisplay = new MB_TagErrorDisplay(document, "ErrorDisplay", 50, error_text);
	// Add this to the display list.
	MBHMIProtocol.AddToDisplayList(ErrorDisplay, "errors", "errors");

MB_StatusLogDisplay requires one table with three columns. The first column will be the current date and time. The second column is the name of the status code, and the third column is the text description of the status code. These column assignments are fixed, and cannot be changed without editing the source code.

MB_StatusLogDisplay(statusdoc, statustableID, maxlength, statustexts)

Display protocol status conditions on an HTML screen. Parameters:

statusdoc - A reference to the HTML document.
statustableID (string) - The id of the html table used to display status.
maxlength (integer) - The maximum number of rows to display.
statustexts (array) - An object with the status messages.


	// This is to display the communications status log.
	var StatusLogDisplay = new MB_StatusLogDisplay(document, "StatusDisplay", 50, status_text);
	// Add this to the display list.
	MBHMIProtocol.AddToDisplayList(StatusLogDisplay, "status", "status");

The text for the descriptions are not carried in the actual messages, but must be provided by the client. The text of the descriptions are expected to be in object literals with the message tags acting as keys to the actual messages. An easy way of implementing this is to put the messages into external Javascript files containing just the data definitions. For example:


	error_text = {"tagnotfound" : "The address tag is not recognised by the server.",
	"badtype" : "The data value is of an incompatible type.",
	"outofrange" : "The data value is out of range.",
	"writeprotected" : "An attempt was made to write to an address which is write 
		protected or otherwise not writable.",
	"addresserror" : "An error occurred in attempting to map the tag to the 
		internal server address representation.",
	"servererror" : "An unspecified error has occurred in the server which prevents 
		the request from being completed.",
	"accessdenied" : "The client does not have authorisation to access this tag. "
	}
	
	status_text = {
	"ok" : "No errors.",
	"protocolerror" : "An error was encountered in the protocol and the entire message 
		was discarded by the server.",
	"commanderror" : "A request command field provided incorrect or invalid data.",
	"servererror" : "An unspecified error has occurred in the server which prevents 
		the request from being completed.",
	"unauthorised" : "The client is not authorised to communicate with this server.",
	"noclistempty" : "The client attempted to read using NOC without an NOC list being 
		present in the server."
	}