Help - ERP Protocol

Overview:

The ERP protocol is a subset of the HMI protocol which is intended to allow access for ERP/MRP (Enterprise/Manufacturing Resource Planning) applications. This protocol uses the same configuration as the conventional HMI protocol, but limits the available features, and also allows the number of tags and the type of access (read or write).

Like the HMI server, the ERP server can automatically convert types, perform scaling, and enforce data ranges.

Web Service Protocols

The ERP protocol is a type of "web service protocol". A web service protocol operates over HTTP like a web page, but transfers machine readable data rather than a simple web page.

Basic Message Format

The ERP Protocol uses a subset of the HMI protocol using JSON over HTTP. JSON is a standard encoding of data for web services based on "keys" and "values".


	{"key1":123, "somekey":"value", "arrayexample":[1, 2, 3]}

Basic Message Request Format

The basic message format consists of the following:

id - This is a client ID string which is used to identify the client. The contents can be any string.
msgid - This is a sequential integer which is used by the client to track requests and responses. The server will echo this number back.


	{
	"id":"ERP Client 123.",
	"msgid":456,
	}

Basic Message Response Format

The basic response format contains the following:

id - This is the server ID string which as defined in the HMI configuration.
msgid - This is an echo of the msgid value sent by the client.
stat - This is a string representing a status or error code.


	{
	"id": "HMIServer demo server",
	"msgid": 456,
	"stat": "ok",
	}

Status Codes

unauthorized - The client is not authorized to communicate with the server.
protocolerror - An error was encountered in the protocol and it could not be accepted. The entire message was discarded by the server.
commanderror - A request command field provided incorrect or invalid data. Check each possible error response for any errors. Multiple errors are possible.
servererror - An unspecified error has occurred in the server which prevents the request from being completed. The error is not specified in any of the return fields.
ok - No errors.

Read Command

The read command specifies which address tags should be read. It consists of a list of the address tag names which the client wishes to read. This command is optional and can be left out if it is not needed.

Request


	{
	"id":"ERP Client 123.",
	"msgid":456,
	"read" : ["Tank1Level", "WidgetCount"],
	}

Response


	{
	"id": "HMIServer demo server",
	"msgid": 0,
	"stat": "ok",
	"timestamp": 1238156675.0,
	"read": {"Tank1Level": 9875, "WidgetCount" : 87},
	}

Write Command

The write command is a group of address tags and values which are to be written to the server.

Request


	{
	"id":"ERP Client 123.",
	"msgid":456,
	"write" : {"Pump1Speed" : 2250},
	}

Response


	{
	"id":"ERP Client 123.",
	"msgid":456,
	}

Combined Read/Write

Reads and writes can be combined in a single transaction.

Request


	{
	"id":"ERP Client 123.",
	"msgid":456,
	"read" : ["Tank1Level", "WidgetCount"],
	"write" : {"Pump1Speed" : 2250},
	}

Response


	{
	"id": "HMIServer demo server",
	"msgid": 0,
	"stat": "ok",
	"timestamp": 1238156675.0,
	"read": {"Tank1Level": 9875, "WidgetCount" : 87},
	}

Read and Write Errors

Read and write errors are reported in the "readerr" and "writeerr" fields in the response. The "readerr" and "writeerr" fields are only present in the response if there is a corresponding error to report.


	{
	"id": "HMIServer demo server",
	"msgid": 9875,
	"stat": "commanderror",
	"timestamp": 1238156675.0,
	"writeerr": {"PBBad": "tagnotfound"}
	}

Error codes:

accessdenied - The client does not have authorization to access this tag.
tagnotfound - The address tag is not recognized by the server.
writeprotected - An attempt was made to write to an address which is write protected or otherwise not writable.
badtype - The data value is of an incompatible type and cannot be converted to the desired type.
outofrange - The data value is out of range. Range limits may be imposed by the server based on data type or through configuration limits imposed on a per-tag basis.
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.

Configuration

The ERP server uses the same tag configuration as the HMI server. However, the ERP server has the following limits on it:

It on supports the "read" and "write" commands. None of the other commands (e.g. alarms, events, etc.) are supported.
Only those tags which are specified as being available to the ERP server can be accessed by it.
The tags which are configured as being available to the ERP server can be designated as read or write (or both). Tags which are designated as "read" but are not designated as "write" cannot be written to.
Conversely, tags which are not designated as "read" cannot be read even if they can be written to (marked "write"). A tag is read-write if the ERP configuration lists it as both "read" and "write".
If the underlying memory type is not writable, list a tag as "write" for ERP purposes will not make the tag writable, and you will still receive an error when you attempt to write to it.

