Appendix F: Web Interfaces

To access the device using a browser, the EM-486 expects an Ethernet connection to port 80 and HTTP transmissions. To connect in the address bar of the browser, call the IP address of the device (to display the address on the EM-486 display, see section 5.3.1 of the manual). The browser displays WEB pages that allow you to read the status of the device, set parameters, call MODBUS functions and perform file operations on the memory card.

In addition, the HTTP connection can be used by other applications to automatically invoke MODBUS functions using the API.

EM-486 supports API in two formats: JSON and XML. For example, if the IP address of the device is “192.168.0.111”, then the API JSON request without parameters will look like 192.168.0.111/api.json, and the XML API will look like 192.168.0.111/api.xml (further in the examples, each request begins with one of these lines, and this beginning is referred to as <API call>).

API Response Without Parameters

An example of a response to a request is given below.

JSON format:

{
    "type": "EM-48x API",
    "version": "1.1",
    "device": "EM-486",
    "firmwareVersion": 43,
    "loginChallenge": "92uJzC89fQEdB62JxOW75sGtNAmA"
}

XML format:

<ApiReply>
  <Type>EM-48x API</Type>
  <Version>1.1</Version>
  <Device>EM-486</Device>
  <FirmwareVersion>43</FirmwareVersion>
  <LoginChallenge>92uJzC89fQEdB62JxOW75sGtNAmA</LoginChallenge>
</ApiReply>

Response Fields Description

JSON	XML	Description
(unnamed)	ApiReply	Root element of the response
type	Type	Response type (always “EM-48x API”)
version	Version	Answer version
device	Device	Device
firmwareVersion	FirmwareVersion	Firmware version
loginChallenge	LoginChallenge	Secure authorization offer (see below)

Authorization

To access MODBUS authorization is required, which can be done in two ways:

1. The unprotected password by sending an API request with a password string in the plainpass parameter;
2. With SHA-1 protection using the authorization proposal received in the loginChallenge field. To do this, compute the standard SHA-1 hash of the string composed of the authorization clause and password, and then send an API request with the hash string (encoded in hexadecimal or BASE-64) in the lcanswer parameter. For example, for the factory password EM-486 “11111” and the sentence in the example above, the hash of the compound string “92uJzC89fQEdB62JxOW75sGtNAmA11111” in hexadecimal form is “28457e7fc55a67bf59caf5f73e42fd168a5fe6a3”.

Upon successful authorization, the device returns a response with a redirection to the session page, for example, /1c193447/api.xml (hereinafter in the examples <API session call>), where “1c193447” is the temporary session code. If the application making the request does not support redirection, then the requests should be called with the redirects parameter set to “0”.

Authorization Response Example

The response to the request <API call>?lcanswer=28457e7fc55a67bf59caf5f73e42fd168a5fe6a3&redirects=0 if it was sent after the response above:

JSON format:

{
    "session": "1c193447",
    "status": "Ready"
}

XML format:

<ApiReply>
  <Session>1c193447</Session>
  <Status>Ready</Status>
</ApiReply>

Authorization Response Fields

JSON	XML	Description
session	Session	Session code. The absence of this element means that authorization is required. Authorized requests begin with <API session call> with the specified code.
status	Status	MODBUS call status: “Busy” - busy, a MODBUS call is being processed. The call should be repeated without parameters to get the result or to send a new call; “Ready” - ready, a new MODBUS call can be sent.

MODBUS Call

To call MODBUS, the following parameters are used:

Parameter	Range of Values	Description
mbc_uid	0–255	Destination device ID
mbc_func	1–6, 15–16	MODBUS function code. Only one value can be written for write functions, including multiple write functions (codes 15 and 16)
mbc_addr	0–65535	Register, flag or digital input address
mbc_data	0–65535	For read functions - the number of read values (from 1 to 16). For write functions, the value to be written
dosend	0–65535	The presence of this parameter with any value in the request makes a MODBUS call with the specified parameters

MODBUS Call Response Example

The answer to <API session call>?mbc_uid=111&mbc_func=3&mbc_addr=213&mbc_data=3&dosend=1 (for the value of the EM-486 own identifier equal to the factory default “111”) - reading the current time:

JSON format:

{
    "type": "EM-48x API",
    "status": "Ready",
    "MODBUSQueries": [
        {
            "deviceID": 111,
            "function": 3,
            "address": 213,
            "data": 3,
            "response": {
                "data": [12, 38, 25]
            }
        }
    ]
}

XML format:

<ApiReply>
  <Type>EM-48x API</Type>
  <Status>Ready</Status>
  <MODBUSQuery>
    <UnitID>111</UnitID>
    <Function>3</Function>
    <Address>213</Address>
    <Data>3</Data>
    <Response>
      <Data>12</Data>
      <Data>38</Data>
      <Data>25</Data>
    </Response>
  </MODBUSQuery>
</ApiReply>

Successful MODBUS Call Response Fields

JSON	XML	Description
MODBUSQueries	MODBUSQuery	MODBUS request
unitID	UnitID	Destination device identifier in the request
function	Function	MODBUS function code in request
address	Address	Address of register, flag or discrete input in request
response	Response	Reply to request
data	Data	In a request - the number of read values or a written value, in a response - read or written data

MODBUS Error Response Fields

JSON	XML	Description
errorInQuery	ErrorInQuery	MODBUS request error (field in request instead of response field): “Query device ID illegal” - invalid device ID; “Query address illegal” - invalid address; “Query data illegal” - an invalid value
errorInResponse	ErrorInResponse	MODBUS response error (field in request instead of response field): “Response mismatch” - The accepted response does not match the request
exceptionCode	ExceptionCode	MODBUS exception code (field in response instead of data field)
exception	Exception	Exception MODBUS (field in response instead of data field, values are listed in table 5.2 of the manual)