Help - HMI Client Protocol Library

Overview:

The HMI protocol client Javascript library comes in two parts. These are the JSON encoding library and the HMI protocol library itself.

JSON and the HMI System:

JSON is a standard data encoding format used in web applications. The HMI messages are encoded in JSON format. The HMI system can use standard JSON encoding libraries such as "json2.js" from JSON.ORG. With the increasing popularity of JSON, future versions of web browsers are expected to support it natively without requiring a separate Javascript library.

HMI Communications Library:

The HMI communications library is implemented as a single Javascript object. This library ("libhmiclient.js") does more than just support the HMI protocol. It provides the following features:

Encoding and decoding of messages using the HMI protocol.
Buffered HMI reading and writing functions.
Event and alarm handling.
Automatic update of screen displays.

The Read List:

The "read list" is an array of tag names that are to be polled (read) on a regular basis. The "read list" is a critical part of an application, because it defines what data is available to the client for display.


	Example - 

	// Make a list of all the address tags to be monitored. This is what we
	// send to the server asking for values.
	var ReadList = ["PL1", "PL2"];

This creates a new object called MBHMIProtocol, which polls "localhost" at port 8503 to read the tags in ReadList.

There should only be one HMI communications object in an application that takes care of all polling.

The "same origin" security policy in most web browsers requires that a web client application can only communicate with the same host that the web page was loaded from. This means that a single server must be used as the source of the web page and as the source (and destination) of all data.

The Zone List:

The "zone list" is an array of zone names that defines the alarms and events that are to be monitored.


	Example - 

	// Make a list of the alarm and event zones to be monitored. Zones are
	// used to filter alarms and events to only those we are interested in. 
	var AlarmZoneList = ["zone1", "zone2", "zone3"];
	var EventZoneList = ["zone1", "zone2", "zone3"];

The Display List:

The display list is an array of code objects which control graphics, text, tables, etc. "UpdateDisplay" calls each item in turn, passes it the latest data, and asks it to update itself. Each screen item must be a code object which exports a method called "UpdateScreen", and which accepts one parameter. e.g. "objref.UpdateScreen(presentstate);"

To add an item to the display list, create the object and pass it to "AddToDisplayList".


	For example - 
	
		// This defines a pilot light control.
		var PL1 = new MB_PilotLight("green", "red", "black", "PL1", document);
		MBHMIProtocol.AddToDisplayList(PL1, "PL1", "read");

This creates a pilot light using "MB_PilotLight" (part of another library), assigns it to a reference called PL1, and passes it to "AddToDisplayList" along with two other parameters.

The second parameter is the "address label". This is used by instructions which need to read the input values. This should be a valid tag from the read list whenever the address label is "read". Its value is not significant for other address labels.

The third parameter is the "tag type". This is a description of the type of address used in the second parameter. This determines the source of the data which is passed to the dislay item. Valid value are: "read" (input data from the read list), "timestamp" (the server time stamp from the last message), "stat" (the server stat value from the last message), "msgid" (the message id returned by the server), "events" (an array of the latest event messages), and "alarms" (an object containing alarms and alarm acknowledgements).

Alarms and alarm acknowledgements are contained in a single object in order to fit both within the single parameter limit. This object has the following form : {"alarms" : this._AlarmBuffer, "alarmsupdated" : this._AlarmsUpdated, "alarmack" : this._AlarmAckBuffer, "alarmackupdated" : this._AlarmAckUpdated};

In this example, "alarms" is the alarm input buffer. "alarmsupdated" is an integer that increments whenever new alarms have arrived. "alarmack" is the alarm acknowledgement input buffer. "alarmackupdated" is an integer that increments whenever new acknowledgement messages have arrived.

Initialisation:

HMIClient(url, port, cid, readlist, alarmzonelist, eventzonelist, ansyncoption);

This is the object name and the initialisation parameters.

url = The url (address) of the server, including address and path.
port = The IP port of the server.
cid = The client ID string.
readlist = The IO read list.
alarmzonelist (array) - List of alarm zone filters.
eventzonelist (array) - List of event zone filters.
ansyncoption = If true, uses asynchronous communication. If false, uses synchronous communications.

The web browser will enforce a security policy requiring that the communications between the HMI web page and the server must be to the same host (address) and port as the web page was loaded from. This means the communications library needs to know the host name and port. This can be accomplished in several ways. One way is to hard code these values. However, that means they must be known in advance.

The other way is to use a standard Javscript object to obtain these values automatically. These are:

window.location.hostname - This automatically obtains the host name (address).
window.location.port - This automatically obtains the port number.

You must also decide whether to use synchrnous or asynchronous communications. With synchronous communications, the web browser waits for the server to reply before continuing. With asynchronous communications, the web browser does not wait. Rather, it sends the request and continues running the browser script. When the response from the server is received, the software function which handles the response is automatically called and the display list is updated.

