Appendix B: Web Interfaces

To access the product using a browser, EM-483 waits for an Ethernet connection to port 80 and for HTTP protocol transfers. To make a connection, call the IP address of the product (the factory setting is 192.168.0.111) from the browser’s address bar. The browser displays WEB pages that allow you to read the product status, configure parameters, call the MODBUS functions, and perform file operations.

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

EM-483 supports API in two formats: JSON and XML. For example, if the IP-address of the product is “192.168.0.111”, then the JSON API 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 (in the examples below, each request starts with one of these lines, and this beginning is designated 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-483",
    "firmwareVersion": 6,
    "loginChallenge": "92uJz89fQEd62JxOW75sGtNAm"
}

XML format:

<ApiReply>
  <Type>EM-48x API</Type>
  <Version>1.1</Version>
  <Device>EM-483</Device>
  <FirmwareVersion>6</FirmwareVersion>
  <LoginChallenge>92uJz89fQEd62JxOW75sGtNAm</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

Access to MODBUS requires authorization, which can be performed in two ways:

1. Unprotected password – by sending an API request with the password string in the plainpass parameter.

2. SHA-1 protection – using the authorization offer received in the loginChallenge field. To do this, calculate the standard SHA-1 hash of the string made up of the authorization offer and password, and then send an API request with the hash string (encoded in hexadecimal form or according to the BASE-64 standard) in the lcanswer parameter.

   For example, for the EM-483 factory password “11111” and the sentence in the example above, the hash of the composite string “92uJzC89fQEdB62JxOW75sGtNAmA11111” in hexadecimal form is 28457e7fc55a67bf59caf5f73e42fd168a5fe6a3.

Upon successful authorization, the product returns the response redirecting it to the session page, for example, /1c193447/api.xml (further in the examples <API session call>), where “1c193447” is the temporary session code. If the application sending 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 in the example 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 start with <API session call> with the specified code.
status	Status	Status of MODBUS calls: “Busy” – MODBUS call is being processed, repeat the call without parameters to get the result or to send a new call; “Ready” – a new MODBUS call can be sent.

MODBUS Call Parameters

The parameters listed below are used to call MODBUS.

Parameter	Range of Values	Description
mbc_uid	0–255	Identifier of the destination device
mbc_func	1–6, 15–16	MODBUS function code. For write functions, only one value can be written including the same for 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 values to be read (from 1 to 16). For write functions – the value to be written.
dosend	0–65535	The presence of this parameter in the request with any value makes a MODBUS call with the specified parameters

MODBUS Call Response Example

The response to <API session call>?mbc_uid=111&mbc_func=3&mbc_addr=168&mbc_data=2&dosend=1 (for the EM-483 own identifier value, which is equal to the factory one “111”) – reading the Operating Time:

JSON format:

{
    "type": "EM-48x API",
    "status": "Ready",
    "modbusQueries": [
        {
            "unitID": 111,
            "function": 3,
            "address": 168,
            "data": 2,
            "response": {
                "data": [0, 408]
            }
        }
    ]
}

XML format:

<ApiReply>
  <Type>EM-48x API</Type>
  <Status>Ready</Status>
  <ModbusQuery>
    <UnitID>111</UnitID>
    <Function>3</Function>
    <Address>168</Address>
    <Data>2</Data>
    <Response>
      <Data>0</Data>
      <Data>408</Data>
    </Response>
  </ModbusQuery>
</ApiReply>

Successful MODBUS Call Response Fields

JSON	XML	Description
modbusQueries	ModbusQuery	MODBUS request
unitID	UnitID	Identifier of the destination device in the request
function	Function	MODBUS function code in the request
address	Address	Address of the register, flag, or quantized input in the request
response	Response	Response to the request
data	Data	In the request – the number of values to read or write, in the response – the data read or written

MODBUS Call Error Response Fields

JSON	XML	Description
errorInQuery	ErrorInQuery	MODBUS request error (the field is in the request instead of the response field): “Query unit ID illegal” – incorrect device ID; “Query address illegal” – invalid address; “Query data illegal” – invalid value
errorInResponse	ErrorInResponse	MODBUS response error (the field is in the request instead of the response field): “Response mismatch” – the received response does not match the request
exceptionCode	ExceptionCode	MODBUS exception code (the field is in the response instead of the data field)
exception	Exception	The MODBUS exception text corresponding to the code (the field is in the response instead of the data field)