Configuration syntax can be found in the section on HMI configuration, and also in the section on using the status web interface for form based configuration.

Creating an ERP Client Interface

To create a custom client interface to the ERP server, you need the following:

A JSON library. These are available for almost all languages and are standard in many.
The ability to make an HTTP POST request to a URL. This is also a very common feature for modern programming languages

You then need to do the following:

Find which server "tags", and make any additions or changes to them which are necessary. This is part of the server HMI configuration.
Add the tags to the ERP configuration in the server HMI configuration file. To make the changes active, you may need to reload the server configuration (this can be done while the system is running).
Construct the request message and encode it as JSON. You can combine read and write commands in the same message.
Make an HTTP POST request to the server, using the appropriate URL. The server port is configurable. The JSON message should be attached to the request as content.
The server will respond with the data attached as content.
Decode the response JSON.
Check to see if the response "stat" is "ok". If it is not, an error is present.
You may check the "msgid" to see if it matches the version sent in the request.
If an error ws present ("stat" was not "ok"), check the "readerr" and "writeerr" fields for the reason. Errors are normally caused by attempting to use a tag which does not exist or which is write protected, or by attempting to write a value which is of an incompatible type or out of range. The server can be configured to enforce data ranges on a per-tag basis.

Example Client

The following is an example ERP client written in Python.


	#!/usr/bin/python
	# This shows a basic demo for an ERP client.
	# This will work with the standard HMI demo.
	# 29-Dec-2010.

	import json
	import urllib2

	# This is the data we are going to send to the server.
	# We need a client id, and a message id. In addition, if we want to 
	# read data, we need to include a list of the tags we want to read. If we want to
	# write data, we need to include a dictionary with the tags and values that we
	# want to write.
	basicdemo = {
	  'id' : 'ErpDemo',
	  'msgid' : 0,
	  'read' : ['PL1', 'PL4', 'PumpSpeedActual', 'PumpSpeedCmd', 'Tank1Level', 
	  			'Tank2Number', 'hello', 'ButtonDisPB'],
	  'write' : {'PB1' : 1, 'PumpSpeedCmd' : -2, 'writebad' : 777, 'SSPPGrip' : 1}
	}

	# Encode the dictionary into JSON format using the standard Python library.
	JsonOut = json.dumps(basicdemo)

	# Send the data using POST. 
	req = urllib2.Request(url = 'http://localhost:8084/', data = JsonOut)
	f = urllib2.urlopen(req)

	# Read the response.
	JsonIn = f.read()

	# Convert from JSON into a dictionary. 
	respdata = json.loads(JsonIn)

	# We will iterate through the 'read' response and show the values that we read.
	# The dictionary will also contain other data (such as errors) which are not 
	# showing here. 
	print('Read response was')
	readdata = respdata.get('read', {})
	for tag, value in readdata.items():
		print('\tTag: %s  Value: %s' % (tag, value))

	# Read errors.
	readerr = respdata.get('readerr', {})
	if readerr:
		print('\nRead errors')
		for tag, value in readerr.items():
			print('\tTag: %s  Value: %s' % (tag, value))

	# Write errors.
	writeerr = respdata.get('writeerr', {})
	if writeerr:
		print('\nWrite errors')
		for tag, value in writeerr.items():
			print('\tTag: %s  Value: %s' % (tag, value))

The output from the above is (when used with the standard HMI demo configuration):


	Read response was
		Tag: PumpSpeedActual  Value: 5
		Tag: PL4  Value: 0
		Tag: PumpSpeedCmd  Value: -2
		Tag: PL1  Value: 1
		Tag: Tank2Number  Value: 75.0
		Tag: Tank1Level  Value: 70

	Read errors
		Tag: ButtonDisPB  Value: accessdenied
		Tag: hello  Value: tagnotfound

	Write errors
		Tag: SSPPGrip  Value: accessdenied
		Tag: writebad  Value: tagnotfound

Help Topics

Topic Details for Communications

Help - ERP Protocol

Overview:

Web Service Protocols

Basic Message Format

Basic Message Request Format

Basic Message Response Format

Status Codes

Read Command

Request

Response

Write Command

Request

Response

Combined Read/Write

Request

Response

Read and Write Errors

Error codes:

Configuration

Creating an ERP Client Interface

Example Client