When the web browser and the server are communicating on a reliable local network (or on the same computer), there is normally no noticable difference between the two methods. However, if the network is slow or unreliable, using the synchronous method can cause the web browser to appear to "stall" or be unresponsive. Also, if the server is stopped and restarted for some reason, the web page will require a reload (press "F5" or click on the "reload" icon) before communications will resume.

When asynchronous communications is used, these problems will not occur. The communications library will automatically keep retrying communications. However, some versions of some web browsers when running on some operating systems may have bugs or other problems which prevent asynchronous communications from working correctly. This rarely occurs. However, since applications using asynchronous communications are relatively new, this feature is not as well tested in all browsers as the synchronous method. If problems are encountered when using asynchronous communications, it is suggested to try setting the "ansyncoption" parameter to "false" to see if the synchronous method will work instead.


	// Make a list of all the address tags to be monitored. This is what we
	// send to the server asking for values.
	var ReadList = ["PL1", "PL2"];

	// Make a list of the alarm and event zones to be monitored. Zones are
	// used to filter alarms and events to only those we are interested in. 
	var AlarmZoneList = ["zone1", "zone2", "zone3"];
	var EventZoneList = ["zone1", "zone2", "zone3"];

	/* This handles communications with the server. 
	The parameters are: 
		1) The host name the web page was loaded from.
		2) The port number the web page was loaded from. 
		3) The client ID string.
		4) The list of tags to poll for data.
		5) The list of alarm zones to poll for new alarms.
		6) The list of event zones to poll for new events.
		7) true = Enable asynchronous communications.
	The first two parameters use a standard Javascript feature.
	Alternatively, these can be hard coded values if the host
	and port are known in advance.
	*/
	var MBHMIProtocol = new HMIClient(window.location.hostname, 
				window.location.port, "Any client name string.", 
				ReadList, AlarmZoneList, EventZoneList, true);

Reading and Writing:

AddWrite(writetag, writeval);

writetag = The tag to write to.
writeval = The value to write
Adds a write request to the output queue.


	MBHMIProtocol.AddWrite("PumpSpeedCmd", PumpSpeed);

WriteImmediate(writetag, writeval);

writetag = The tag to write to.
writeval = The value to write.
Similar to AddWrite, but instead of simply adding a request to the write queue, it forces an immediate polling cycle and screen update.


		// Stop the pump.
		if (ButName == "PBStop") {
			PumpSpeed = 0;
		}
		// Update the new pump speed.
		MBHMIProtocol.WriteImmediate("PumpSpeedCmd", PumpSpeed);

WriteToggleImmediate(writetag, reftag);

writetag = The tag to write to.
reftag = The reference tag.
Similar to WriteImmediate, but instead of simply writing a value, it sets the value of a tag to the boolean opposite of that found in a reference tag.


	MBHMIProtocol.WriteToggleImmediate('PB2', 'PL2');

WriteIncImmediate(writetag, reftag, incval, inclimit);

writetag = The tag to write to.
reftag = The reference tag.
incval = The amount to increment by. This must be a numeric value. This may be negative.
inclimit = The absolute value of the increment limit. This must be a numeric value.
Similar to WriteImmediate, but instead of simply writing a value, it reads the value stored in "reftag", increments it by the number "incval", and stores the result in "writetag". "reftag" and "writetag" may be the same. If the absolute value of the result exceeds the number "inclimit", the result is set to zero.


	MBHMIProtocol.WriteIncImmediate('PB4', 'PL4', 1, 6);

function GetServerID()

Read the value of the id string.

function GetMsgStat()

Read the value of the current message status.

GetRead(readlabel);

readlabel = The tag to read.
Reads a value from tag address "readlabel". The value returned is the most recent value in the input buffer.


		var PumpSpeed;
		// First, get the current pump speed.
		PumpSpeed = MBHMIProtocol.GetRead("PumpSpeedActual");

GetTimeStamp();

This returns the most recent server time stampe. The value returned is the one from the most recent message.


		var TimeStamp = MBHMIProtocol.GetTimeStamp();

Event and Alarm Handling:

AddAlarmAck();

This adds the alarm at the head of the alarm queue (the oldest unacknowledged alarm) to the output queue.


	MBHMIProtocol.AddAlarmAck();

Display Control:

AddToDisplayList(objref, addrlabel, tagtype);

objref = A reference to the display object.
addrlabel = If the tagtype is "read", this is the address label the display object is attached to. If the tagtype is not "read", the value in this parameter is ignored.
tagtype = The type of tag.

This adds an HMI display Javascript object to the display list. The "addrlabel" must be a valid tag which is part of the read list. The "tagtype" is a string, and may be "read", "timestamp", etc. (see below). Each of these tag types refers to a valid HMI field from which it derives its data.

