Get MBLogic at SourceForge.net. Fast, secure and Free Open Source software downloads

Help Topics

Topic Details for Communications

Help - MB-REST

Overview:

The MB-REST web service protocol is considered to be obsolete and should not be used. It will eventually be removed and replaced by a simpler and more effective protocol.

The MB-REST web service protocol does not support expanded register maps.

The MB-REST web service protocol provides access to the data table (memory array) using an HTTP (web) protocol which is modelled after the Modbus protocol. This protocol is intended for applications such as "enterprise integration" (e.g. connecting to an MRP/ERP system). If you are not interested in applications of that nature, you can probably skip this section.

The web service described here is based on REST principles using GET and POST to read and write data. The web service protocol is designed to be similar to the Modbus protocol. If you are familiar with Modbus, this web service should be easy to use.

Web Service Concepts:

A true web service (as opposed to just tunneling a remote procedure call over HTTP) treats resources as web pages. This means for example that you can examine the resources using a web browser.

The web service protocol described here treats each data table address as if it were a web page. Since the Modbus function code is inherently part of the address (it determines whether coils, discrete inputs, or registers are being addressed), the function code plus the data table address form part of the address URL. Other parameters, such as quantity, transaction ID, and unit ID are treated as parameters, rather than part of an actual address.

Following normal web conventions, functions which read data and have no side effects are accessed using HTTP GET. Functions which write data or otherwise have side effects are accessed using HTTP POST. GET and POST data are returned and POST data is sent in XML documents which may be machine parsed.

Reading Data:

To read data requires an HTTP GET similar to the following: 


	"http://host/modbus/function-code/address?qty=x&tid=y&uid=z"

Where:

Supported MB-Rest Function Codes:

Examples:

Example 1: This will return 32 coils starting at address 64, with a transaction ID of 67 and a unit ID of 1. 


	http://localhost:8080/modbus/1/64?qty=32&tid=67&uid=1

Example 2: This will return 18 holding registers starting at address 0. 


	http://localhost:8080/modbus/3/0?qty=18&tid=68&uid=1

Example 3: This will return 1 input register at address 32000. 


	http://localhost:8080/modbus/4/32000

Writing Data:

To write data requires an HTTP POST similar to that used for reading data.

Example: 


	http://host/modbus/function-code/address?qty=x&tid=y&uid=z"

In addition, it requires an XML document to be sent containing the data to be written. The document is embedded in the headers labelled as "modbusrest". The document would be in the following form. 

	<?xml version="1.0" encoding="utf-8" ?>
	<request>
		<protocol>modbusrest_v1.0</protocol>
		<msgdata>10010001</msgdata>
	</request>

The data is contained between the "msgdata" tags (see below for an explanation of data formats).

Supported MB-Rest Function Codes:

Server Response:

A successful call will return an XML document in one of the following formats:

Example 1 - Response to a successful request to read data using function 1: 

	<?xml version="1.0" encoding="utf-8" ?>
	<response status="ok">
		<transactionid>67</transactionid>
		<protocol>modbusrest_v1.0</protocol>
		<unitid>1</unitid>
		<functioncode>1</functioncode>
		<msgdata>10010001</msgdata>
	</response>

Example 2 - Response to a successful request to read data using function 3: 

	<?xml version="1.0" encoding="utf-8" ?>
	<response status="ok">
		<transactionid>68</transactionid>
		<protocol>modbusrest_v1.0</protocol>
		<unitid>1</unitid>
		<functioncode>3</functioncode>
		<msgdata>f12d001a</msgdata>
	</response>

The "function" value will be an echo of the function code sent as in a normal Modbus response message. The "transactionid" and "unitid" will also be and echo of the values sent, or else the default values if these were omitted in the request. "protocol" identifies the protocol name and version.

The "msgdata" will be the returned data (see below for an explanation of data formats). For read functions, this will be the requested data. For write functions, this will be the quantity of elements written (or for function 5, an echo of the data sent).

A failed call will return an XML document in the following format: 

	<?xml version="1.0" encoding="utf-8" ?>
	<response status="fail">
		<transactionid>68</transactionid>
		<protocol>modbusrest_v1.0</protocol>
		<unitid>1</unitid>
		<functioncode>133</functioncode>
		<msgdata>3</msgdata>
	</response>

The "function" and "msgdata" values will normally follow the Modbus protocol rules for exceptions for error code and exception respectively. However, where no comparable Modbus exception code may apply, the function and exception codes will both be returned as "0". Also however, see the sections on "HTTP Errors" and "Modbus Exceptions".

XML Document Tags:

The XML document tags are defined as follows:

Data Formats:

For coil or discrete input data is represented as a string of "0" and "1" characters. The first (left most) character is the value at the requested address, with additional values continuing to the right. As in a normal Modbus response, the number of values returned will be a multiple of 8 with the message padded out with extra "0" characters as necessary. Example: 10010001

For register data, the characters are in groups of 4, with each group representing one register. The right most character in each group is the least significant digit. The first (left most) group is the value at the requested address, with additional register values continuing to the right. Example: f12d001a

For function 5 (write single coil), the coil data is represented as "0000" (for "off"), or "FF00" (for "on") as with normal Modbus.

For hexadecimal data, characters may be represented as either upper or lower case.

HTTP Errors:

For HTTP errors (as opposed to Modus exceptions), a standard HTTP error code will be returned (e.g. 404). When an HTTP error code is returned, there will be no XML document accompanying it. There may be a descriptive HTML document, but this is for human consumption only and should not be parsed for error information. The contents of this HTML document may be locale dependent.

Modbus Exceptions:

The regular Modbus protocol defines certain errors as being "exceptions". This web service protocol deals with exceptions in the following manner:

Limits on Message Size:

The protocol follows the normal Modbus limits on the number of coils, discrete inputs, or registers which may be sent or received in a single request or response. These limits for a single message are:

Protocol Speed and Overhead:

Like all web service protocols, this one is slower and has a higher overhead than comparable binary protocols. For example, the regular Modbus/TCP protocol is approximately 10 times faster.

This protocol is best suited to applications which do not require continuous high speed polling, such as interfacing to ERP or production reporting systems.