The display list is automatically updated whenever new data is received from the server.


	// This defines a pilot light control.
	var PL1 = new MB_PilotLight(document, "PL1", "black", "green", "red");
	var PL2 = new MB_PilotLight(document, "PL2", "black", "green", "red");

	// Now, add each of these screen objects to the list of things to update.
	MBHMIProtocol.AddToDisplayList(PL1, "PL1", "read");
	MBHMIProtocol.AddToDisplayList(PL2, "PL2", "read");

	// This is for the alarm status display on the main screen.
	var AlarmStat = new MB_PLMultiColour(document, "AlarmStat", 
				"black", ["white", "green", "orange", "red"]);
	MBHMIProtocol.AddToDisplayList(AlarmStat, "", "unackalarm");

HMI Tag Types:

read - Use the data from the tag given as the second parameter.
timestamp - The message time stamp.
serverid - The server id.
stat - The message "stat" parameter.
msgid - The message id number.
alarms - The alarms.
alarmhistory - The alarm history.
events - The events.
errors - The errors.
status - The message status.
chkalarm - Check if alarms present (see below).

For "chkalarm" alarms, the HMI display object will be passed the following values:

0 - No current alarms present.
1 - At least one unacknowledged alarm in the "ok" state.
2 - At least one acknowledged alarm is still active ("ackalarm").
3 - At least one unacknowledged alarm in the "alarm" state.

Higher number codes take priority over lower numbered codes.

Polling Cycle Control:

SendRequest();

This triggers a communications polling cycle. However, it does not schedule the polling request. Scheduling the polling request must be done by other means. Typically, you would use "setTimeout", which is a standard web page Javascript event. In the example below, the function "RunScanCycle" is being scheduled again in 1000 milliseconds.

The polling time to use will be a compromise between several factors. If the time between polls is too long, there will be a noticable lag between a physical event happening and indication of it on the display. If the time between polls is too short, the load on the computer displaying the HMI client (and possibly the server as well) will be too high.

Also, if asynchronous polling is used, and if the time between polls is too short, the server will not have had enough time to respond before the client begins to send the next poll. If this happens, the connection will be aborted and the client will not receive the reply. In these cases, it is better to either use synchronous communcations (this is set via an initialisation parameter) or to use a slower polling rate.


	// Run all the operations required each scan cycle.
	function RunScanCycle() {

		// Query the server for updates.
		MBHMIProtocol.SendRequest();

		// Call the function back again at the set interval.
		window.setTimeout("RunScanCycle()", 1000);
	}

Communications Watchdog:

CommsWatchDogTimeOut(limit);

limit = The amount of difference permitted between the number of messages sent and received before an error is reported.

This function is useful only when using asynchronous communications. The "SendRequest" function keeps track of the number of requests sent and received. If too many consecutive requests are sent without a response from the server, "CommsWatchDogTimeOut" will return "true". This may be used to annunciate a loss of communications on the screen. The count of requests is automatically reset every time a response is received, so an occasional loss of messages will automatically correct itself when the next response is received.

If communications is lost, a valid response message will not be received, which in turn means the display list will not be called to update itself. If you wish to display a message to the operator, you should call the appropriate function directly yourself. If you are using one of the client display library functions, you may do this by called the "UpdateScreen") method directly.

This method is an alternative to using the watchdog list. The watchdog list method using "SetCommsWatchDogTimeOut" and "AddToWatchdogList" is recommended for most normal applications.


	// Run all the operations required each scan cycle.
	function RunScanCycle() {

		// Query the server for updates.
		MBHMIProtocol.SendRequest();

		// Check the comms watch dog counters.
		ComsTimeOut = MBHMIProtocol.CommsWatchDogTimeOut(10);
		if (ComsTimeOut) {
			CommWD.UpdateScreen(1);
		} else {
			CommWD.UpdateScreen(0);
		}

		// Call the function back again at the set interval.
		window.setTimeout("RunScanCycle()", 1000);
		
	}

SetCommsWatchDogTimeOut(limit);

limit = limit (integer) - The amount of difference permitted between the number of messages sent and received before an error is reported. This is a count, not a time value.

Set the limit to be used when checking the communications watchdog limit via the watchdog list. The watchdog function checks if responses are being received from the server by comparing a communications counter to the limit.


	// Set the watchdog limit to 10 scans.
	MBHMIProtocol.SetCommsWatchDogTimeOut(10);

AddToWatchdogList(objref);

objref = A reference to the display object.

Add an item to the watchdog list. This is similar to the "display list" but is only for the communications watchdog counter. Objects on this list are scanned and automatically updated each time a request is sent. The watchdog function passes a 1 to the display function if the communications watchdog counter has exceeded the limit, or 0 otherwise.


	// This is for the communications watch dog display. 	
	var CommWD = new MB_PilotLight(document, "CommWatchDog", "black", "green", "red");
	// This is the watchdog list, not the regular display list.
	MBHMIProtocol.AddToWatchdogList(CommWD);

Help - HMI

Help Topics

Topic Details for HMI